Windows 安装程序
用于 Windows 的 Tauri 应用程序可以通过使用 WiX Toolset v3 的 Microsoft 安装程序(.msi
文件)或使用 NSIS 的安装可执行文件(-setup.exe
文件)进行分发。
请注意,.msi
安装程序**只能在 Windows 上创建**,因为 WiX 只能在 Windows 系统上运行。NSIS 安装程序的交叉编译如下所示。
本指南提供了有关安装程序可用自定义选项的信息。
要在 Windows 计算机上构建应用程序并将其打包为 Windows 安装程序,您可以使用 Tauri CLI 并运行 tauri build
命令
npm run tauri build
yarn tauri build
pnpm tauri build
deno task tauri build
bun tauri build
cargo tauri build
使用 NSIS 在 Linux 和 macOS 主机上交叉编译 Windows 应用程序是可能的,但有一些注意事项。它不像直接在 Windows 上编译那样简单,并且没有经过那么多测试。因此,如果本地 VM 或 GitHub Actions 等 CI 解决方案不适合您,它应该只作为最后的手段。
由于 Tauri 官方仅支持 MSVC Windows 目标,因此设置会稍微复杂一些。
某些 Linux 发行版在其存储库中提供 NSIS,例如在 Ubuntu 上,您可以通过运行此命令来安装 NSIS
sudo apt install nsis
但在许多其他发行版上,您必须自行编译 NSIS 或手动下载发行版二进制包中未包含的 Stubs 和 Plugins。例如,Fedora 仅提供二进制文件,不提供 Stubs 和 Plugins
sudo dnf in mingw64-nsiswget https://github.com/tauri-apps/binary-releases/releases/download/nsis-3/nsis-3.zipunzip nsis-3.zipsudo cp nsis-3.08/Stubs/* /usr/share/nsis/Stubs/sudo cp -r nsis-3.08/Plugins/** /usr/share/nsis/Plugins/
在 macOS 上,您将需要 [Homebrew] 来安装 NSIS
brew install nsis
由于默认的 Microsoft 链接器仅适用于 Windows,我们还需要安装一个新的链接器。为了编译用于设置应用程序图标等功能的 Windows 资源文件,我们还需要 llvm-rc
二进制文件,它是 LLVM 项目的一部分。
sudo apt install lld llvm
如果您添加了作为其构建脚本一部分编译 C/C++ 依赖项的依赖项,则在 Linux 上还需要安装 clang
包。默认的 Tauri 应用程序不应需要此功能。
brew install llvm
在 macOS 上,您还需要将 /opt/homebrew/opt/llvm/bin
添加到您的 $PATH
中,如安装输出中建议的那样。
假设您正在为 64 位 Windows 系统构建
rustup target add x86_64-pc-windows-msvc
我们将使用 [cargo-xwin
] 作为 Tauri 的“运行器”,而不是手动设置 Windows SDK。
cargo install --locked cargo-xwin
默认情况下,cargo-xwin
会将 Windows SDK 下载到项目本地文件夹中。如果您有多个项目并希望共享这些文件,则可以使用 XWIN_CACHE_DIR
环境变量设置首选位置的路径。
现在,只需将运行器和目标添加到 tauri build
命令即可
npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc
yarn tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc
pnpm tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc
deno task tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc
bun tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc
cargo tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc
构建输出将位于 target/x86_64-pc-windows-msvc/release/bundle/nsis/
。
Tauri CLI 默认使用您机器的架构编译您的可执行文件。假设您正在 64 位机器上开发,CLI 将生成 64 位应用程序。
如果您需要支持 32 位机器,您可以使用 --target
标志通过不同的 Rust 目标编译您的应用程序
npm run tauri build -- --target i686-pc-windows-msvc
yarn tauri build --target i686-pc-windows-msvc
pnpm tauri build --target i686-pc-windows-msvc
deno task tauri build --target i686-pc-windows-msvc
bun tauri build --target i686-pc-windows-msvc
cargo tauri build --target i686-pc-windows-msvc
默认情况下,Rust 仅为您机器的目标安装工具链,因此您需要首先安装 32 位 Windows 工具链:rustup target add i686-pc-windows-msvc
。
如果您需要为 ARM64 构建,您首先需要安装额外的构建工具。为此,打开 Visual Studio Installer
,单击“修改”,然后在“单个组件”选项卡中安装“C++ ARM64 构建工具”。撰写本文时,VS2022 中的确切名称是 MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)
。
现在您可以使用 rustup target add aarch64-pc-windows-msvc
添加 Rust 目标,然后使用上述方法编译您的应用程序
npm run tauri build -- --target aarch64-pc-windows-msvc
yarn tauri build --target aarch64-pc-windows-msvc
pnpm tauri build --target aarch64-pc-windows-msvc
deno task tauri build --target aarch64-pc-windows-msvc
bun tauri build --target aarch64-pc-windows-msvc
cargo tauri build --target aarch64-pc-windows-msvc
请注意,NSIS 安装程序本身仍将是 x86,通过仿真在 ARM 机器上运行。应用程序本身将是原生的 ARM64 二进制文件。
默认情况下,Microsoft 安装程序 (.msi
) 在 Windows 7 上无法运行,因为它需要下载 WebView2 引导程序(如果未安装),如果操作系统中未启用 TLS 1.2,则可能会失败。Tauri 包含一个嵌入 WebView2 引导程序的选项(请参阅下面的嵌入 WebView2 引导程序部分)。基于 NSIS 的安装程序(-setup.exe
)也支持 Windows 7 上的 downloadBootstrapper
模式。
此外,要在 Windows 7 中使用通知 API,您需要启用 windows7-compat
Cargo 功能
[dependencies]tauri-plugin-notification = { version = "2.0.0", features = [ "windows7-compat" ] }
如果您的系统要求 MSI 包符合 FIPS,您可以在运行 tauri build
之前将 TAURI_BUNDLER_WIX_FIPS_COMPLIANT
环境变量设置为 true
。在 PowerShell 中,您可以这样为当前终端会话设置它
$env:TAURI_BUNDLER_WIX_FIPS_COMPLIANT="true"
默认情况下,安装程序会下载 WebView2 引导程序并在未安装运行时时执行它。或者,您可以嵌入引导程序、嵌入离线安装程序或使用固定的 WebView2 运行时版本。下表比较了这些方法
安装方法 | 需要互联网连接吗? | 额外安装程序大小 | 备注 |
---|---|---|---|
下载引导程序 | 是 | 0MB | 默认 导致安装程序大小更小,但不建议通过 .msi 文件部署到 Windows 7。 |
嵌入引导程序 | 是 | 约 1.8MB | 更好地支持 Windows 7 上的 .msi 安装程序。 |
离线安装程序 | 否 | 约 127MB | 嵌入 WebView2 安装程序。建议用于离线环境。 |
固定版本 | 否 | 约 180MB | 嵌入固定版本的 WebView2。 |
跳过 | 否 | 0MB | ⚠️ 不推荐 不将 WebView2 作为 Windows 安装程序的一部分进行安装。 |
在 Windows 10(2018 年 4 月版或更高版本)和 Windows 11 上,WebView2 运行时作为操作系统的一部分分发。
这是构建 Windows 安装程序的默认设置。它会下载引导程序并运行它。需要互联网连接,但会导致安装程序更小。如果您要通过 .msi
安装程序分发到 Windows 7,则不推荐这样做。
{ "bundle": { "windows": { "webviewInstallMode": { "type": "downloadBootstrapper" } } }}
要嵌入 WebView2 引导程序,将 webviewInstallMode 设置为 embedBootstrapper
。这将使安装程序大小增加约 1.8MB,但会增加与 Windows 7 系统的兼容性。
{ "bundle": { "windows": { "webviewInstallMode": { "type": "embedBootstrapper" } } }}
要嵌入 WebView2 引导程序,请将 webviewInstallMode 设置为 offlineInstaller
。这将使安装程序大小增加约 127MB,但允许您的应用程序在没有互联网连接的情况下安装。
{ "bundle": { "windows": { "webviewInstallMode": { "type": "offlineInstaller" } } }}
使用系统提供的运行时对于安全性而言非常重要,因为 WebView 漏洞补丁由 Windows 管理。如果您想控制每个应用程序的 WebView2 分发(无论是自行管理发布补丁还是在没有互联网连接的环境中分发应用程序),Tauri 可以为您捆绑运行时文件。
- 从 Microsoft 网站下载 WebView2 固定版本运行时。在此示例中,下载的文件名为
Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab
- 将文件解压到核心文件夹
Expand .\Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab -F:* ./src-tauri
- 在
tauri.conf.json
中配置 WebView2 运行时路径
{ "bundle": { "windows": { "webviewInstallMode": { "type": "fixedRuntime", "path": "./Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64/" } } }}
- 运行
tauri build
以生成包含固定 WebView2 运行时的 Windows 安装程序。
通过将 webviewInstallMode 设置为 skip
,您可以从安装程序中移除 WebView2 运行时下载检查。如果用户未安装运行时,您的应用程序将无法工作。
如果用户未安装运行时,您的应用程序将无法工作,并且不会尝试安装它。
{ "bundle": { "windows": { "webviewInstallMode": { "type": "skip" } } }}
有关完整的自定义选项列表,请参阅 WiX 配置。
.msi
Windows 安装程序包是使用 WiX Toolset v3 构建的。目前,除了预定义的配置外,您还可以通过使用自定义 WiX 源代码(一个带有 .wxs
文件扩展名的 XML 文件)或通过 WiX 片段来更改它。
Tauri 定义的 Windows 安装程序 XML 配置为适用于基于简单 WebView 的应用程序的常见用例(您可以在此处找到它)。它使用 handlebars,因此 Tauri CLI 可以根据您的 tauri.conf.json
定义来定制您的安装程序。如果您需要一个完全不同的安装程序,可以在 tauri.bundle.windows.wix.template
上配置自定义模板文件。
WiX 片段是一个容器,您可以在其中配置 WiX 提供的几乎所有内容。在此示例中,我们将定义一个写入两个注册表项的片段
<?xml version="1.0" encoding="utf-8"?><Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Fragment> <!-- these registry entries should be installed to the target user's machine --> <DirectoryRef Id="TARGETDIR"> <!-- groups together the registry entries to be installed --> <!-- Note the unique `Id` we provide here --> <Component Id="MyFragmentRegistryEntries" Guid="*"> <!-- the registry key will be under HKEY_CURRENT_USER\Software\MyCompany\MyApplicationName --> <!-- Tauri uses the second portion of the bundle identifier as the `MyCompany` name (e.g. `tauri-apps` in `com.tauri-apps.test`) --> <RegistryKey Root="HKCU" Key="Software\MyCompany\MyApplicationName" Action="createAndRemoveOnUninstall" > <!-- values to persist on the registry --> <RegistryValue Type="integer" Name="SomeIntegerValue" Value="1" KeyPath="yes" /> <RegistryValue Type="string" Value="Default Value" /> </RegistryKey> </Component> </DirectoryRef> </Fragment></Wix>
将片段文件以 .wxs
扩展名保存在 src-tauri/windows/fragments
文件夹中,并在 tauri.conf.json
中引用它
{ "bundle": { "windows": { "wix": { "fragmentPaths": ["./windows/fragments/registry.wxs"], "componentRefs": ["MyFragmentRegistryEntries"] } } }}
请注意,ComponentGroup
、Component
、FeatureGroup
、Feature
和 Merge
元素 ID 必须在 tauri.conf.json
的 wix
对象中的 componentGroupRefs
、componentRefs
、featureGroupRefs
、featureRefs
和 mergeRefs
中分别引用,才能包含在安装程序中。
WiX 安装程序默认使用 en-US
语言构建。国际化 (i18n) 可以使用 tauri.bundle.windows.wix.language
属性进行配置,该属性定义了 Tauri 应该针对哪些语言构建安装程序。您可以在 Microsoft 网站上的 Language-Culture 列中找到要使用的语言名称。
要创建针对特定语言的单个安装程序,请将 language
值设置为字符串
{ "bundle": { "windows": { "wix": { "language": "fr-FR" } } }}
要编译针对多种语言的安装程序,请使用数组。将为每种语言创建一个特定的安装程序,并以语言键作为后缀
{ "bundle": { "windows": { "wix": { "language": ["en-US", "pt-BR", "fr-FR"] } } }}
可以为每种语言定义一个配置对象以配置本地化字符串
{ "bundle": { "windows": { "wix": { "language": { "en-US": null, "pt-BR": { "localePath": "./wix/locales/pt-BR.wxl" } } } } }}
localePath
属性定义了语言文件的路径,一个配置语言文化的 XML
<WixLocalization Culture="en-US" xmlns="http://schemas.microsoft.com/wix/2006/localization"> <String Id="LaunchApp"> Launch MyApplicationName </String> <String Id="DowngradeErrorMessage"> A newer version of MyApplicationName is already installed. </String> <String Id="PathEnvVarFeature"> Add the install location of the MyApplicationName executable to the PATH system environment variable. This allows the MyApplicationName executable to be called from any location. </String> <String Id="InstallAppFeature"> Installs MyApplicationName. </String></WixLocalization>
目前,Tauri 引用以下区域设置字符串:LaunchApp
、DowngradeErrorMessage
、PathEnvVarFeature
和 InstallAppFeature
。您可以定义自己的字符串,并在自定义模板或片段中用 "!(loc.TheStringId)"
引用它们。有关更多信息,请参阅 WiX 本地化文档。
有关完整的自定义选项列表,请参阅 NSIS 配置。
Tauri 定义的 NSIS 安装程序 .nsi
脚本配置为适用于简单 WebView 应用程序的常见用例(您可以在此处找到它)。它使用 handlebars,因此 Tauri CLI 可以根据您的 tauri.conf.json
定义来定制您的安装程序。如果您需要一个完全不同的安装程序,可以在 tauri.bundle.windows.nsis.template
上配置自定义模板文件。
如果您只需要扩展一些安装步骤,则可以使用安装程序挂钩,而不是替换整个安装程序模板。
支持的挂钩有
NSIS_HOOK_PREINSTALL
: 在复制文件、设置注册表项值和创建快捷方式之前运行。NSIS_HOOK_POSTINSTALL
: 在安装程序完成所有文件复制、设置注册表项和创建快捷方式之后运行。NSIS_HOOK_PREUNINSTALL
: 在删除任何文件、注册表项和快捷方式之前运行。NSIS_HOOK_POSTUNINSTALL
: 在文件、注册表项和快捷方式被删除之后运行。
例如,在 src-tauri/windows
文件夹中创建 hooks.nsh
文件并定义您需要的挂钩
!macro NSIS_HOOK_PREINSTALL MessageBox MB_OK "PreInstall"!macroend
!macro NSIS_HOOK_POSTINSTALL MessageBox MB_OK "PostInstall"!macroend
!macro NSIS_HOOK_PREUNINSTALL MessageBox MB_OK "PreUnInstall"!macroend
!macro NSIS_HOOK_POSTUNINSTALL MessageBox MB_OK "PostUninstall"!macroend
然后您必须配置 Tauri 来使用该挂钩文件
{ "bundle": { "windows": { "nsis": { "installerHooks": "./windows/hooks.nsh" } } }}
您可以使用安装程序挂钩自动安装应用程序所需的系统依赖项。这对于 Visual C++ Redistributables、DirectX、OpenSSL 或其他可能并非所有 Windows 系统都存在的系统库等运行时依赖项特别有用。
MSI 安装程序示例(Visual C++ 可再发行组件)
!macro NSIS_HOOK_POSTINSTALL ; Check if Visual C++ 2019 Redistributable is installed (via Windows Registry) ReadRegDWord $0 HKLM "SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64" "Installed"
${If} $0 == 1 DetailPrint "Visual C++ Redistributable already installed" Goto vcredist_done ${EndIf}
; Install from bundled MSI if not installed ${If} ${FileExists} "$INSTDIR\resources\vc_redist.x64.msi" DetailPrint "Installing Visual C++ Redistributable..." ; Copy to TEMP folder and then execute installer CopyFiles "$INSTDIR\resources\vc_redist.x64.msi" "$TEMP\vc_redist.x64.msi" ExecWait 'msiexec /i "$TEMP\vc_redist.x64.msi" /passive /norestart' $0
; Check wether installation process exited successfully (code 0) or not ${If} $0 == 0 DetailPrint "Visual C++ Redistributable installed successfully" ${Else} MessageBox MB_ICONEXCLAMATION "Visual C++ installation failed. Some features may not work." ${EndIf}
; Clean up setup files from TEMP and your installed app Delete "$TEMP\vc_redist.x64.msi" Delete "$INSTDIR\resources\vc_redist.x64.msi" ${EndIf}
vcredist_done:!macroend
主要注意事项
- 一个好的做法是始终使用注册表项、文件是否存在或通过 Windows where 命令检查依赖项是否已安装。
- 使用
/passive
、/quiet
或/silent
标志以避免中断安装流程。检查 msiexec 选项以了解.msi
文件,或查看应用程序特定标志的设置手册 - 包含
/norestart
以防止在安装过程中自动重新启动系统,适用于重新启动用户设备的设置 - 清理临时文件和捆绑的安装程序,以避免应用程序膨胀
- 考虑在卸载时依赖项可能与其他应用程序共享
- 如果安装失败,提供有意义的错误消息
确保将依赖项安装程序捆绑到 src-tauri/resources
文件夹中,并添加到 tauri.conf.json
,以便它们在安装过程中可以从 $INSTDIR\resources\
访问
{ "bundle": { "resources": [ "resources/my-dependency.exe", "resources/another-one.msi ] }}
默认情况下,安装程序只会为当前用户安装您的应用程序。此选项的优点是安装程序不需要管理员权限即可运行,但应用程序会安装在 %LOCALAPPDATA%
文件夹中,而不是 C:/Program Files
。
如果您希望您的应用程序安装可在系统范围内使用(这需要管理员权限),您可以将 installMode 设置为 perMachine
{ "bundle": { "windows": { "nsis": { "installMode": "perMachine" } } }}
或者,您可以通过将 installMode 设置为 both
,让用户选择应用程序是仅为当前用户安装还是系统范围安装。请注意,安装程序需要管理员权限才能执行。
有关更多信息,请参阅 NSISInstallerMode。
NSIS 安装程序是一个多语言安装程序,这意味着您始终只有一个安装程序,其中包含所有选定的翻译。
您可以使用 tauri.bundle.windows.nsis.languages
属性指定要包含的语言。NSIS 支持的语言列表可在 NSIS GitHub 项目中找到。需要一些 Tauri 特定翻译,因此如果您看到未翻译的文本,请随时在 Tauri 的主仓库中提出功能请求。您还可以提供自定义翻译文件。
默认情况下,操作系统默认语言用于确定安装程序语言。您还可以配置安装程序在渲染安装程序内容之前显示语言选择器
{ "bundle": { "windows": { "nsis": { "displayLanguageSelector": true } } }}
如果您的应用程序需要仅在较新 WebView2 版本中可用的功能(例如自定义 URI 方案),您可以指示 Windows 安装程序验证当前 WebView2 版本,如果与目标版本不匹配,则运行 WebView2 引导程序。
{ "bundle": { "windows": { "nsis": { "minimumWebview2Version": "110.0.1531.0" } } }}
© 2025 Tauri 贡献者。CC-BY / MIT