企业官网建设流程全解析

翻到笔记里躺着的一条需求记录，日期停在2021年8月19日，内容是“在InstallShield主程序安装包之外，附属安装和卸载一个MSI组件”。笔记本上就这一句话，但做过Windows安装包开发的人看到这句话，应该马上能想到一堆具体问题：MSI怎么塞进主安装包、什么时候以什么权限启动安装、卸载时怎么把独立产品清干净、装到一半失败了怎么排查。这篇文章就把这类需求完整拆一遍，从方案选型、安装动作配置、卸载逻辑、日志排错到个人踩过的坑，一条条写清楚。适合正在维护InstallShield老工程、或者需要把多个独立MSI组合成一套交付包的开发者参考。

1. 需求还原与方案选型，先想清楚要解决什么问题

1.1 这个需求到底在说什么

先还原一下场景。假设手里已经有一个主产品的安装包工程，可能是InstallScript类型，也可能是Basic MSI类型。主产品本体是一套软件，但运行依赖另一个独立的MSI组件——比如某个运行时、驱动包、服务模块、公共库，甚至可能是另一个团队维护的插件。这个MSI不能简单被“融入”主安装包，因为它有自己的版本号、发布渠道和升级节奏，必须以独立产品的形式出现在“程序和功能”里，也必须在主产品卸载时一并卸载。

用户视角就一句话：双击主安装包，装完主程序，附属组件一起到位；卸载主程序，附属组件也一起消失。但这句话落到InstallShield工程里，意味着要在安装和卸载两个时序里各插一段自定义逻辑，还要处理好权限、条件、路径和残留问题。

很多人在这一步容易犯迷糊：不等价于把一个MSI文件拖进安装包就完事。拖进去只是让文件“随包分发”，Windows Installer不会因为你把一个MSI复制到了安装目录就把它注册成一个产品。真正让它安装起来、卸载干净，靠的是执行序列里的自定义动作（Custom Action）调用msiexec命令。

1.2 三条主流路径怎么选

处理这种“主程序之外附属一个MSI”的需求，业内常见有三条路，各有利弊，先放个对比表：

如果手里是个运行了很多年的老工程，或者团队里还有一堆基于InstallScript脚本写死的业务逻辑，迁移Suite项目的成本基本等于重做安装包。Merge Module方案又要求组件方配合改工程，跨团队协调经常卡壳。所以我在实际处理时选的是第三条路：主工程保持不动，在安装和卸载序列里分别插入执行msiexec的自定义动作。

选择这条路的核心原因是“改动最小、可控性最强”。主安装包还是原来的主安装包，附属MSI还是原来的独立MSI，两边都不需要动源码。InstallShield只负责在正确的时机、用正确的身份、带上正确的参数去调用msiexec而已。听起来简单，实际配置起来有不少细节，下面两章按安装、卸载分开讲。

2. 安装阶段：把附属MSI装进主安装包

2.1 准备阶段：MSI文件放哪、怎么进包

开始配置之前，先把附属MSI文件弄进主安装包。这一步看似基础，但文件放的位置会影响后面卸载逻辑的可靠性。

InstallShield工程里一般有两个地方可以放这类“额外文件”。InstallScript工程习惯用“Support Files”视图；Basic MSI工程可以在“Files and Folders”里把它加到一个组件目录下。我个人的建议是专门在安装目录下开一个子目录，比如[INSTALLDIR]\Components\xxx.msi，让MSI文件随着主安装流程释放到用户机器上。

为什么不放临时目录？临时目录看起来干净，装完可以自动清理，但问题是卸载时很可能已经拿不到了。Windows安装目录在主程序卸载时大概率还在，而临时文件夹可能被系统盘清理、用户手动清理或者其他安装过程给清掉。如果卸载动作想依赖本地文件做二次确认，文件却没了，那场面会很尴尬。

还有两个小细节值得提前注意。第一，MSI文件名尽量全英文、不带空格。msiexec命令行解析路径时，空格必须靠双引号处理，一旦引号嵌套出问题，安装动作直接失败。第二，确认这个MSI是32位还是64位组件。这两个位数在64位系统上的行为完全不同，后面排查部分会专门讲。

2.2 用自定义动作触发静默安装

文件进包之后，开始配置安装动作。以Basic MSI工程为例，在InstallShield里打开“Custom Actions and Sequences”，在InstallExecuteSequence中找到位置，右键新增一个执行程序的自定义动作，核心配置如下：

• 动作类型：Launch Program（启动外部程序）
• 命令行：msiexec /i "[INSTALLDIR]\Components\xxx.msi" /qn /norestart /l*v "[TempFolder]\component_install.log"
• 执行位置：InstallFiles之后、InstallFinalize之前，事件定位选“After InstallFiles”
• 条件：NOT Installed
• 执行上下文：Deferred Execution in System Context（延迟到系统上下文执行）

每个参数都不是随便写的。/qn表示完全静默安装，不弹MSI自带界面；如果主安装包是带向导界面的，而附属MSI又弹出一个安装进度框，用户会看到两个安装界面叠在一起，显得非常业余，也容易让用户误以为安装程序出了问题。/norestart是防止附属MSI在安装过程中触发系统重启，导致主安装流程直接中断。/l*v是生成详细日志，这个参数在出问题排查时几乎是救命稻草，后面第4章会反复提到。

条件NOT Installed保证了只在首次全新安装时触发。主安装包做修复操作或者添加组件时，不应该再执行一遍附属MSI的安装动作。执行上下文选择“系统上下文”也很关键：普通用户双击安装包时，Windows Installer的权限往往不足以在Program Files目录写文件、在注册表HKLM写键值，把自定义动作提升到系统上下文可以避开大量权限报错。

InstallScript工程的做法思路完全一样，只不过位置在InstallScript序列里，点的位置叫“Call Custom Action”或者直接在脚本码区写一段LaunchApplication或调用ShellExec的代码。区别在于老InstallScript工程更灵活，同一个动作甚至可以做成同步等待或异步执行——遇到需要确认安装结果的情况，可以选同步，让主安装流程等待msiexec返回的退出码再继续。

2.3 安装时机与进度反馈上的经验

配置好动作后，还有一个很少有人会在第一时间考虑的问题：安装时机对用户体验的影响。

贴上“After InstallFiles”位置是有讲究的。放在这个点，意味着主安装包的文件已经先落盘，安装目录结构已经存在。如果放在InstallFiles之前，比如放在InstallInitialize后面，附属MSI依赖的一些目录或文件可能还没释放，轻则安装失败，重则留下半个装完的组件残骸在系统里。我在实际工程中测试过一次把动作放在InstallFiles之前，那次测试机重启后直接报告组件损坏，属于典型的不按执行顺序办事的教训。

另外，附属MSI如果比较大，静默安装在用户看来就是“一直没反应”。主安装包的进度条可能会停在某个阶段长时间不动。建议在自定义动作前后加一个进度提示：安装动作开始前，把进度条文案改成“正在安装附加组件...”，动作返回后恢复原有进度。InstallShield里可以通过设置进度条消息文本或插入一个小的等待窗口来实现，不同版本界面叫法不一样，但逻辑都是异步任务加界面反馈。

还有一个容易被忽略的点：安装动作的时序选择会直接影响后续卸载逻辑的组织。比如安装时把附属MSI放到[INSTALLDIR]\Components，卸载时就可以按这个路径去确认文件是否还在。路径策略要和卸载策略一起设计，不要装的时候随手放，卸的时候又临时找。

3. 卸载阶段：主程序走了，附属组件也得跟着走

3.1 为什么默认不会自动卸载

现在说卸载。很多人配置完安装动作就以为大功告成了，实际上坑全在卸载这半边。

前提认知是：用msiexec安装成功的MSI，会以独立产品的身份注册在Windows Installer的“已安装产品”列表里，拥有自己的ProductCode。主安装程序卸载时，Windows Installer只会清理主MSI产品数据里记录的文件、注册表项和组件，不会主动去扫描机器上还存在哪些其他产品。所以主程序卸载完后，附属MSI会变成孤儿产品，留在“程序和功能”列表里，用户下次重新安装主程序时还会被这个残留版本干扰。

我遇到过的最典型的残留症状是：卸载主程序后重装新版，安装过程一切正常，但新版附属组件安装动作返回错误，打开日志一看，系统提示“该产品的另一个版本已安装”。这就是孤儿产品没清干净导致的冲突。

3.2 卸载自定义动作的配置

所以必须给卸载动作单独配置一段自定义逻辑。同样是以Basic MSI工程为例：

• 动作位置：RemoveFiles之后、InstallFinalize之前
• 条件：REMOVE="ALL" AND NOT UPGRADINGPRODUCTCODE
• 命令行：msiexec /x {GUID-XXXX-XXXX-XXXX-XXXXXXXXXXXX} /qn /norestart /l*v "[WindowsFolder]\component_uninstall.log"
• 执行上下文：Deferred Execution in System Context

这里的ProductCode不是瞎填的。要从附属MSI安装包本身的属性表里读取，也就是该组件作为独立产品时注册用的那个GUID。这个GUID在“程序和功能”里、注册表HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall条目下都能对应上。安装时写进命令行用的就是它。

条件里的REMOVE="ALL"表示完整卸载整个产品而不是修改某个功能；AND NOT UPGRADINGPRODUCTCODE也很重要，它的作用是防止主安装包做升级操作时，误把附属组件卸载掉。升级场景下，旧版本的主产品被移除时也会触发卸载序列，如果不加这个条件，就会出现“升级主程序，结果附属组件被卸了”的严重事故。

卸载用/x参数配合ProductCode，不要用文件路径。原因很简单：附属MSI在机器上可能因为后续单独升级、手动安装过新版本而发生变化，用ProductCode卸载能保证卸载的是“当前注册的产品”，而不是“某个路径下的文件对应的那个版本”。

3.3 卸载时序的取舍

关于卸载时序，不同团队有不同习惯。我看到网上有方案安排在InstallInitialize之前卸载附属MSI，理由是越早清掉组件，主程序卸载时越不会受它的文件影响。但实际上这个时序有个隐患：如果附属组件有服务或进程正在运行，主程序文件还没清理就被卸载，可能因为文件被占用导致卸载失败。

我实际更推荐放在RemoveFiles之后。先让主程序把自己的文件清理掉，如果主程序进程正在运行，也让它先释放句柄；然后再触发附属MSI的卸载，此时系统的文件占用已经最小化，卸载成功率明显提高。

卸载日志的存放位置也要留意。不要写到[INSTALLDIR]下，因为主程序文件已经被清掉了，目录可能都不存在了；写到[WindowsFolder]或[TempFolder]更稳妥。我在一次测试中把卸载日志路径写死到了安装目录下，结果卸载完成后日志文件根本找不到，排查直接没了线索。

另外，卸载动作调用msiexec返回3010（需要重启）时，主程序卸载也不能直接假装成功，最好给用户一个“请重启系统完成卸载”的提示。很多安装包对3010的处理都很随意，但附属组件的文件如果被占用，不重启的情况下卸载其实并不彻底，重新安装时可能还会有残留冲突。

4. 常见问题与日志排查实录

4.1 msiexec返回码速查表

自定义动作本质是启动msiexec进程，排查时第一眼先看进程的退出码。msiexec的返回码很有规律，列个速查表方便对照：

这张表能在排查时帮我们把问题快速分成两类：一类是安装包本身的问题，一类是环境或路径的问题。比如1619、1706往往伴随着文件路径错误；1603则需要结合日志里更具体的错误信息往下追。

4.2 一次1603的完整排查过程

拿一个典型的1603举例。某次测试，主程序在开发机上安装正常，在另一台测试机上安装时，主程序装完了，最后却整体回滚。打开附属组件的安装日志，末尾写着“MainEngineThread is returning 1603”。

经验不够的人看到1603可能会先去怀疑权限。但仔细看日志发现错误发生在系统上下文执行阶段，权限基本没有问题。继续往日志前面翻，看到一行路径相关的记录：附属MSI尝试访问64位程序目录下的路径，但日志里记录的目录被重定向到了SysWOW64下。

问题就出在位数匹配上。这台机器上跑的附属MSI是32位组件，而主安装包工程是64位工程，自定义动作默认启动的msiexec继承了主进程的位数环境。结果就是动作执行环境、MSI目标平台、实际落盘路径三者不一致，组件安装到一半找不到目标路径，于是回滚。

解决办法是在自定义动作的属性里显式标记“64-bit”执行，或者干脆把附属MSI换成和主工程匹配的位数。这个案例说明，位数问题表面上看是配置问题，本质上是对Windows Installer重定向机制的认知问题。32位进程在64位系统上写文件、写注册表时，系统会悄悄把路径和注册表键重定向到SysWOW64目录和Wow6432Node节点，日志里如果不熟悉这套行为，根本看不出异常。

4.3 三个高频坑与避让

第一个高频坑是ProductCode抄错。GUID连字符的位置、大小写、数字字母写错一个，卸载时直接1605。尤其是从安装日志里复制ProductCode时，很容易因为日志格式截断而抄漏一段。最稳的做法是打开附属MSI的Property表直接读ProductCode，或者让组件方提供正式参数清单。

第二个高频坑是卸载依赖本地文件路径。用msiexec /x "路径\xxx.msi"这种写法在文件还在时确实能卸，但一旦主程序文件先被清理，路径失效，卸载动作直接失败。前面章节已经强调过，卸载统一用ProductCode，这是整个方案里最重要的原则之一。

第三个高频坑是条件漏掉升级判断。很多人照着网上的模板填了REMOVE="ALL"，没加AND NOT UPGRADINGPRODUCTCODE，结果主安装包升级时，卸载序列触发了附属组件的卸载动作，用户升级完主程序发现附属组件不见了，服务起不来。这种问题在测试环境不容易发现，因为升级测试往往被排在很靠后的阶段，但一旦发生就是生产事故级别的影响。

还有一个小坑值得单独提：安装动作放在InstallFiles之前导致的找不到文件错误。前面提到过，InstallShield界面上自定义动作的时序位置非常好拖，拖错位置也不会报明显错误，只在安装时静默失败。所以配置完一定要看一整条执行序列的完整顺序，不要只看单个动作。

5. 实操总结与踩坑记录

5.1 一套最简可行配置清单

下面把整套方案浓缩成一张可以直接照着做的清单，以Basic MSI工程为例：

按照这张表配置，理论上就能跑通“主程序安装 -> 附属MSI自动安装 -> 主程序卸载 -> 附属MSI自动卸载”的完整闭环。InstallScript工程的区别只是把自定义动作放到脚本序列里，命令行参数完全一致。

实际动手前，建议先把三件事写在纸上：附属MSI的ProductCode、安装日志要放的路径、卸载日志要放的路径。这三个信息在排错时会频繁用到，提前列清楚能省很多时间。

5.2 我的几点体会

这种“主程序外再带一个MSI”的需求，表面看是InstallShield界面上的两次自定义动作配置，深层涉及的其实是Windows Installer的产品模型、执行序列时序、权限上下文、32/64位重定向机制这四层知识。只会在界面里点按钮，不理解背后的执行逻辑，出了问题就会很被动。

我个人强烈建议，配置完成后不要只在开发机上验证一次“能装上”就结束。至少要在干净虚拟机里完整跑一遍“安装-卸载-重装”三连测，重点观察三件事：卸载完成后“程序和功能”里还有没有残留产品记录；重装时附属动作的日志有没有出现1605、1706这类异常；再卸载时日志路径是否正确。这套测试流程能提前暴露大部分残留问题，成本比生产环境出问题低一个数量级。

最后再分享一个细节：日志文件命名时把动作名带进去。比如安装日志叫component_install.log，卸载日志叫component_uninstall.log，不要统一叫msi.log。出问题时，用户收集回来的是一堆文件名相同的日志，光靠时间戳区分会非常痛苦。把动作名写进日志名，三四份日志摆在一起，一眼就能看出哪份是安装动作产生的、哪份是卸载动作产生的，排查效率完全不一样。