wix311-binaries.zip离线构建MSI：从解压配置到避坑指南

简介：WiX（Windows Installer XML）是构建 Windows 安装程序的开源工具集，wix311-binaries.zip 即其 3.11 版二进制文件包，面向需要创建或维护 MSI 安装包的开发人员与运维人员。压缩包约 32.77MB，包含 dark、heat、lux、melt、pyro、light、candle、lit、torch、smoke 等工具的 10 个 .exe.config 配置文件，分别对应 MSI 元数据提取、资源自动收集、非 XML 脚本转译、MSI 转 WiX 源码、链接器、编译器、库打包及数据库修补等环节；其中 candle 负责把 .wxs 编译为 .wixobj，light 负责链接生成最终 MSI，是工具链的核心。对于使用 WiX 构建安装程序的开发者，通过了解并调整这些配置文件中的日志记录级别、默认输出目录、命令行参数默认值等选项，可以更灵活地定制构建流程，遇到编译或链接报错时也能更快定位问题。对于需要从既有 MSI 反向分析、自动化收集文件资源或制作补丁的进阶任务，这套配置文件还提供了 torch、dark、heat 等环节的默认行为参考。目前已有 465 人学习下载，适合具备一定 WiX 或 MSI 基础、希望深入掌握官方工具链行为的用户。

1. wix311-binaries.zip 到底是个什么包：离线构建 MSI 的第一块垫脚石

wix311-binaries.zip是 WiX Toolset 3.11 的预编译二进制集合，它解决的是 Windows 交付场景里很具体的痛点：在没有外网、不方便跑安装向导的内网构建机上，把.wxs源文件编译、链接成可分发的 MSI 安装包。很多人解压完这个 zip 以为马上就能用，结果candle.exe一闪而过，或者light.exe抛出一串 LGHT 开头的错误，问题往往不在工具本身，而在解压后的目录布局、环境变量和调用方式上。这篇文章按“拆包 → 配环境 → 写 wxs → 避坑 → 验证”的顺序推进，适合交付工程师、CI 维护者和研究 Windows Installer 生成链路的开发者照着做。

2. 为什么是 WiX 3.11 二进制包：从 candle 到 light 的 MSI 生成链路

2.1 一条 wxs 要经历什么才变成 MSI：candle 与 light 的定位

MSI 不是简单把文件压缩到一起，它本质上是一个关系型数据库，里面装着 File 表、Component 表、Feature 表、Directory 表这些结构化信息。WiX 的价值，就是让你用 XML 写安装逻辑，再通过工具链把这个 XML 变成 MSI 数据库文件。整个转换分两段完成：candle.exe负责把.wxs预处理并编译成.wixobj中间对象；light.exe负责把.wixobj和扩展模块、资源文件链接起来，生成最终可安装的 MSI。

这个模型和 C 语言“编译 + 链接”非常像。candle相当于编译器，把源码变成目标文件；light相当于链接器，把目标文件组合成最终可执行体。理解了这一点，你就不会把两个工具的参数搞混：candle 处理的是 XML 源文件，light 处理的是已经生成的 wixobj。很多新手一上来就在 light 命令里写.wxs路径，报错后一脸茫然，其实就是没分清这两个阶段。

很多人分不清 candle 的“预处理”和“编译”到底做了什么。预处理和 C 编译器的宏展开一个道理：-dVersion=1.0.0定义变量后，wxs 里所有$(var.Version)在真正解析 XML 之前就被替换成字面量。替换发生在 XML 解析之前，所以如果值里带引号或特殊字符，需要提前转义。编译阶段才把 XML 树转换成 MSI 表记录。light 链接时，[#DemoExe]这种文件 ID 引用才会被解析成实际路径。理解这三个阶段，很多参数错误就能自己推导出来，而不是靠试错。

我一般会先确认工具链版本再往下走。给一个最简单的检查方式：

# 解压后把 bin 目录挂到当前会话 PATH $env:Path = "C:\wix311\bin;" + $env:Path # 查看 candle 版本和用法 candle.exe -nologo -?

-nologo的作用是去掉启动横幅，让输出更适合被 CI 日志捕获。如果candle.exe -?能看到 3.11 字样，说明文件没残缺、目录权限也没问题。如果命令闪现退出，多半是杀软隔离或 .NET 运行时缺失，后面第 5 章会专门讲排查。

2.2 3.11 到底赢在哪：老模型成熟、扩展齐、迁移成本低

WiX 4.x 早就出来了，但大量项目还在用 3.11，不是守旧，是 3.11 的模型足够稳。3.11 的编译产物直接、参数肉眼可读、网上案例最多；4.x 把多个工具合并成了wix.exe子命令体系，感觉更现代，但老.wxs文件的兼容性需要重新评估。对已经跑了三五年的交付脚本来说，升级工具链带来的收益不一定高于风险。

选择 3.11 还有一个现实原因：网上绝大多数现成 wxs 示例都是 3.x 语法，很多遗留工程也建立在 3.x 之上。不少老构建机只装了 .NET Framework，没有 .NET SDK，跑 3.11 没问题，但 4.x 的wix.exe在某些环境下依赖更新的运行时。构建工具这种基础件，求稳比求新重要。

3.11 自带的扩展覆盖了绝大多数交付需求：WixUIExtension提供安装界面，WixUtilExtension提供文件搜索、注册表搜索和用户管理，WixNetFxExtension专门处理 .NET Framework 检测。用 light 时加-ext参数就能挂进去。这意味着大多数纯净交付场景不需要写 C++ 自定义动作，纯 XML 就能完成界面、服务、快捷方式和环境变量配置。

可以做一个空跑验证，确认扩展文件没有缺失：

light.exe -nologo -ext WixUIExtension -?

这个命令不生成 MSI，只是让 light 加载扩展并输出相关说明。如果扩展 DLL 缺失，输出里会明确提示文件路径问题。WiX 的扩展 DLL 本身就在二进制包的 bin 目录下，所以这个 zip 解压出来的目录不能被杀软删掉一半，否则后续全是黑匣子式报错。

2.3 拿到 wix311-binaries.zip 能拆到什么：目录布局和离线价值

以 3.11.1 的二进制包为准，解压后通常是下面这个布局，具体以你手头的压缩包为准：

离线场景下，这个 zip 的价值非常明确：不需要联网跑 WiX 安装器，不需要管理员权限安装全局组件，只需要解压到一个团队约定目录。配合构建脚本，完全断网的编译机也能出 MSI。它还顺带解决了安装版工具链版本漂移的问题——同一个压缩包解压出同样的二进制，这是可复现构建的前提。

如果你这个 zip 是从团队内部制品库拉下来的，记得把哈希校验做进构建脚本。构建机从内网拉包时校验失败，通常代表包拉取不完整，而不是 WiX 本身有问题。补丁场景还会用到torch.exe给 MSI 打 transform，生成 MSP 补丁包，这些工具都在 bin 目录里，离线环境一样能用。有一点要注意：这个包本身不附带 .NET Framework 运行时。WiX 工具链依赖 .NET Framework，Windows 10/11 和 Server 2016 以上自带 4.x，老系统比如 Server 2008 要提前确认运行时在不在位，这是换机器后最容易忽略的隐性依赖。

3. 把 wix311-binaries.zip 跑起来：解压、环境变量与第一次构建

3.1 解压与目录约定：把 bin 挂到 PATH 上

拿到wix311-binaries.zip后，先别急着双击进压缩包看文件，直接解压到一个不含空格和中文的目录，比如C:\wix311或D:\build\tools\wix。路径里有空格时，后续脚本引号处理容易出错，这是很多人踩过的小坑。

我一直建议把工具链放在D:\build\tools这类目录，而不是C:\Program Files (x86)\WiX Toolset 3.11。前者路径干净，后者目录名带括号和空格，PowerShell 脚本里到处要转义，还容易和安装版 WiX 混在一起。工具链版本在构建脚本里用参数声明，比如$WixRoot = 'D:\build\tools\wix'，后续调用全部基于这个变量，换机器时只改一个地方。

我一般不会把它解压到用户目录或临时目录，因为构建脚本要长期引用，目录一旦被清掉，下一轮构建就会莫名失败。解压命令和基本环境设置如下：

# 解压到 C:\wix311，-Force 表示已存在则覆盖 Expand-Archive -Path .\wix311-binaries.zip -DestinationPath C:\wix311 -Force # 当前会话里临时挂环境变量，不影响系统全局 $env:WIX = "C:\wix311" $env:Path = "C:\wix311\bin;" + $env:Path # 确认核心工具在位 Test-Path "C:\wix311\bin\candle.exe" Test-Path "C:\wix311\bin\light.exe"

Expand-Archive的-Force参数在重复解压时很有用，能避免“目标目录已存在”这类中断。为什么不建议直接改系统环境变量？一方面，构建机可能装了不同版本的 WiX 工具链，全局 PATH 一旦指向错误版本，整条流水线都要遭殃；另一方面，公司电脑的权限策略经常禁止修改系统环境变量。用脚本在每次构建开始时设置会话级变量，更可控也更容易排查。

接着做一次最小验证，输出工具版本，确认解压没有被杀软截断：

(Get-Item "C:\wix311\bin\candle.exe").VersionInfo | Select-Object FileVersion, ProductVersion

如果这里输出的版本号不是 3.11.x，那说明解压的可能不是本压缩包，或者被其他工具版本覆盖了。常见做法是在构建脚本开头强制断言版本，跑错直接退出，而不是等 MSI 构建到一半才暴露问题。

3.2 用 candle + light 构建第一个 MSI：命令解读与参数说明

现在手写一个最简单的 wxs。它只做一件事：把demo.exe装到 Program Files 下，并创建一个可卸载的安装项。这是后面所有复杂配置的起点。

<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Product Name="DemoApp" Manufacturer="MyCompany" Language="1033" Version="1.0.0" UpgradeCode="12345678-1234-1234-1234-123456789012"> <Package InstallerVersion="500" Compressed="yes" Platform="x64"/> <MediaTemplate EmbedCab="yes"/> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFiles64Folder"> <Directory Id="INSTALLFOLDER" Name="DemoApp"> <Component Id="MainApp" Guid="*"> <File Id="DemoExe" Source="demo.exe" KeyPath="yes"/> </Component> </Directory> </Directory> </Directory> <Feature Id="MainFeature" Title="Main Feature" Level="1"> <ComponentRef Id="MainApp"/> </Feature> </Product> </Wix>

这段代码里有几个关键结构。Product节点是整个安装包的根，Name和Manufacturer会出现在“程序和功能”界面；UpgradeCode是产品的家族标识，后续升级替换全看它，一旦发布就不要改。Package里的InstallerVersion="500"表示要求 Windows Installer 5.0 以上，Compressed="yes"表示所有资源压缩进 MSI，Platform="x64"限定 64 位平台。

Directory树决定文件装到哪。ProgramFiles64Folder在 64 位系统里指向C:\Program Files，INSTALLFOLDER是自定义的安装根目录。Component是 MSI 中最小的安装粒度，File的KeyPath="yes"表明以该文件作为组件的关键路径，卸载时会围绕它判断组件状态。Feature是用户可见的功能项，用ComponentRef把组件挂上去。这个结构缺一不可，漏掉任何一级，light 都会在编译期提出警告或错误。

编译并生成 MSI 的命令如下：

# 编译 wxs，生成中间对象文件 candle.exe demo.wxs -out demo.wixobj # 链接中间对象，生成最终 MSI light.exe demo.wixobj -out demo.msi

candle 的-out指定输出文件路径，默认输出到当前目录。light 的-out指定最终 MSI 路径。这条命令跑完，你会得到一个包含demo.exe的安装包。可以用 msiexec 验证：

# 静默安装并记录日志 msiexec.exe /i demo.msi /qn /l*v install.log # 静默卸载 msiexec.exe /x demo.msi /qn /l*v uninstall.log

/qn表示安静模式，不弹任何界面；/l*v输出详细日志。第一次做实例验证时，日志一定要开，后面排错用的就是它。如果此时 2755 或 1603 错误出现，先翻日志里的 “Return value 3”，大部分问题都能在那里定位。

如果安装包不是单个 exe 而是几十个文件，MediaTemplate EmbedCab="yes"会全部塞进 MSI，包体积增大；换成EmbedCab="no"则可以把 cab 文件外置。外置 cab 在分发时要多带一个文件，但安装启动更快，适合非常大的资源。这里没有绝对正确，只有取舍，关键是把选择写进构建文档，别让后面接手的同事猜。

3.3 融入 CI 流水线：命令行参数与静默构建的取舍

真实交付不会每次都手敲上面两条命令。把 wix311 接进 CI 时，关键不是把命令写对，而是把重复产生的不确定性去掉。构建脚本通常长这样：

$ErrorActionPreference = "Stop" $env:WIX = "C:\wix311" $env:Path = "C:\wix311\bin;" + $env:Path # -nologo 去掉横幅；-sw1106 把特定警告降级，避免告警当错误 candle.exe -nologo -dVersion=1.0.0 product.wxs -out obj\product.wixobj light.exe -nologo -ext WixUIExtension ` obj\product.wixobj -out bin\setup.msi -pdbout bin\setup.wixpdb

-dVersion=1.0.0是 WiX 的预处理器变量，wxs 里可以用$(var.Version)引用，版本号集中在流水线参数里维护，比改 wxs 文件更干净。-pdbout把构建符号输出到 pdb 文件，以后排查“这个 MSI 是哪个 wxs 编出来的”会省很多力气。$ErrorActionPreference = "Stop"让 PowerShell 遇到第一个错误就退出，避免构建继续产出坏包。

CI 里尽可能让 candle 和 light 的输入输出都落在固定目录，比如obj/与bin/。wixobj 可以缓存，只要 wxs 没变，下次构建就不需要重新编译，能省时间。light 的-ext参数顺序也值得固定，扩展加载顺序会影响最终行为，流水线里不要乱调。

构建脚本最好能自动引入 wix311-binaries.zip。比如在 CI 的 PowerShell 步骤开头检查C:\wix311\bin\candle.exe是否存在，不存在就从一个内部制品地址解压。这样新构建机第一次跑流水线不需要手工部署，排错也少一个环节。不要在脚本里直接写死公网下载，离线构建环境没有外网，内部制品库才是正道。这个“先探测、后拉取、再校验”的套路，能避免三分之二的“换机器就构建失败”类问题。

4. 从零写一个能卸载干净的 Product.wxs：文件、服务、快捷方式与升级路径

4.1 最小骨架里藏的三个绑定：Directory、Component 与 Feature

第 3 章的骨架能跑，但离“可交付”还差得远。工程上真正影响交付质量的是三类绑定：目录树决定安装位置，组件决定文件和注册表项的归属，功能决定用户看到什么。三者一旦错位，卸载时就会留下大量残留。

先看目录树。TARGETDIR是树的根，ProgramFiles64Folder、ProgramMenuFolder、CommonAppDataFolder这些都是 WiX 预定义的系统目录。把文件挂到哪个目录，决定它装在 Program Files 还是其他位置。再看组件。一个 Component 内可以有多个File、RegistryValue、Shortcut，这些对象在安装时一同提交、卸载时一同移除。把安装逻辑上要一起消失的对象放进同一个 Component，是卸载干净的基本前提。最后是 Feature。Feature 是用户可勾选的安装项，组件通过ComponentRef挂接到 Feature，安装时才会生效。

常见的反面案例是为了写字少，把 20 个文件每个放一个 Component。卸载时 MSI 逐个处理，文件多、组件多，出错率也随之上扬。更合理的方式是按逻辑切割：一个可执行文件加上它依赖的 dll 放一个 Component，配置文件单独一个 Component，快捷方式和开始菜单目录单独一个 Component。这样既清晰，又容易保证卸载没有残留。

我通常会在设计阶段就把分组列成表格，评审通过再写 wxs：

配置类文件单独成组件，还能在升级时利用 MSI 的覆盖规则控制是否覆盖用户已改过的配置，这是把配置和服务混在一个组件里做不到的。注意Component的Guid="*"会在编译时基于路径自动生成，但路径一旦变化 GUID 就变。正式项目建议生成固定 GUID 后手写进去，这个规则直接影响升级和卸载，别图省事。

4.2 注册服务与快捷方式：把“部署动作”写进 Component

很多交付包不止是“拷文件”，还要注册 Windows 服务、创建快捷方式、写入注册表。这些动作在 WiX 里不是自定义脚本，而是组件下的一组子元素。以注册服务为例：

<Component Id="DemoService" Guid="*"> <File Id="DemoSvcExe" Source="demo-service.exe" KeyPath="yes"/> <ServiceInstall Id="InstallDemoService" Name="DemoSvc" DisplayName="Demo Service" Description="Demo background service" Type="ownProcess" Start="auto" ErrorControl="normal"/> <ServiceControl Id="ControlDemoService" Name="DemoSvc" Start="install" Stop="both" Remove="uninstall" Wait="yes"/> </Component>

ServiceInstall在安装时创建服务，Type="ownProcess"表示独立进程服务，Start="auto"指开机自动启动。ServiceControl控制服务生命周期，Start="install"表示安装时启动服务，Stop="both"表示安装和卸载都停止服务，Remove="uninstall"表示卸载时删除服务。Wait="yes"让安装程序等待服务状态变化完成，避免刚启动就被下一步操作打断。

快捷方式要放到实际会驻留它的目录组件下。开始菜单的快捷方式，通常挂在ProgramMenuFolder下，并且要配合RemoveFolder在卸载时清掉目录本身：

<Directory Id="ProgramMenuFolder"> <Directory Id="ProgramMenuDir" Name="DemoApp"> <Component Id="StartMenuShortcut" Guid="*"> <Shortcut Id="AppShortcut" Name="Demo App" Target="[#DemoExe]" WorkingDirectory="INSTALLFOLDER"/> <RemoveFolder Id="RemoveProgramMenuDir" On="uninstall"/> <RegistryValue Root="HKCU" Key="Software\MyCompany\DemoApp" Name="installed" Type="integer" Value="1" KeyPath="yes"/> </Component> </Directory> </Directory>

Target用[#DemoExe]这种语法引用组件里的文件，MSI 安装后会自动解析为实际路径。Shortcut自己不能作为 KeyPath，所以补一个RegistryValue作为组件的关键路径，这是很多新手漏掉的地方，没有 KeyPath 的组件会在 light 阶段报警告。RemoveFolder负责在卸载时删除空目录，否则开始菜单里会留下一个空文件夹。

核心逻辑是：服务、快捷方式、注册表项不是独立的安装动作，而是组件的一部分。把它们放进同一个 Component，卸载时才能一起消失。反过来，如果把服务单独放一个组件，文件单独放一个组件，卸载顺序稍有变化，服务删了但文件还占着，或者反过来，都是麻烦。

4.3 升级与卸载路径：UpgradeCode 的边界

升级是交付里最容易被“能用就行”糊弄过去的环节。安装包做完第一版，后续出了 1.1、2.0，老用户要能直接覆盖安装而不是先卸载旧的。WiX 3.11 里负责这件事的是UpgradeCode和MajorUpgrade。

UpgradeCode放在Product元素上，同一个产品的所有版本必须共用同一个UpgradeCode。MajorUpgrade元素声明了大版本升级策略：

<MajorUpgrade DowngradeErrorMessage="A newer version of this application is already installed."/>

加上这一行后，新版本 MSI 安装时会检测同一UpgradeCode下是否有旧版本，有就自动先卸载旧版本再装新的。如果用户试图安装比现有版本更旧的包，安装会中止，并提示上面这句错误信息。这是升级路径的“后悔药”——老用户不需要知道手动卸载，直接跑新包就行。

升级检测的触发点其实在安装启动早期。Windows Installer 会根据UpgradeCode搜索已安装产品，找到后读取版本号，与当前包的Version比较，再按MajorUpgrade的配置决定是替换还是禁止。搜索范围默认包含机器安装和当前用户安装，常见误区是只测当前登录用户的安装，导致其他账户装的旧版本没有被替换。这种问题在测试环境很难复现，因为测试机通常只有一个账户。

这里有个边界：UpgradeCode一旦发布给用户，就不应该再变。某次交付把 UpgradeCode 换掉了，后果是所有老用户都变成“另一个产品”，新版本无法自动替换旧版本，用户机器上可能出现两个安装项。同样，Component GUID 也不能在发布后更改，否则升级时新老组件无法关联，旧文件残留在磁盘上。很多“升级不干净”的工单，追到根上都是 GUID 或 UpgradeCode 在某个小版本里被顺手改了。

验证升级行为有个固定套路：在一台干净虚拟机里先装 1.0.0，再直接运行 1.0.1 的 MSI，确认安装完成后程序版本是新的、旧的安装目录没有残留、“程序和功能”里只有一个安装项。这一步如果跳过，升级问题通常要等用户报障才会被发现。

5. 避坑记录：wix311 构建 MSI 的五个高频翻车点

5.1 杀软把解压后的 exe 隔离，candle.exe 一闪而过

现象：解压完 wix311-binaries.zip 后，执行candle.exe -?没有输出，进程闪退，或Test-Path显示文件存在但运行被拒绝。

原因：压缩包里的二进制文件被 Windows Defender 或其他终端安全软件隔离。这类工具是命令行程序，没有安装器签名，离线环境更容易被误判。

解决：解压后先比对哈希，确认文件没被污染，再在策略允许的情况下把解压目录加入杀软排除项。哈希对比命令：

# 计算本地文件哈希，与发布页给出的 SHA256 比对 Get-FileHash "C:\wix311\bin\candle.exe" -Algorithm SHA256

不要为了图省事关掉整个系统的 Defender 排除，尤其是公司机器。更稳妥的做法是在构建机上单独建一个工具目录，加入排除清单，目录只放受控工具，不放业务文件。从那以后，我解压任何构建工具包的第一件事都是算哈希，而不是先运行它。

5.2 light 报 LGHT0103：找不到文件或路径

现象：light 执行时抛错，类似error LGHT0103 : The system cannot find the file ...，但 candle 已经成功产出 wixobj。

原因：wxs 里File元素的Source写的是相对路径，而 light 是在另一个工作目录执行，导致路径解析不到。常见于 CI 里把构建命令放在仓库根目录，而 wxs 在子目录。

解决：把Source路径改成相对于 wxs 文件所在目录，或者用预处理变量在命令行注入绝对路径。例如：

<File Id="DemoExe" Source="$(var.SourceDir)\demo.exe" KeyPath="yes"/>

调用时用-dSourceDir传入：

candle.exe -dSourceDir=C:\project\bin -nologo product.wxs -out obj\product.wixobj

还有一条经验：不要在 wxs 里写死盘符绝对路径，比如D:\myapp\demo.exe。换构建机就崩，而且排查时不会第一时间联想到路径写死。把可变路径全部收口到预处理变量，才是长期可维护的做法。SourceDir的默认解析规则是相对于 wxs 所在目录，但 CI 的工作目录不一定等于 wxs 目录，所以显式用变量传值是最稳的。

5.3 升级装完，旧文件还在磁盘上

现象：1.0.1 安装完成后，用户目录或安装目录下仍然留着 1.0.0 的文件，甚至旧服务还在运行。

原因：比较常见的有三种。Component GUID 在发布后被改动；卸载流程里没有RemoveFolder或没有停止服务；MajorUpgrade没有配置，新版本直接把文件装进同一目录，而旧组件没有被标记移除。

解决：升级前先检查 GUID 稳定性。wxs 里每个发布过的Component的Guid要保持不变，新增组件用新 GUID，已销毁的组件不要复用。服务类组件要保证ServiceControl的Remove="uninstall"存在。最后确认Product上的Version严格递增。最好把 1.0.0、1.0.1 的 MSI 都留一份，在干净机器上做回归验证，不要只升级不卸载，也不要只卸载不升级。

5.4 中文文件名在安装后乱码

现象：wxs 源文件里写了中文文件名或中文 Manufacturer 名称，构建不报错，但安装完成后创建的文件名或快捷方式显示乱码。

原因：WiX 3.11 的解析器对 wxs 文件的编码比较敏感。文件保存为不带 BOM 的 UTF-8 时，中文字符可能被按 ANSI 解析，输出到 MSI 后就是乱码。这是典型的环境相关坑，本机正常，CI 或者其他语言环境的机器上就变样。

解决：把 wxs 保存为带 BOM 的 UTF-8。用 PowerShell 统一转一下再提交：

# 读取原文件，以 UTF-8 带 BOM 写回 $content = Get-Content -Raw -Encoding UTF8 .\product.wxs [System.IO.File]::WriteAllText( (Resolve-Path .\product.wxs), $content, (New-Object System.Text.UTF8Encoding $true) )

写完后可以通过文件首字节确认 BOM 存在。Visual Studio 默认带 BOM，VS Code 需要手动切换编码。只要这个文件被 Git 等工具转过编码，就要重新检查，否则乱码会在升级时卷土重来。这个问题在中文团队里出现频率很高，建议直接把“带 BOM 保存”写进仓库的编码规范。

5.5 MSI 安装失败：只有弹窗，没有日志

现象：用户双击 MSI 安装到一半回滚，提示错误码 1603 或 2755，没有更多信息，无法判断是哪个组件或动作失败。

原因：MSI 默认不输出详细日志。错误弹窗只给结果不给过程，而真正失败的自定义动作、文件安装、注册表写入全在日志里。没有日志等于让用户当排错员。

解决：安装时要求带上详细日志：

msiexec.exe /i demo.msi /l*v install.log /qn # 安装失败后从日志里找关键错误 Select-String -Path install.log -Pattern "Return value 3|CustomAction|Error [0-9]+"

/l*v是全量详细日志，/qn静默安装。出现失败后，先搜Return value 3，这表示某个操作返回失败码 3；再往日志前面翻，定位到对应的CustomAction或InstallFiles阶段。把这条命令写进交付文档，回滚问题的排查时间至少能缩短一半。日志是 MSI 排错的第一入口，这一条我会写进每个项目的 README。

6. 把验证做成习惯：版本核对、静默安装与 heat 生成

6.1 每次构建前先核对工具链版本，再用日志跑通验证

构建工具这种“黑匣子”，最容易出问题的时刻不是第一次配置，而是换机器。新机器解压了压缩包，路径也挂了，但工具版本可能被其他软件覆盖，或者 .NET 运行时缺失。我的习惯是每次进入构建流程第一件事，用一段固定脚本断言版本：

# 核对 candle 实际文件版本 $candle = "C:\wix311\bin\candle.exe" $info = (Get-Item $candle).VersionInfo if ($info.FileVersion -notlike "3.11*") { throw "WiX 版本不符合预期: $($info.FileVersion)" } Write-Host "使用 WiX 版本: $($info.FileVersion)"

脚本写死路径和版本前缀，跑不过就直接抛异常，而不是等后面编译到一半才发现。烤出来的 MSI 再亲手跑一轮静默安装验证：msiexec /i /qn /l*v，确认退出码为 0，再检查安装目录、服务和开始菜单。这一套走完，交付包才敢往外发。

我还有一个习惯：现有目录需要打成 MSI 时，不用手写几百行 File 节点，直接用heat.exe扫描目录生成 wxs 骨架：

heat.exe dir C:\project\output -out output.wxs ` -cg MainComponents -srd -gg -ke -template:product

heat 是 WiX 自带的目录内容采集工具，-cg指定组件组名，-srd避免把根目录嵌套多层，-gg为每个文件生成 GUID。生成的 wxs 通常还需要人工整理，因为文件分组是按目录来的，不一定符合业务逻辑，但它能把工作量从“手写几百行”降到“删改几十行”。从那以后，每次接到“把目录打包成 MSI”的需求，我都强制走一遍“版本核对 → heat 生成骨架 → 手工整理组件 → 静默安装验证”的流程，出错率明显降下来。希望这份 wix311-binaries.zip 的拆解能让你少走同样弯路。

本文还有配套的精品资源，点击获取