简介：WiX 3.11 版二进制资源包面向需要构建 Windows 安装程序的开发与运维人员，用 XML 描述安装流程，可生成 MSI 包并实现标准化打包，适合从手动打包转向自动化发布的团队，解决手工制作安装程序繁琐且难以复用的问题。压缩包约 33MB，内含多个配套配置文件，对应编译器、链接器、资源收集与元数据提取等核心工具，可用于调整命令行参数、日志级别、默认输出目录及特定转换规则；这些配置文件通常以 XML 结构保存，便于版本化管理与团队共享。已有 465 人浏览学习，适合初中级使用者理解 WiX 工具链协作方式，也可作为企业安装包团队的参考模板。通过对比这些配置，能快速掌握各工具在打包任务中的分工，构建失败或链接出错时还能从配置层面定位原因，提升安装包制作效率。
1. 为什么还在用 wix311-binaries.zip：先认清这个包里装的是什么
如果你接手过一个有点年份的安装包工程，大概率在 CI 脚本里见过这样一段：解压 wix311-binaries.zip，调用 candle.exe，调用 light.exe，最后产出一个 .msi。这个 zip 是 Windows Installer XML（WiX）3.11 版本的官方二进制发行包，里面没有安装向导、没有图形界面，只有一组命令行工具，解压即用。它解决的核心问题很简单：把用 XML 描述的安装逻辑编译成标准 MSI 安装包，全程不依赖 Visual Studio，适合在 Jenkins 这类构建环境里无人值守地跑。适合谁？维护存量 WiX 工程的人、需要在批处理里出包的人、以及不想为一个安装包需求引入整套 VS 工程的人。下面直接进入工具清单和构建流程，把参数、边界和踩过的坑一次说清。
2. 工具盘点和两段式编译：wix311-binaries.zip 里的可执行文件
2.1 从 wxs 到 wixobj 再到 msi：candle 与 light 的分工
WiX 的构建是一条两段式流水线。源文件是 .wxs（XML 格式），candle.exe 负责把它编译成 .wixobj 中间文件，light.exe 再把中间文件链接成最终 .msi。这和我们写 C 代码出 exe 的逻辑一样，也分“编译”和“链接”两步。之所以拆两步，不是因为 WiX 故弄玄虚，而是中间产物可以缓存复用：当你只改了版本号或者某个文件路径时，重跑 light 比全量编译快得多。另一个理由是，light 阶段会跑一组叫 ICE（Internal Consistency Evaluators）的一致性检查，把安装包层面的规则问题暴露在构建期，而不是等用户装到一半才报错——相当于链接器顺手帮你查了一遍“内存越界”。
wixobj 对大多数人来说是个黑匣子，不需要打开它，但你要知道它存在。candle 的常用参数我从实际使用里挑几个列出：
| 参数 | 作用 | 示例 |
|---|---|---|
| -d | 定义预处理变量，wxs 里用 $(var.xxx) 引用 | -dBuildDir=release\bin |
| -o | 指定输出 wixobj 路径 | -o build\MyApp.wixobj |
| -arch | 指定目标架构 x86/x64，影响目录变量解析 | -arch x64 |
| -ext | 加载 WiX 扩展程序集 | -ext WixUtilExtension |
| -sw | 压制指定编号的警告 | -sw1002 |
一个典型的编译命令长这样：
candle.exe -nologo -arch x64 -dBuildDir=release\bin -out build\MyApp.wixobj MyApp.wxs命令里的 -nologo 是去掉版本横幅，让 CI 日志干净一些。-arch x64 是让 WiX 按 64 位产品来解析标准目录变量，这个参数漏掉是后面踩坑章节第一名的直接原因。如果你暂时不确定架构，至少要知道有这个开关存在，不要在 32 位和 64 位之间靠猜。
2.2 不止 candle 和 light：heat、torch、pyro 与 insignia 的职责
除了核心的编译链接工具，bin 目录下还躺着几个平时不怎么碰、但特定场景必须用的工具。
heat.exe 是“目录收割器”。常见做法是：编译产物是一整个 web 静态资源目录，里面可能上百个文件，手写 wxs 把这些文件一个个列出来既不现实也没必要。heat 直接扫描目录，自动生成一个包含所有文件的 ComponentGroup 片段。典型命令：
heat.exe dir dist -cg WebFiles -gg -g1 -srd -sf -var var.DistDir -out dist.wxs参数含义：dir 是子命令，后面跟要扫描的目录。-cg 指定生成的组件组名称，供 Feature 里引用。-gg 让 heat 为每个组件自动生成 GUID，-g1 表示生成的 GUID 不带花括号。-srd 表示不生成 SourceDir 根引用，这样最终文件路径可以完全交给变量控制。-sf 的意思是不要为每个文件拆出独立 fragment，全部塞进一个组件组里，方便引用。-var var.DistDir 是这里最关键的一个：heat 会把文件源路径替换成 $(var.DistDir)... 这样的变量引用，真正路径由 candle 的 -dDistDir 参数在编译时决定。这样 wxs 里就不会出现绝对路径，换台机器构建不用改文件。
其他工具的使用频率更低：
| 工具 | 职责 | 什么时候碰 |
|---|---|---|
| candle.exe | wxs 编译为 wixobj | 每次构建 |
| light.exe | wixobj 链接为 msi | 每次构建 |
| heat.exe | 目录/项目生成 wxs 片段 | 新增成批文件时 |
| torch.exe | 合并两个 wixout、生成补丁源 | 做升级补丁时 |
| pyro.exe | 把补丁源打包成 msp | 打补丁包时 |
| insignia.exe | 引导程序数字签名收尾 | 做自定义 burn bundle 时 |
| vit.exe | 对照两个 msi 数据库差异 | 排查安装结果差异时 |
日常出包其实只用到前三个。torch 和 pyro 是“升级补丁”这条线的工具，属于另一个独立工作流，不在常规 MSI 构建里出现。第一次用 WiX 的人不需要把它们全部搞懂，但至少知道工具箱里有这些，遇到对应需求时能想起名字就够。
2.3 为什么 3.11 在 WiX 4 出来之后仍是默认选择
这是新人最容易困惑的问题：明明 WiX 4 都出了，为什么网上大量存量工程和 CI 脚本还在用 wix311。
核心原因有三个。第一，WiX 4 的底层实现换过，wixlib 格式、扩展机制、burn bundle 的结构都有变化，老工程迁移不是改个版本号那么简单，而要过一遍构建脚本和自定义扩展；对“安装包能稳定产出”这个目标来说，迁移收益不明显，成本却摆在眼前。第二，WiX 3.x 时代积累的资料量最大，遇到问题搜出来的答案大部分还是 3.x 语法，照着 3.11 写不会卡壳。第三，3.11 是 3.x 系列最后一个大版本，该修的兼容性问题修得相对干净，属于这个系列里最稳定的一代。
这不代表 3.11 完美。新项目我一般会直接看 WiX 4，但接手老工程或者要快速在 CI 里把 MSI 出出来，把 3.11 吃透更实际。工具选型这件事上，“存量兼容”往往压过“技术先进”，这句话在安装包领域尤其成立。
3. 从解压到一条命令出 MSI：最小 wxs、candle 与 light 的构建流程
3.1 解压到纯英文路径，把 bin 加进 PATH
wix311-binaries.zip 不需要安装，解压即用。但有一个硬性习惯：解压路径不要有空格、不要有中文。推荐直接解压到 C:\wix311 这种纯英文短路径。原因很实在：安装包构建工具对引号处理非常敏感，路径一旦带空格，bat 脚本里到处要加引号，少加一个就是一场排查事故。
# 解压 wix311-binaries.zip 到 C:\wix311，路径里不要有空格和中文 Expand-Archive -Path .\wix311-binaries.zip -DestinationPath C:\wix311 # 把 bin 目录临时加进当前会话的 PATH $env:Path += ";C:\wix311\bin" # 验证工具可用，第一行会输出编译器版本号 candle.exe -?如果想把 PATH 永久写入系统环境变量，用 setx 命令，但要注意 setx 会覆盖式地写用户变量，操作前先记录原值。在 CI 里我更推荐的做法是不改 PATH，直接在 bat 里用全路径引用，比如 %WIX%\candle.exe，这样脚本对执行环境无依赖。
后面的命令都以“C:\wix311\bin 已在 PATH 中”为前提。验证标准是 candle.exe -? 能打印出版本信息，看到 3.11 开头的版本号就说明包没问题。
3.2 写一个最小可过编译的 wxs：固定 ProductId，放开 ComponentGuid
wxs 是 WiX 的源文件，本质是一份 XML。下面这个文件是能通过编译的最小骨架，包含产品信息、目录结构、一个组件和一个功能：
<?xml version="1.0" encoding="UTF-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Product Id="B8A4E2C0-6D7F-4E9A-9C3D-1F2A5B7E8D4A" Name="MyApp 主程序" Language="1033" Version="1.0.0.0" Manufacturer="Example Corp" UpgradeCode="A3F9C1E8-2B4A-4D5C-9E6F-7D8A9B0C1D2E"> <Package InstallerVersion="500" Compressed="yes" /> <MediaTemplate EmbedCab="yes" /> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFiles64Folder"> <Directory Id="INSTALLFOLDER" Name="MyApp"> <Component Id="MainExecutable" Guid="*" Win64="yes"> <File Id="MainExe" Source="$(var.BuildDir)\MyApp.exe" KeyPath="yes" /> </Component> </Directory> </Directory> </Directory> <Feature Id="ProductFeature" Title="主程序" Level="1"> <ComponentRef Id="MainExecutable" /> </Feature> </Product> </Wix>逐一说明关键点。Product 的 Id 和 UpgradeCode 必须用固定 GUID，不要偷懒写星号。原因：UpgradeCode 是产品升级时检测旧版本的身份标识，ProductId 决定已安装产品是否被识别为“同一个产品”。如果两处都写成 *，每次构建都会生成新 GUID，版本升级永远变成“安装第二个应用”，旧版本不会被覆盖。所以这两个值在工程创建时生成一次，之后不再变动。
Component 的 Guid 写成 * 则恰恰相反，这是 WiX 推荐的做法。星号让 WiX 基于组件路径确定性生成 GUID，同一路径每次构建结果一致，既免去手工维护上百个 GUID 的负担，又保证升级时组件 ID 稳定，旧版本能干净卸载。这里不要理解成“每次编译随机生成”，它是确定性的算法结果。
File 元素里 KeyPath="yes" 表示这个文件是组件的关键路径，安装检测时以它是否存在来判断组件是否已安装。Source 写的是 $(var.BuildDir)\MyApp.exe，这个变量由编译命令里的 -dBuildDir 提供，不在 wxs 里写死绝对路径。
提示：WiX 3.10 之后推荐用 代替手写 。InstallerVersion="500" 表示要求系统安装服务不低于 5.0，Windows 7 SP1 及以上均满足，同时让 MSI 表结构更精简。
这个骨架里目录用了 ProgramFiles64Folder 且组件带 Win64="yes"，是标准的 64 位安装包写法。如果你要出 32 位包，把目录改回 ProgramFilesFolder、去掉 Win64 属性即可。
3.3 编译、链接与批处理脚本：把两个命令串成一个构建步骤
candle 负责把 wxs 编译成 wixobj，light 负责把 wixobj 链接成 msi。下面是完整的构建脚本，可以直接存成 build.bat，在 CI 的 cmd 步骤里执行：
@echo off set WIX=C:\wix311\bin %WIX%\candle.exe -nologo -dBuildDir=release\bin -out build\MyApp.wixobj MyApp.wxs if errorlevel 1 exit /b 1 %WIX%\light.exe -nologo -out build\MyApp.msi build\MyApp.wixobj if errorlevel 1 exit /b 1 echo MSI built: build\MyApp.msi先看 candle 这一行。-nologo 去掉横幅；-dBuildDir=release\bin 把变量 BuildDir 指向实际的成品目录，wxs 里的 $(var.BuildDir) 在这里被替换；-out 指定 wixobj 的输出位置。这里要注意变量名大小写必须和 wxs 里引用的一致，BuildDir 和 buildDir 在 WiX 预处理阶段是两个不同的变量。
再看 light 这一行。-out 指定目标 msi 路径，后面跟的是 candle 产出的 wixobj。如果工程引用了扩展，比如之后要加的 WixUI，在这一行追加 -ext 参数即可。
脚本里每步之后检查 errorlevel 是 CI 里的关键习惯。candle 成功返回 0，任何编译错误都会是非零值，不检查的话，light 会拿着不完整的 wixobj 继续跑，报一堆难懂的链接错误，把你真正的问题淹没掉。所以两个 errorlevel 判断不可省。
另一种常见做法是不用 -d 变量，给 light 加 -b 参数指定绑定路径，wxs 里写相对路径。但那样做可移植性差，目录结构一变就要改脚本。我更习惯 -d 变量方案，把路径选择权留给调用方，wxs 永远只描述“安装成什么样”，不描述“文件从哪里来”。
构建完成后，build\MyApp.msi 就是产物。这里顺便提一句排查思路：如果构建失败，先看是 candle 报的错还是 light 报的错。candle 报错基本是 XML 语法、变量未定义、GUID 格式非法；light 报错基本是引用关系、扩展缺失、ICE 校验失败。两个阶段的错误原因几乎不交叉，按这个方向查能省一半时间。
4. 常见问题与避坑清单：wix311 构建中我踩过的五个坑
4.1 装了 64 位程序结果文件落在 SysWOW64：x64 架构的三件套缺失
现象：用 64 位编译环境产出的 MSI，安装时文件进了 Program Files (x86) 目录，程序也以 32 位进程在跑。检查 wxs 里的目录声明，明明写的是 ProgramFilesFolder，但 WiX 在 x86 默认模式下把它解析成了 32 位视图。
原因：candle 命令行缺少 -arch x64，导致整个产品按 32 位处理。在 WiX 里，64 位安装包不是“加几个属性”就能声明的，它要求三件事同时成立：candle 加 -arch x64、组件声明 Win64="yes"、目录用 ProgramFiles64Folder。缺一件，系统就会走 32 位重定向逻辑。
解决：按下面三处逐一核对。
<Component Id="MainExecutable" Guid="*" Win64="yes"> <File Id="MainExe" Source="$(var.BuildDir)\MyApp.exe" KeyPath="yes" /> </Component>同时确认 wxs 里的目录节点是 ProgramFiles64Folder，而不是 ProgramFilesFolder；确认编译命令里带了 -arch x64。这三件套缺一不可，这是我见过最多的翻车点，没有之一。
4.2 light 阶段 ICE57 报错：64 位组件里混入了 32 位注册表键
现象：light 链接时构建失败，日志里出现 ICE57 开头的错误，大意是某个组件同时涉及 64 位文件键路径和会被重定向的 32 位注册表路径。构建进程直接退出，退出码非零。
原因：ICE 是 light 阶段的内部一致性校验，专门检查安装包规则层面的矛盾。一个标记为 Win64="yes" 的组件里，如果 Registry 项写的是 HKEY_LOCAL_MACHINE\Software... 这种默认视图路径，Windows 在安装时会把它重定向到 SysWOW64 对应的注册表视图，与组件自身的 64 位键路径产生冲突。ICE 校验不允许这种同一组件内混合位架构的做法。
解决：把注册表项从 64 位组件里拆出来，单独建一个 32 位组件专门放注册表写入；或者给注册表键名加上 **64 后缀明确写到 64 位注册表视图。另外值得知道的是，light 提供 -sice:ICE57 这样的临时压制参数，但在团队工程里不要轻易用它。压制一个 ICE 等于关掉一道安全闸门，当前构建能过，升级时可能埋雷。正确顺序永远是先改 wxs 结构，最后才考虑压制。
4.3 中文界面变乱码或解析失败：wxs 编码必须统一 UTF-8
现象：安装界面上的中文说明变成一串问号，或者更严重，light 直接报 XML 解析错误，说文件里有非法字节。代码在同事机器上编译正常，换到你的机器就挂。
原因：Windows 默认文本编码历史遗留严重，wxs 文件被存成了 ANSI 或 GBK，但文件头部的 XML 声明写的还是 encoding="UTF-8"。candle 按 UTF-8 去读，读到中文字节就解码失败，或者更隐蔽地解码出错误字符，界面显示乱码。
解决：所有 wxs 统一使用 UTF-8 编码保存。带不带 BOM 都可以，重点是文件实际字节必须是 UTF-8。用 VS Code 打开文件后看右下角编码提示，不是 UTF-8 就“通过编码保存”重新存一次。团队协作时，最好在编辑器设置里把默认文件编码固定为 UTF-8，这个设置能避免 90% 的乱码问题。顺带提醒：wxs 里的注释、Product 的 Name 属性、Feature 的 Title，任何出现中文的地方都是编码重灾区，检查时别只盯正文。
4.4 下载源和杀软误报：只从官方渠道拿 zip 并校验哈希
现象：从某个下载站拿到的 wix311-binaries.zip，解压后被 Windows Defender 报毒；或者解压出来的 bin 目录里多出几个不认识的 exe，candle.exe 的图标和官方的看起来不一样。
原因：WiX 工具要写注册表、创建安装服务、生成 MSI 文件，行为特征和恶意安装包脚本有相似之处，部分杀软会按启发式规则给出风险提示。另一个更危险的因素是，很多第三方镜像站喜欢把多个工具混在一个压缩包里重新打包，夹带私货不容易被注意。
解决：只从官方渠道获取 wix311-binaries.zip，认准 WiX 工具集的官方发布仓库或者说 wixtoolset.org 的下载跳转页面，不要从任何第三方“绿色工具合集”下载。拿到文件后先算哈希，和官方发布页公布的 SHA256 比对：
Get-FileHash .\wix311-binaries.zip -Algorithm SHA256 | Format-List哈希一致，才能确认这个包没有被替换过。如果此时杀软仍报毒，可以把这个官方来源的包加入排除项。哈希对不上，立刻删除重新下载。这个习惯花三十秒，能省掉一整天的排毒时间。
4.5 unresolved reference：-ext 没加导致的链接失败
现象：light 阶段报类似这样的错误：light.exe : error LGHT0104 : unresolved reference to symbol 'WixUI:WixUI_Minimal' in section 'Product'。构建中止。
原因：wxs 里使用了某个扩展程序集提供的符号，但 light 命令行没有加载对应的扩展 DLL。WiX 的 -ext 机制和链接库的概念非常像：你在代码里引用了库里的函数，链接时不带那个库文件，自然报未解析引用。这里引用的是 WixUI 扩展里的对话框集合，但 light 不知道去哪里找。
解决：在 light 命令里补上扩展参数，用 WixUI 就加载 WixUIExtension：
light.exe -ext WixUIExtension -nologo -out build\MyApp.msi build\MyApp.wixobj如果报错的符号前缀是 WixUtil:，对应的是 WixUtilExtension；前缀是 WixUI:，对应 WixUIExtension；前缀是 WixVaultExtension 等同理。另一个经验是：这类错误直接搜错误码 LGHT0104，比搜整句报错有效得多。错误码定位到具体错误类型，搜索得到的答案更准确，这个技巧对 WiX 全系列报错都适用。
5. 给 MSI 加上 WixUI 向导：用安装日志验证产物的最后一公里
5.1 三行改动，换来一个标准安装向导
没有 UI 引用的 MSI 安装时是系统默认的用户账户控制弹窗加一个朴素进度条，对内部工具够用，但要交付给非技术同事时，最好有一个标准的安装向导界面。WiX 3.11 自带 WixUI 扩展，要做的事情只有两步。
第一步，在 wxs 的 Package 元素之后加一行 UI 引用：
<!-- 在 <Package ... /> 之后、<MediaTemplate ... /> 之前插入 --> <UIRef Id="WixUI_Minimal" />第二步，light 命令加载对应扩展：
light.exe -ext WixUIExtension -nologo -out build\MyApp.msi build\MyApp.wixobj三种常见 UI 方案按需选择：
| UI 方案 | 交互范围 | 适用场景 |
|---|---|---|
| WixUI_Minimal | 只有进度和完成页，无交互 | 内部工具、无选项安装 |
| WixUI_InstallDir | 增加安装路径选择页 | 用户需要换目录 |
| WixUI_FeatureTree | 增加功能树选择页 | 多组件、多特性产品 |
大多数内部工具选 Minimal 就够了，少一个交互页少一份用户误操作的可能。需要中文界面时，在 light 里追加 -cultures:zh-CN 参数，并把 Product 的 Language 改成对应 LCID，扩展内置的本地化字符串会自动匹配。
5.2 安装日志 /l*v：最诚实的产物验证方式
构建成功不等于安装成功。MSI 装上后文件到底落在哪里、注册表写了没有、为什么不声不响地回滚了，这些问题用安装日志验证最直接。
msiexec /i build\MyApp.msi /l*v install.log/l*v 是详细日志开关，会记录安装过程中每个 Action 的执行顺序和返回值。我一般看日志只看三处：第一搜 Return value 3，这是失败返回值，出现就说明某个 Action 崩了；第二看最后一个 Action start 有没有对应的 Action ended，没有配对的就是中断位置；第三在日志里搜文件名，比如 MyApp.exe，看它实际被复制到了哪个目录，程序装没装对地方，日志比界面诚实得多。
从那以后我每次在 CI 出完包，都会强制自己把 /l*v 日志扫一遍再交付。装没装上、装到哪、哪一步失败，这些问题的答案全在日志里，猜是猜不出来的。希望帮到你。
本文还有配套的精品资源，点击获取
