A DLL wouldn’t load on my Mac, so I built pefix

我的 Mac 上无法加载 DLL，所以我开发了 pefix

I was modding a Unity game on my Mac. The mod shipped as a .NET DLL and wouldn’t load: the IL was plain managed code, but the assembly header was stamped for Windows x64, so the runtime refused it. 我在 Mac 上修改一款 Unity 游戏时，发现该模组以 .NET DLL 形式发布，但无法加载：其 IL 是普通的托管代码，但程序集标头被标记为 Windows x64，因此运行时拒绝了它。

I opened the PE header, flipped the bits that pin it to a platform back to AnyCPU, and it loaded. That became pefix fix. 我打开 PE 标头，将锁定平台的位改回 AnyCPU，它就成功加载了。这就是 pefix 的修复功能。

The header turned out to be the easy case. The failures that actually bite are about the folder around the DLL: a dependency that never got copied, two copies of one assembly at different versions, a method a plugin calls that the shipped library no longer has. None of it shows up until something loads the assembly at runtime. 事实证明，标头问题只是小菜一碟。真正棘手的失败往往与 DLL 所在的文件夹有关：未被复制的依赖项、同一程序集的不同版本共存、插件调用的方法在已发布的库中已不存在。这些问题在运行时加载程序集之前都不会显现。

So pefix grew into a static loadability preflight over a whole folder. It reads each assembly’s metadata (no Assembly.Load) and resolves every reference, type, member, field and interface against what’s present. It only reports what it can prove statically, so it won’t fail a build on a false alarm, which is what makes it usable as a hard CI gate. 因此，pefix 演变成了一个针对整个文件夹的静态可加载性预检工具。它读取每个程序集的元数据（不使用 Assembly.Load），并根据现有内容解析每一个引用、类型、成员、字段和接口。它只报告能够静态证明的问题，因此不会因误报而导致构建失败，这使其能够作为严格的 CI 门禁使用。

dotnet tool install -g pefix pefix scan ./publish --profile publish-dir --fail-on-issue

Or as a GitHub Action (pulls the native binary, no SDK): 或者作为 GitHub Action 使用（拉取原生二进制文件，无需 SDK）：

- uses: FeathBow/pefix@v1.0.2 with: path: ./publish profile: publish-dir fail-on-issue: true

A passing scan means no static issue was found, not that load will succeed at runtime. It catches what’s provable and stays quiet otherwise. 扫描通过意味着没有发现静态问题，并不代表运行时一定能成功加载。它只捕获可证明的问题，其余情况保持静默。

MIT, single Native-AOT binary. MIT 协议，单个 Native-AOT 二进制文件。

Repo: https://github.com/FeathBow/pefix NuGet: https://www.nuget.org/packages/pefix