简介：这是一份面向Windows安装包开发者的WiX工具集3.11版二进制资源包，通过XML语言定义安装过程，用于创建、定制和验证MSI安装程序。压缩包大小约32.77MB，主要包含一系列以.exe.config结尾的.NET框架配置文件，分别对应WiX工具链中的多个命令行工具：candle编译器负责将源文件编译为中间对象，light链接器负责生成最终安装包，heat用于收集文件系统资源，dark用于解析现有安装包，lit用于打包库文件，torch用于处理补丁合并。这些配置用于调整各工具的命令行默认参数、日志记录级别和输出目录，从而让构建流程更贴合具体项目。已有465人学习下载，适合希望系统掌握WiX组件分工与配置细节的中高级开发者。借助这些文件，读者可以理顺安装包构建链路中每个工具的职责，并通过修改配置文件优化打包行为，为自动化构建和问题排查提供有价值的参考。
1. 拿到 wix311-binaries.zip 之前，先搞懂它在构建链里的位置
wix311-binaries.zip 是 WiX Toolset v3.11 的官方二进制发布包，解压即得一套能在命令行直接调用的 MSI 构建工具链。它常被塞进内网制品库，当作构建机上锁定的固定版本；本地开发不用装 Visual Studio 插件，也能编译出可安装的 Windows 安装包。它解决的痛点是：在没有 Visual Studio、没有 WiX VSIX 扩展的纯净 Windows 环境里，也能写出、编译、链接并验证一个完整 MSI。适合维护安装工程、批量部署脚本和 CI 流水线的工程师。下面从一台只有远程桌面的 Windows Server 起手，用这个 zip 里的原生命令做出最小 MSI。
2. 解压与准备：一个 zip 就能凑齐一条完整工具链？
很多 CI 团队不愿意把 WiX 做成“每个人都去装一个 VS 插件”的状态，原因很直白：那样你没法锁定工具链版本。而 wix311-binaries.zip 正好解决版本一致性的问题——把压缩包放进内网制品库，构建脚本固定引用这个路径，谁改版本谁负责，构建结果可重复。所以请不要嫌它“不够正规”，这在交付环境里反而是最稳的一种做法。
2.1 binaries 压缩包里到底装了什么：candle、light、heat 三者分工
用 7-Zip 解开后，能看到一组 exe、dll、xsd schema 和资源目录。第一眼看得很乱，但真正需要关心的只有三个主程序和几个扩展库：
| 文件 | 职责 | 使用时机 |
|---|---|---|
| candle.exe | 把 .wxs 源文件编译成中间格式 .wixobj | 每次构建 |
| light.exe | 把 .wixobj 与扩展库链接成 .msi/.msm | 每次构建 |
| heat.exe | 扫描目录或 VS 项目，自动生成 .wxs 片段 | 发布前同步文件清单 |
| WixUIExtension.dll | 提供标准安装向导界面 | 需要图形界面时 |
| WixUtilExtension.dll | 文件搜索、目录搜索、服务操作等辅助函数 | 做依赖检测时 |
| WixNetFxExtension.dll | 检测 .NET Framework 版本并转为安装前提条件 | 目标机装有 .NET 时 |
| schemas*.xsd | 为 wxs 提供 XML 校验与编辑器提示 | 写代码过程中 |
candle 负责把 .wxs 编译成 .wixobj，light 再把 .wixobj 链接成 .msi/.msm，heat 则反过来——从文件目录或 Visual Studio 项目里抓取现有文件，自动生成 .wxs。
注意：不要只复制单个 exe 使用。candle.exe 和 light.exe 运行时要加载同目录下的扩展 DLL 和本地化资源，缺了会在启动阶段或链接阶段报一堆不明所以的错。迁移到新机器时请整个解压目录一起拷，这也是 wix311-binaries.zip 最容易被误解的地方。
2.2 解压目录和运行方式：两个我认为必须先定下来的约定
第一个约定是路径不放进系统 PATH。平时直接用全路径调用最省心；非要写进 PATH 的话，确保这台机器上只有这一个 WiX 版本出现在前面。WiX 4 的命令行参数与 3.x 有不少差异，环境里同时存在两个版本时，脚本失败的方式极其隐蔽——你会先怀疑是自己的 wxs 写错，折腾一小时后才发现 PATH 指到了另一个 exe。
REM 固定工具链变量，后续命令统一引用 set WIX=C:\ci\tools\wix311 "%WIX%\candle.exe" -nologo install.wxs第二个约定是解压路径避开空格。虽然 exe 本身能处理带空格路径，但构建脚本一旦经过 PowerShell、GitLab Runner 或 Jenkins 的 shell 包装，引号嵌套就很容易出问题。建议放在 C:\wix 或 C:\ci\wix311 这种短目录下。我吃过亏：把工具链放在带空格的 “CI Tools” 目录后，light 链接长路径源文件时总要在这类地方多耗半天时间。
2.3 三条命令验证工具链：candle、light、heat 一个都不能少
解压完不要直接开写，先用三个 -? 把可执行文件挨个敲一遍，确认依赖库完整：
C:\wix\candle.exe -? C:\wix\light.exe -? >NUL && echo LIGHT_OK C:\wix\heat.exe -? >NUL && echo HEAT_OK如果刚解出来的 exe 报 0xc000007b（应用无法正常启动），先检查这台机器有没有装 Visual C++ 2015-2022 Redistributable，x64 和 x86 两个版本最好都装上。这个问题在 Windows Server Core 上尤其常见，因为它是精简安装，不会预装 VC++ 运行库。补装后不用重启，再跑一次 -? 就能看到正常帮助输出。
顺手可以看一下三个 exe 的版本号是否一致。candle -? 的第一行会显示 3.11.x；如果三个工具版本号对不上，说明混用了不同 zip 里的文件，这种情况在下载缓存覆盖不干净时很常见。
3. 用 candle + light 把 wxs 编译成 MSI：最小可复现流程
MSI 的安装模型和普通脚本安装不同：它不是“把文件拷过去再改注册表”，而是以一个安装数据库来记录目录结构、组件和功能。理解这个模型以后，你会发现很多异常行为都能从逻辑上推断出来，而不是靠玄学。
3.1 从零写一个最简 .wxs：Product、Package、Feature、Component 四件套
下面这个文件是最小可用的 wxs。它把源码目录放到了安装树的 Program Files 下，注册了两个文件，并挂到一个名为 MainFeature 的 Feature 上：
<?xml version="1.0" encoding="UTF-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Product Id="*" Name="DemoApp" Language="1033" Version="1.0.0.0" Manufacturer="Example Corp" UpgradeCode="3E2E5A1E-0000-4000-8000-000000000001"> <Package InstallerVersion="500" Compressed="yes" InstallScope="perMachine"/> <MajorUpgrade Schedule="afterInstallInitialize" DowngradeErrorMessage="请先卸载旧版本"/> <Media Id="1" Cabinet="demo.cab" EmbedCab="yes"/> <Feature Id="MainFeature" Title="DemoApp" Level="1"> <ComponentGroupRef Id="AppComponents"/> </Feature> </Product> <Fragment> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFilesFolder"> <Directory Id="INSTALLFOLDER" Name="DemoApp"/> </Directory> </Directory> <ComponentGroup Id="AppComponents" Directory="INSTALLFOLDER"> <Component Id="MainExecutable" Guid="*"> <File Id="DemoExe" Source="bin\Release\demo.exe" KeyPath="yes"/> <File Id="DemoConfig" Source="bin\Release\demo.exe.config"/> </Component> </ComponentGroup> </Fragment> </Wix>Product 定义产品身份；Package 定义安装器行为和权限；Feature 是对用户可见的功能入口；Component 则是 MSI 跟踪文件、注册表项、服务的最小单位。目录树放在 Fragment 里，编译时会被链接器合并进最终数据库。
这里有两处发布前必须处理的点：UpgradeCode 是企业里标识“同一产品家族”的关键，一旦发布就不能再改；Guid="*" 表示让编译器每次生成新组件 GUID，严格说这只适合开发期测试，正式发布时最好改成固定 GUID。Component 没有指定 KeyPath 时，MSI 会默认给第一个 File 分配 KeyPath 角色，卸载和修复都依赖它。
3.2 candle 编译与 light 链接：命令、参数与产物
wxs 写好后进入构建环节。candle 是编译阶段，它把 XML 解析成一个或多个 .wixobj，中间产物仍然是 XML 风格的描述，但包含了 GUID 分配、目录解析和引用关系：
REM 编译 install.wxs 到 build 目录 mkdir build C:\wix\candle.exe install.wxs -o build\install.wixobj然后 light 负责链接：把 wixobj、扩展库和资源文件打包成最终 MSI，同时生成 CAB 压缩包。加不加 -ext 差别很大，不加 WixUIExtension 时 MSI 没有任何标准界面，安装全程无声无息：
REM 链接：wixobj -> msi，并挂载标准 UI 扩展 C:\wix\light.exe build\install.wixobj -o DemoApp.msi -ext WixUIExtension.dll如果希望安装时有一个最简单的“下一步”向导，还需要在 wxs 的 Product 节点内加一段 UI 引用，光加扩展 DLL 是不够的：
<UI> <UIRef Id="WixUI_Minimal"/> </UI>candle 还有几个日常会固定带的参数：-arch x64 会改变默认 ProgramFilesFolder 的选择；-d 用来传入外部定义，例如 -dOutputPath=bin\Release；-o 指定输出文件位置，建议显式给 build 目录，别让中间产物散落在 wxs 旁边。light 更常用的是 -b，它把源文件的查找根目录固定下来，等用到 heat 生成片段时，-b 几乎是必需品。
3.3 让 MSI 真正能装、能卸：ProductId、UpgradeCode 与版本控制
wxs 里决定安装包能不能正常升级的是三样东西：ProductId、UpgradeCode、Version。开发期把 ProductId 写成 "*" 没有问题，每次构建会生成不同 GUID，适合临时测试；但正式发布版本建议写成固定 GUID，并固定一个版本号，方便日志回溯。
UpgradeCode 则代表产品家族的唯一标识。一台机器上同族的 MSI 通过 UpgradeCode 建立升级关系；改了它等于告诉 Windows Installer“这是另一款软件”，旧版本不会被新版本覆盖。常见翻车现场是：为了新版本“干净”，把 UpgradeCode 重新生成了一遍，结果每个版本都像是独立软件，卸载时留下好几个残留入口。
版本号是四段式，每段范围 0 到 65535。MajorUpgrade 会按后三段做比较，所以 1.0.0.1 升级到 1.0.0.2 是合法的，但 1.0.1 降到 1.0.0 会被 DowngradeErrorMessage 拦下来。之前有个同事把版本号写成了 1.0 而不是 1.0.0，链接时 candle 直接拒绝编译，报错信息里明确要求四段版本。
4. wix311-binaries 实战避坑：4 个最常见的翻车现场
用 wix311-binaries.zip 给公司产品做安装打包时，下面这四类问题我基本每个项目都会碰到。它们不写进任何一本书，却能真正消耗掉一个下午。
4.1 注册表写入 64 位程序却落在 WOW6432Node
现象：构建的是 x64 MSI，程序启动后读取 HKLM\Software\DemoApp 下的配置，结果读到的是空值。打开注册表编辑器一看，值被写进了 HKLM\Software\WOW6432Node\DemoApp。
原因：MSI 默认把注册表操作映射到 32 位视角。64 位程序读 64 位注册表视图，自然看不见 32 位视图里刚写入的值。
解决：在 RegistryValue 元素上显式加 Win64="yes"：
<Component Id="RegistryEntries" Guid="*"> <RegistryValue Root="HKLM" Key="Software\DemoApp" Name="InstallDir" Value="[INSTALLFOLDER]" Type="string" Win64="yes" KeyPath="yes"/> </Component>如果连安装目录都想固定到 64 位 Program Files，还要把目录树里的 ProgramFilesFolder 换成 ProgramFiles64Folder，否则 x64 应用会被装进 Program Files (x86)，后面又得补一堆兼容性处理。
4.2 升级安装后“程序和功能”里出现两个卸载入口
现象：从 1.0 升级到 1.1，装完发现旧版本还留在“程序和功能”里，两个入口都能卸载。
原因：要么没有写 UpgradeCode，要么 UpgradeCode 在发版时被改过。没有 UpgradeCode 时 MSI 无法识别新旧版本之间的亲属关系，MajorUpgrade 也无从谈起。
解决：在 Product 上固定 UpgradeCode，并显式加入 MajorUpgrade 元素。WiX 3.11 里我用的是 Schedule="afterInstallInitialize"，它会在安装初始化之后先移除旧版本相关资源，再写入新版本。改完后验证路径也简单：先装 1.0，再装 1.1，安装结束去“程序和功能”里确认只剩一个入口。
4.3 heat 生成的组件 ID 和手写组件 ID 撞车，light 报 duplicate symbol
现象：链接阶段 light 报 duplicate symbol Component/xxx，但这个 Component 只在一份 wxs 里手写过，看起来根本不该有冲突。
原因：heat 生成组件 ID 时默认基于源代码路径和文件名的 hash。同一份文件被 heat 扫描两次，或扫描目录里嵌套了另一个已扫描子目录，就会产生相同 ID；如果你同时有手写片段，撞车概率更高。
解决：heat 命令固定加 -sfrag -srd 两个开关。-sfrag 让每个目录生成独立的 Fragment，-srd 去掉 SourceDir 根目录，避免把构建机器的绝对路径带进产物。链接前先用 findstr 快速查一遍生成的 wxs 里有没有重复 Component Id，确认干净再进 light。
4.4 用了相对路径，candle 一进 CI 就报 1001 找不到 wxs
现象：本机命令行下执行得好好的，换到 CI 流水线后 candle 报 error 1001，说找不到 install.wxs。
原因：CI 里工作目录不是你猜的那个目录。本机能跑是因为你的终端刚好站在 wxs 所在目录；流水线里默认工作区可能指向仓库根目录、构建产物目录或者某个临时工作区。
解决：在脚本开头显式切换工作目录，再调用绝对路径的 candle：
cd /d "%WORKSPACE%" "%WIX%\candle.exe" install.wxs -o build\install.wixobj这个坑看起来很小，但排错成本极高：candle 报错信息没有告诉你它尝试过哪些相对路径，只会丢一个找不到文件。所以我在所有构建脚本里的统一约定是：先 cd，再执行，绝不依赖调用者的当前目录。
5. 再往前走一步：heat.exe 自动收集文件，并把安装包验证写进日常
5.1 heat.exe 从输出目录生成 wxs 片段
产品目录里文件会有几十个，手工维护 wxs 不现实。常见做法是用 heat 扫描发布目录，自动生成组件组：
REM 扫描发布目录，生成组件组 WebComponents C:\wix\heat.exe dir bin\publish ^ -cg WebComponents ^ -sfrag -srd ^ -gg -g1 ^ -template fragment ^ -out generated\publish.wxs参数含义：-cg 指定收集到的组件组名称；-sfrag 让每个目录各生成一个 Fragment；-srd 不生成 SourceDir 根目录；-gg 为组件生成 GUID；-g1 在组件级别补充 GUID；-template fragment 表示输出的是可被主工程引用的片段；-out 指定输出路径。生成后的 publish.wxs 不要直接当黑匣子用，先打开看一眼目录结构是否符合预期。
5.2 在 CI 流水线里把主工程与收集片段串起来
heat 生成的片段要和手写的 install.wxs 一起编译、一起链接。我一般在流水线里写成这样：
REM 编译主工程与 heat 生成的片段 "%WIX%\candle.exe" install.wxs generated\publish.wxs -arch x64 -o build\ ^ -ext WixUtilExtension.dll REM 链接时用 -b 指回源文件根目录 "%WIX%\light.exe" build\install.wixobj build\publish.wixobj ^ -b bin\publish ^ -ext WixUIExtension.dll ^ -ext WixUtilExtension.dll ^ -o artifacts\DemoApp.msi-b 参数在这里很关键：heat 生成的片段里 Source 属性通常保存的是相对路径，light 需要靠 -b 找到 bin\publish 下的真实文件。漏掉它时，light 会报找不到源文件，但报错里给出的路径往往和实际布局差一层，非常误导人。
5.3 验证安装的一条血泪经验：永远保留 msiexec 日志
最后建议在每次流水线构建后顺手做一次安装与卸载验证，并保留完整日志：
msiexec /i artifacts\DemoApp.msi /l*v build\install.log msiexec /x FIXED-PRODUCT-GUID /l*v build\uninstall.log部署报 1603 或回滚时，第一动作不是看代码，而是翻日志：安装日志里搜 “Return value 3” 可以看到执行序列在哪一步失败；搜 “MainEngineThread is returning 1603” 说明是安装引擎级回滚。没有日志的排查全是玄学，这是我用几次交付延期换来的教训。把这个习惯固化进日常构建后，安装包问题从“整个小组一起猜”变成了“两分钟定位”。希望帮到你。
本文还有配套的精品资源，点击获取
