部署)
windows-reactor-setup 使用指南为 Windows Reactor 应用构建自包含Self-Contained部署【免费下载链接】windows-rsRust for Windows项目地址: https://gitcode.com/GitHub_Trending/wi/windows-rswindows-reactor-setup是 Rust for Windowswindows-rs仓库中的一个构建期build-time辅助 crate职责是暂存stagingWindows App SDK 运行时与 WebView2 投影程序集使基于windows-reactor构建的 WinUI 3 应用可以完全不依赖目标机器上安装的框架包直接以自带运行时的自包含形态分发与运行。本文以 docs/crates/windows-reactor-setup.md 为主线结合 crates/libs/reactor-setup 的源码、资源清单与 crates/samples/reactor/self_contained 参考工程完整讲解它的适用场景、接入方式、构建期内幕、部署打包要点与故障排查方法。什么时候该用它三种部署形态的取舍windows-reactor-setup只在一种情况下使用你的windows-reactor可执行程序必须在自己旁边携带一份私有的 Windows App SDK 运行时自包含部署。它是从build.rs调用的构建依赖不是运行时 API因此绝不应出现在[dependencies]中。与之相对的另外两种形态明确不需要它部署形态运行时来源是否需要windows-reactor-setup自包含self-contained可执行文件旁暂存的私有运行时文件需要框架依赖framework-dependent启动时解析机器上已安装的 Windows App SDK 框架包不需要windows-reactor已内联框架引导逻辑纯windows-webviewHWND 宿主WebView2 Evergreen 运行时提供 COM 路径不需要原文档特别强调两点边界框架依赖应用不要用它。windows-reactor内部已经包含了框架引导framework bootstrap逻辑会在启动时解析已安装的 Windows App SDK 框架包这种模式不暂存任何私有运行时文件。纯 HWND 的 WebView2 宿主不要用它。WebView2 Evergreen 运行时已经覆盖了纯 COM 路径但 Reactor 的 XAML WebView2 控件额外需要一个投影 DLLMicrosoft.Web.WebView2.Core.dll这个额外的需求正是windows-reactor-setup为自包含 Reactor 应用处理的。前置条件在把windows-reactor-setup接入项目之前确认满足以下条件Cargo 目标操作系统必须是 Windows源码中assert_windows()会检查CARGO_CFG_TARGET_OS非windows直接 panic见 src/lib.rs。首次构建需要网络访问每个固定的 NuGet 包首次暂存时需要下载。%SystemRoot%\System32\curl.exe与tar.exe必须存在源码分别用它们下载.nupkgdl_nupkg与解包extract_tar见 src/lib.rs。目标必须使用 MSVC或清单链接参数所支持的基于 LLVM 的 GNU ABI源码只处理(msvc, _)与(gnu, llvm)两种组合其余 panic见 src/lib.rs。目标架构映射固定x86→x86aarch64→arm64其他 Rust 目标架构一律 →x64见 src/lib.rs 的target_arch()。注意target_arch()的返回值同时用于 MSIX 解包路径win10-{arch}和 WebView2 包路径win-{arch}架构映射不正确会导致找不到文件、暂存静默失败。快速上手构建依赖与一行 build.rs在Cargo.toml的[build-dependencies]中加入 crateREADME 的完整声明见 crates/libs/reactor-setup/readme.md[build-dependencies] windows-reactor-setup 0.100然后创建build.rs调用入口函数windows_reactor_setup::as_self_contained();就这么简单——整个自包含暂存流程下载、解包、拷贝、写清单、传链接参数全部发生在构建脚本中应用代码无需任何改动。参考工程 crates/samples/reactor/self_contained/Cargo.toml 的[build-dependencies]一节就是这样声明的示例工程使用 workspace 版本实际发布到 crates.io 的版本声明为0.100级别。需要强调的架构定位as_self_contained()没有Result返回值。它要么把一切布置妥当要么在构建期直接 panic 或打印诊断信息。它是一次调用、全部搞定的构建期副作用函数。第一个工作流产出自包含构建原文档给出了完整六步操作流程这是实践的核心骨架在[build-dependencies]中加入windows-reactor-setup。创建build.rs并调用windows_reactor_setup::as_self_contained()。正常用 Cargo 构建应用如cargo build。从 Cargo profile 输出目录直接运行可执行文件确认暂存运行时被实际使用。打包时把该输出目录中的可执行文件、所有暂存 DLL 与运行时目录一起打包并保持它们之间的相对布局不变。在一台没有提供框架依赖构建所需框架包的机器上测试打包目录验证自包含有效性。crates/samples/reactor/self_contained是参考工程布局其 main.rs 就是一个最小 Hello World Reactor 组件Cargo.toml中仅多了[build-dependencies]一节即可产出携带完整 Windows App Runtime 的自包含可执行文件。crates/samples/reactor/webview展示了同一套 setup 在包含 XAML WebView2 控件的 Reactor 应用中的用法它的 Cargo.toml 在依赖中启用了windows-webview的reactorfeature同时照常声明windows-reactor-setup作为构建依赖。构建步骤内幕as_self_contained 到底做了什么as_self_contained在应用构建期间依次执行以下操作对应 src/lib.rs 的实现顺序解析 Cargo profile 输出目录依据OUT_DIR与PROFILE定位。target_dir_from_out先尝试从OUT_DIR向上找到文件名为PROFILE的最近祖先目录找不到再回退到约定深度ancestors().nth(3)见 src/lib.rs。下载并缓存固定的Microsoft.WindowsAppSDK.RuntimeNuGet 包固定版本为2.4.0常量RUNTIME_VER。下载走 NuGet v2 包地址https://www.nuget.org/api/v2/package/{name}/{version}。为当前目标架构解包 MSIX路径为包内MSIX/win10-{arch}/Microsoft.WindowsAppRuntime.2.msix解包到独立的.msix_extract目录见ensure_msix_extracted。把允许清单内的 Windows App Runtime 文件拷贝到 profile 输出目录copy_runtime_to只处理assets/runtime.txt中列出的顶层条目目录条目则递归整体拷贝。下载并缓存固定的Microsoft.Web.WebView2NuGet 包固定版本为1.0.4078.44常量WEBVIEW2_VER。把目标架构native_uap/Microsoft.Web.WebView2.Core.dll拷贝到可执行文件旁deploy_webview2从win-{arch}/native_uap/下取这个投影 DLL见 src/lib.rs。写入包含自包含部署标记的应用清单模板为 assets/app.manifestas_self_contained在开头的assembly ...元素之后插入descriptionwindows-reactor-self-contained/description标记常量SELF_CONTAINED_MARKER写结果到OUT_DIR/app.manifest。传递内嵌清单的链接器参数对 MSVC 输出/MANIFEST:EMBED与/MANIFESTINPUT:path对 LLVM GNU 输出-Wl,/MANIFEST:EMBED与-Wl,/MANIFESTINPUT:path。仅作用于二进制目标cargo:rustc-link-arg-bins。缓存机制下载的.nupkg与解包目录都缓存在%LOCALAPPDATA%\windows-reactor-setup\temp当LOCALAPPDATA可用时。Cargo 可能重跑构建脚本但有了包缓存和解包目录就不会每次构建都重复下载。从源码看缓存目录的选择还支持回退链LOCALAPPDATA→XDG_CACHE_HOME→HOME/.cache三者都缺失时才 panic见 src/lib.rs。暂存文件清单runtime.txt拷贝哪些文件由 assets/runtime.txt 这份手维护的允许清单决定。它包含两部分顶层运行时文件如microsoft.ui.xaml.dll、microsoft.ui.xaml.controls.dll、microsoft.ui.input.dll、microsoft.windowsappruntime.dll、microsoft.ui.pri、resources.pri、dwmcorei.dll、marshal.dll、mrm.dll、wuceffectsi.dll等三十余个 DLL/PRI 文件多语言资源目录af-za、ar-sa、zh-cn、zh-tw等一百多个 locale 目录名匹配时忽略大小写。copy_runtime_to对该清单做大小写不敏感的匹配eq_ignore_ascii_case文件条目单文件拷贝目录条目递归整体拷贝到目标目录下同名子目录。务必让这份清单与固定的 Windows App SDK 运行时保持同步——它决定了最终自包含部署包含哪些文件。应用清单app.manifestassets/app.manifest 是一份 2800 余行的完整 Win32/WinRT 应用清单模板覆盖了Microsoft.UI.Xaml.Controls.dll含WebView2、NavigationView、InfoBar等大量控件、Microsoft.UI.Input.dll、Microsoft.UI.Windowing.dll、Microsoft.WindowsAppRuntime.dll含DeploymentManager、PackageDeploymentManager、PushNotificationManager等在内的激活类activatable class注册。as_self_contained在其中插入部署标记后写入OUT_DIR再经链接器嵌入二进制。部署与共享目标目录打包的红线原文档对本节有两个反复强调的关键告诫Cargo profile 目录可能包含多个包的输出。请从干净的、已知的构建 profile 暂存应用并把可执行文件旁所需的每个运行时文件和子目录都拷贝齐。只拷贝.exe不会得到自包含部署——必须连同Microsoft.WindowsAppRuntime.dll、Microsoft.UI.Xaml.dll等全套运行时文件与resources.pri、microsoft.ui.pri等资源一起且保持相对布局。部署标记是自包含/框架依赖的分水岭。内嵌清单包含windows-reactor-self-contained描述标记Reactor 读取该标记来选择私有运行时。反之框架依赖的可执行文件会忽略自包含构建遗留在同一 Cargo target 目录中的私有文件改用其内联的框架引导逻辑。另外要理解Microsoft.Web.WebView2.Core.dll的定位它总是被暂存这让自包含应用无需额外部署步骤即可启用windows-webview的reactorfeature。它是 XAML WebView2 控件使用的 WinRT 投影程序集不是COM-only 托管所用的webview2loader.dll后者由 Evergreen 运行时提供机器上本来就有的东西。失败处理与清理由于as_self_contained没有Result返回失败通过两种途径暴露panic硬失败不支持的目标配置、缺少 Cargo 环境变量如OUT_DIR、CARGO_CFG_TARGET_ENV未设置会直接让构建脚本 panic。打印诊断软失败下载、解包、单个文件拷贝失败时helper 会打印信息如Download failed for {name} {version}、MSIX not found at ...、{name} not found at ...。此时需要检查构建输出和 profile 目录找出缺失的暂存文件。由此引出的运维要点首次构建必须有可靠的 NuGet 访问。离线构建环境中应在断网前先把 helper 的包缓存准备好或直接使用带所需缓存的构建环境。不要在其他构建正在使用缓存时删除它。暂存文件在 Cargo profile 输出目录不在包的OUT_DIR。cargo clean会清掉 target 输出但不会清掉LOCALAPPDATA下的包缓存。只有需要强制重新下载包、或从损坏的部分下载中恢复时才手动删除那个特定缓存目录。不要手工替换暂存文件。helper 拷贝的是固定包版本WindowsAppSDK.Runtime 2.4.0、WebView2 1.0.4078.44升级应通过更新 crate 完成以保证清单、运行时允许清单与 WebView2 投影三者保持兼容。面向贡献者的内部实现要点原文档最后一部分是面向windows-reactor-setup贡献者的内部文档摘要如下as_self_contained校验CARGO_CFG_TARGET_OS从最近匹配PROFILE的祖先目录推导目标目录并回退到约定的祖先深度。单元测试覆盖了标准与 split-package 两种OUT_DIR布局——见 src/lib.rs 的tests模块标准布局C:\repo\target\debug\build\package-hash\out与拆分布局C:\repo\target\debug\build\package\hash\out都能正确定位到C:\repo\target\debug。stage_pkg缓存.nupkg文件与解包后的包目录运行时 MSIX 解包使用独立的.msix_extract目录。copy_runtime_to只拷贝assets/runtime.txt中列出的顶层条目再递归保留被选中的目录。应用清单模板是assets/app.manifest函数在起始 assembly 元素后插入部署标记把结果写入OUT_DIR并对 MSVC 或 LLVM GNU 目标发出仅针对二进制bins的清单链接参数。deploy_webview2从固定 WebView2 包的按架构native_uap目录拷贝Microsoft.Web.WebView2.Core.dll其包版本需要与windows-webview及 Reactor 使用的 WinRT 元数据、XAML WebView2 桥保持兼容。相关资源导航主文档docs/crates/windows-reactor-setup.md本文的原始依据上游 Reactor 指南docs/crates/windows-reactor.md含Deployment一节对两种样本的对比指引Crate README 与声明crates/libs/reactor-setup/readme.md、crates/libs/reactor-setup/Cargo.toml实现源码crates/libs/reactor-setup/src/lib.rs资源清单与清单模板crates/libs/reactor-setup/assets/runtime.txt、crates/libs/reactor-setup/assets/app.manifest参考工程crates/samples/reactor/self_contained纯 Reactor 自包含、crates/samples/reactor/webview含 XAML WebView2 的自包含 Reactor 应用【免费下载链接】windows-rsRust for Windows项目地址: https://gitcode.com/GitHub_Trending/wi/windows-rs创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考