Ruffle Windows MSI 安装包构建指南使用 WiX 工具集为 ruffle_desktop 打包安装程序【免费下载链接】ruffleA Flash Player emulator written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/ruffle本指南基于 Ruffle 仓库中的 desktop/packages/windows/wix/README.md 及同目录下的 WiX 工程源码完整讲解如何把 Ruffle 桌面版ruffle_desktop构建为 Windows 标准.msi安装包。你将掌握 WiX v4 工具链的安装配置、RUFFLE_VERSION等环境变量的含义与取值规则、完整构建命令及其可选参数并深入理解 ruffle.wxs 中安装目录、文件关联、环境变量 PATH、升级策略与自定义安装向导界面的底层实现。一、背景为什么要为 Ruffle 桌面版制作 MSI 安装包Ruffle 是一个用 Rust 编写的 Flash Player 模拟器同时面向桌面与 WebWebAssembly。桌面版本体位于 desktop 目录Cargo 包名为ruffle_desktop构建产物为ruffle.exeWindows 下OriginalFilename即ruffle.exe见 desktop/Cargo.toml。为了让 Windows 用户能够通过标准的“双击安装向导”完成部署、获得开始菜单/桌面快捷方式、.swf文件关联以及系统 PATH 写入等能力仓库在desktop/packages/windows/wix目录下维护了一套基于 WiXWindows Installer XML工具集的 MSI 打包工程。该目录包含 4 个文件它们共同构成完整的 MSI 工程README.md构建 MSI 的操作文档即本文所依据的核心文档ruffle.wxs主安装脚本定义包元数据、目录结构、组件、文件关联与功能树dialog.wxi自定义安装向导 UI 的 Include 片段banner.png、dialog.png安装向导使用的横幅与对话框背景位图资源。二、前置条件准备 WiX 工具链与 Ruffle 构建产物在构建 MSI 之前需要先完成环境准备。按照 README 的说明依次执行以下步骤安装 WiX 工具集v4 .NET 工具。WiX v4 通过 .NET 全局工具分发使用如下命令安装dotnet tool install --global wix添加 UI 扩展用于生成安装向导界面wix extension add -g WixToolset.UI.wixext添加 Util 扩展用于util:PermissionEx目录权限等实用功能wix extension add -g WixToolset.Util.wixext这两条命令也可以在ruffle.wxs文件头部的注释中看到对应说明见 ruffle.wxs与 README 保持一致。构建 Ruffle 桌面版 release 产物。MSI 需要把已经编译好的ruffle_desktop.exe打进安装包。README 给出的方式是先构建整个桌面项目cargo build --release也可参考仓库根目录 README.md 中的桌面构建说明cargo run --release --packageruffle_desktop可用于构建并运行构建产物默认位于仓库根目录下的target/release/ruffle_desktop.exe。也就是说在运行wix build之前必须保证ruffle_desktop.exe已就绪若只是要打包也可以直接准备一个预编译的 exe 放在上述路径。注意ruffle.wxs中引用的是$(CargoBuildDir)/ruffle_desktop.exe见 ruffle.wxs因此打包前请确认该 exe 文件存在且为 Windows 目标平台产物。三、环境变量RUFFLE_VERSION 与 CARGO_BUILD_DIRMSI 构建依赖两个环境变量其中一个是必需的。RUFFLE_VERSION必需该变量指定 MSI 所包含的 Ruffle 版本号会直接写入 Windows Installer 的Version属性见 ruffle.wxs用于 Windows 的版本比较与升级判定。取值规则如下格式必须为1.2.3或1.2.3.4点分四段注意第四段数字会被 Windows 忽略——Windows 的“是否为相同或更新版本”检查只比较前三段因此不要指望通过修改第四段来发布“更新版本”它不影响升级判定。在构建命令中通常以内联环境变量的方式传入例如RUFFLE_VERSION1.2.3 wix build ruffle.wxs ...CARGO_BUILD_DIR可选该变量指定包含ruffle_desktop.exe的目录。默认值为../../../../target/release相对于desktop/packages/windows/wix目录即仓库根目录下的target/release。ruffle.wxs中对应的逻辑如下见 ruffle.wxs?ifdef env.CARGO_BUILD_DIR? ?define CargoBuildDir $(env.CARGO_BUILD_DIR)? ?else? ?define CargoBuildDir ../../../../target/release? ?endif?即如果设置了CARGO_BUILD_DIR环境变量则优先使用否则回退到默认的../../../../target/release。当你的 exe 输出到自定义目录例如 CI 流水线中的临时目录时可通过该变量覆盖默认路径无需改动.wxs文件。四、构建命令与常用参数进入desktop/packages/windows/wix目录后执行以下命令生成 x64 架构的 MSIwix build ruffle.wxs -ext WixToolset.UI.wixext -ext WixToolset.Util.wixext -arch x64其中参数说明ruffle.wxs主安装脚本文件WiX 编译入口-ext WixToolset.UI.wixext引入 UI 扩展构建向导界面所需-ext WixToolset.Util.wixext引入 Util 扩展util:PermissionEx等所需-arch x64目标 CPU 架构决定安装目录与注册表视图README 还给出了三个可选参数-arch x86将 MSI 标记为 x86 架构此时安装目录会落在Program Files (x86)等 32 位路径下由ProgramFiles6432Folder标准目录决定详见下文-pdbtype none禁用.wixpdbWiX 调试数据库文件的生成若不需要调试符号可加上此参数减小构建产物-o foo.msi指定 MSI 输出文件名与路径默认输出到当前目录。组合示例——生成 x86 架构、不带 wixpdb、自定义输出路径的 MSIwix build ruffle.wxs -ext WixToolset.UI.wixext -ext WixToolset.Util.wixext -arch x86 -pdbtype none -o dist/Ruffle-Setup-x86.msi五、深入解析 ruffle.wxs安装包配置拆解ruffle.wxs是整个 MSI 的“心脏”。下面按安装包生命周期逐层拆解其配置。5.1 Package 元数据与升级策略Package NameRuffle UpgradeCode$(var.UpgradeCode) ManufacturerRuffle LLC Language1033 Codepage65001 Version$(env.RUFFLE_VERSION) InstallerVersion500 CompressedyesName安装包显示名RuffleUpgradeCode升级码用于跨版本识别“同一个产品”。固定值C6A4BA50-FA08-4B87-9B55-D81A1C730D25定义于文件顶部见 ruffle.wxs注释说明如需将 MSI 作为“不同的包”安装例如本地测试同一版本可修改此 UpgradeCode——修改后 Windows 会把它当作全新产品允许与正式版共存Manufacturer厂商名Ruffle LLCLanguage/Codepage语言 1033en-US与 UTF-8 代码页 65001Version直接取自$(env.RUFFLE_VERSION)环境变量即上文必须设置的版本号InstallerVersion所需 Windows Installer 最低版本 500Windows Installer 5.0随 Windows 7 及以后系统提供Compressedyes全部文件压缩进 MSI配合Media EmbedCabyes见 ruffle.wxs得到单一自包含的.msi文件。升级逻辑由MajorUpgrade控制见 ruffle.wxsMajorUpgrade ScheduleafterInstallInitialize DowngradeErrorMessageA newer version of Ruffle is already installed. Setup will now exit. AllowSameVersionUpgradesyes/ScheduleafterInstallInitialize在安装初始化后执行主要升级可处理文件占用等场景DowngradeErrorMessage检测到已安装更新版本时显示的提示文案“已安装更新版本的 Ruffle安装程序将退出”AllowSameVersionUpgradesyes允许同版本号覆盖安装配合前文“第四段版本号被忽略”的特性使用。5.2 目录结构与组件目录树定义如下见 ruffle.wxsProgramFiles6432Folder 64 位Program Files32 位Program Files (x86) └── INSTALLFOLDER (ruffle) ├── EnsureDirectoryWritable 组件授权 Users 组 GenericAll 写权限util:PermissionEx ├── License 组件安装 LICENSE.md 许可证文件 └── Bin (bin) ├── Path 组件把 [Bin] 写入系统 PATH 环境变量 └── binary0 组件安装 ruffle.exe 开始菜单快捷方式几个值得注意的实现细节ProgramFiles6432Folder由-arch参数决定其最终解析路径——x64 安装到Program Filesx86 安装到Program Files (x86)这正是 README 中“-arch x86会安装到 Program Files (x86)”的底层原因EnsureDirectoryWritable通过util:PermissionEx UserUsers GenericAllyes授予所有 Users 对安装目录的写权限方便普通用户在安装后写入数据例如向 Ruffle 目录放置 SWF 文件而不需要管理员权限Path组件使用Environment元素把[Bin]即...\ruffle\bin追加到系统级 PATHPartlast表示追加在末尾Permanentno表示卸载时移除Actionset、Systemyes表示写入系统环境变量。该组件默认随主功能安装但可在 UI 中作为独立子功能控制见 5.5binary0组件安装ruffle.exe同时创建ProgramMenuFolder中的“Ruffle”开始菜单快捷方式Advertiseyes广告式快捷方式图标取自Icon.ico见 ruffle.wxs图标源文件为仓库根目录 desktop/assets/favicon.icoDesktopShortcut组件桌面快捷方式带ConditionINSTALLDESKTOPSHORTCUT条件——只有用户在自定义向导中勾选了“在桌面创建快捷方式”复选框对应属性INSTALLDESKTOPSHORTCUT默认值为 1见 ruffle.wxs才会安装。由于快捷方式不能作为组件 KeyPath源码中特意写入了一个 HKCU 注册表值作为 KeyPath 并附注释说明这一“必要的技巧”见 ruffle.wxs。5.3 文件关联.swf / .spl / .rufAssociations组件为 Ruffle 声明了三种文件类型关联见 ruffle.wxsProgId扩展名说明Ruffle.swf.swfFlash 影片ContentTypeapplication/x-shockwave-flashRuffle.spl.splFlash 影片旧式 FutureSplash 扩展名Ruffle.ruf.rufRuffle BundleContentTypeapplication/x.ruffle-bundlezip每个 ProgId 都注册了open动词执行命令为ruffle.exe %1Argument%1见 ruffle.wxs。同时通过HKCR\.swf\OpenWithProgids等注册表值把 Ruffle 加入对应扩展名的“打开方式”列表见 ruffle.wxs。源码注释对关联行为有重要说明见 ruffle.wxs这些注册只表示“Ruffle 可以打开这些文件”Windows 不一定会立即把默认打开程序切换为 Ruffle更常见的是用户下次双击 SWF 时被询问选择哪个程序。同时ApplicationInfo组件进一步在HKCR\Applications\ruffle.exe下注册了FriendlyAppName在“打开方式”对话框中显示为 “Ruffle” 而非ruffle.exe以及SupportedTypes.swf/.spl/.ruf见 ruffle.wxs。注释中还特别提醒Windows 仅凭 exe 文件名来匹配这些关联信息一旦用户把ruffle.exe重命名这些“打开方式”条目便会失效。5.4 卸载信息与控制面板属性SetProperty IdARPINSTALLLOCATION Value[APPLICATIONFOLDER] AfterCostFinalize把安装位置写入 ARP添加/删除程序信息见 ruffle.wxsARPPRODUCTICON控制面板中显示的产品图标Icon.icoARPHELPLINK帮助链接指向https://ruffle.rsdialog.wxi中设置ARPNOMODIFY1见 dialog.wxi隐藏“修改”按钮安装后只允许修复/卸载。5.5 Feature 功能树Feature IdBinaries TitleApplication DescriptionInstalls the Ruffle desktop application ... !-- EnsureDirectoryWritable / License / binary0 / Associations / ApplicationInfo / DesktopShortcut -- Feature IdEnvironment TitlePATH Environment Variable DescriptionAdd the install location of the Ruffle executable to the PATH system environment variable... ComponentRef IdPath/ /Feature /Feature外层功能Binaries应用程序本体为必装项Level1内部嵌套子功能Environment是否把 Ruffle 目录加入 PATH——由于Displayexpand且子功能Level1默认选中用户在自定义安装界面中可展开并取消勾选“PATH 环境变量”功能实现按需安装。六、自定义安装向导dialog.wxi 与 WixUI_InstallDir_NoLicenseMSI 并未使用 WiX 默认向导而是通过dialog.wxi定制了一套名为WixUI_InstallDir_NoLicense的界面即“可选安装目录、无许可证页”的变体并在ruffle.wxs中引用ui:WixUI IdWixUI_InstallDir_NoLicense InstallDirectoryINSTALLFOLDER/ WixVariable IdWixUIBannerBmp Valuebanner.png/ WixVariable IdWixUIDialogBmp Valuedialog.png/安装目录固定绑定到INSTALLFOLDER用户可在向导中浏览/修改安装位置界面横幅顶部 370x44 区域的BannerBitmap与对话框背景分别来自 banner.png 和 dialog.png。dialog.wxi的核心内容见 dialog.wxi包括针对三种架构X86/X64/A64生成的 UI 片段通过?foreach WIXUIARCH in X86;X64;A64 ?分别生成WixUI_InstallDir_NoLicense_X86等 UI并在BrowseDlg浏览目录与RuffleInstallDirDlg的“下一步”按钮上挂钩WixUIValidatePath_$(WIXUIARCH)路径校验动作ConditionNOT WIXUI_DONTVALIDATEPATH可通过设置WIXUI_DONTVALIDATEPATH关闭校验。自定义安装目录对话框RuffleInstallDirDlg这是一个 370x270 的标准 WiX 对话框Next/Back/Cancel 按钮、标题/描述文本、横幅位图、路径编辑框PathEdit、ChangeFolder浏览按钮并额外加入了一个桌面快捷方式复选框见 dialog.wxiControl IdDesktopShortcutCheckBox TypeCheckBox X20 Y160 Width290 Height17 PropertyINSTALLDESKTOPSHORTCUT CheckBoxValue1 TextCreate a shortcut for this program on the desktop./该复选框直接绑定前文 5.2 中DesktopShortcut组件的条件属性INSTALLDESKTOPSHORTCUT——勾选与否会实时决定桌面快捷方式是否被安装。完整的对话框流转序列见 dialog.wxi 与各Publish规则首次安装WelcomeDlg → RuffleInstallDirDlg → VerifyReadyDlg → DiskCostDlg维护已安装MaintenanceWelcomeDlg → MaintenanceTypeDlg修复/移除→ RuffleInstallDirDlg → VerifyReadyDlg补丁安装WelcomeDlg → VerifyReadyDlg目录校验失败时会弹出InvalidDirDlg浏览目录通过BrowseDlg完成。七、与桌面端构建产物的对应关系MSI 打包并非孤立流程它和ruffle_desktop的构建配置紧密相关可执行文件名ruffle.wxs安装的文件名是ruffle.exe与 desktop/Cargo.toml 中winresource声明的OriginalFilename ruffle.exe一致该元数据段还声明了ProductName Ruffle、FileDescription Adobe Flash Player emulator、CompanyName Ruffle LLC、LegalCopyright等 Windows 资源信息与 MSI 包元数据Name/Manufacturer相互呼应版本信息来源desktop/src/main.rs中RUFFLE_VERSION常量由CARGO_PKG_VERSION、Git 提交 SHA 等在编译期拼接生成见 desktop/src/main.rs而打包时要求手动设置的RUFFLE_VERSION环境变量则独立控制 MSI 版本号二者需注意保持同步避免安装包版本与程序内部版本不一致许可证文件MSI 安装的License组件直接引用仓库根目录的 LICENSE.md见 ruffle.wxs即 Ruffle 的 Apache-2.0/MIT 双许可文本。八、常见问题与注意事项版本号格式错误导致构建失败RUFFLE_VERSION必须形如1.2.3或1.2.3.4缺少段数或含非数字字符会导致wix build报错且第四段不参与 Windows 版本比较发布新版本时应递增前三段。exe 缺失构建前务必确认$(CARGO_BUILD_DIR)/ruffle_desktop.exe存在默认../../../../target/release否则打包会因找不到源文件失败。x86 与 x64 的选择-arch x64安装到Program Files-arch x86安装到Program Files (x86)请与你的ruffle_desktop.exe实际目标平台保持一致。同版本号无法“升级”由于 Windows 忽略版本号第四段连续发布两个1.2.3.x包时需依赖AllowSameVersionUpgradesyes的覆盖安装语义若希望并存测试可修改 ruffle.wxs 中的UpgradeCode。文件关联不生效MSI 只负责注册“打开方式”候选与 ProgId是否接管默认关联由 Windows 询问用户决定且重命名ruffle.exe会导致Open With中的条目失效见 ruffle.wxs 注释。.wixpdb体积不需要调试数据库时加上-pdbtype none可精简构建输出。九、小结Ruffle 的 Windows MSI 打包方案以 WiX v4 为工具链、以 ruffle.wxs 为配置核心配合 dialog.wxi 的自定义向导实现了安装目录选择、桌面快捷方式复选、.swf/.spl/.ruf文件关联、PATH 环境变量写入、主升级策略与Program Files目录权限等完整安装体验。只要遵循“先装 WiX 扩展、再构建ruffle_desktop.exe、设置RUFFLE_VERSION、执行wix build”四步流程即可在本地或 CI 中稳定产出可分发、可升级的.msi安装包。【免费下载链接】ruffleA Flash Player emulator written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/ruffle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考