WPF 单文件打包：ILRepack 踩坑记录

最近维护的 WPF 工具箱需要以单文件形式分发，技术栈是 .NET Framework 4.8，合并依赖选择了 ILRepack。过程不算复杂，但有几个坑值得记录。

基础配置

ILRepack 可以通过 MSBuild 任务集成到项目里，打包时自动合并。核心思路是：

• 主程序集作为 primary assembly
• 所有第三方 DLL 作为输入
• 指定目标平台与内部化选项

<Target Name="MergeDependencies" AfterTargets="Build">
  <Exec Command="$(ILRepack) /out:$(TargetDir)merged\$(TargetFileName) ..." />
</Target>

容易踩的坑

1. 资源文件丢失

WPF 的 BAML 资源在合并后可能会损坏或无法加载。解决办法是确保 CopyLocal 的依赖完整，并测试所有窗口和控件能否正常打开。

2. 反射程序集名变化

如果代码里用 Assembly.GetExecutingAssembly().GetName().Name 做逻辑判断，合并后名称不会改变；但如果依赖某个特定 DLL 的 AssemblyQualifiedName，可能会失效。

3. 调试符号

发布时建议生成 PDB，并在 CI 里单独存档，方便后续排查问题。单文件不等于没有调试需求。

发布前检查清单

• 程序能正常启动所有功能窗口
• 关键路径的日志输出正确
• 依赖项没有遗漏
• 文件大小在合理范围

ILRepack 不是银弹，但对于 net48 项目来说，仍是简单可靠的方案。