跳到内容
Tauri

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

使用 NSIS 在 Linux 和 macOS 主机上交叉编译 Windows 应用程序是可能的,但有一些注意事项。它不像直接在 Windows 上编译那样简单,并且没有经过那么多测试。因此,如果本地 VM 或 GitHub Actions 等 CI 解决方案不适合您,它应该只作为最后的手段。

由于 Tauri 官方仅支持 MSVC Windows 目标,因此设置会稍微复杂一些。

某些 Linux 发行版在其存储库中提供 NSIS,例如在 Ubuntu 上,您可以通过运行此命令来安装 NSIS

Ubuntu
sudo apt install nsis

但在许多其他发行版上,您必须自行编译 NSIS 或手动下载发行版二进制包中未包含的 Stubs 和 Plugins。例如,Fedora 仅提供二进制文件,不提供 Stubs 和 Plugins

Fedora
sudo dnf in mingw64-nsis
wget https://github.com/tauri-apps/binary-releases/releases/download/nsis-3/nsis-3.zip
unzip nsis-3.zip
sudo cp nsis-3.08/Stubs/* /usr/share/nsis/Stubs/
sudo cp -r nsis-3.08/Plugins/** /usr/share/nsis/Plugins/

由于默认的 Microsoft 链接器仅适用于 Windows,我们还需要安装一个新的链接器。为了编译用于设置应用程序图标等功能的 Windows 资源文件,我们还需要 llvm-rc 二进制文件,它是 LLVM 项目的一部分。

Ubuntu
sudo apt install lld llvm

如果您添加了作为其构建脚本一部分编译 C/C++ 依赖项的依赖项,则在 Linux 上还需要安装 clang 包。默认的 Tauri 应用程序不应需要此功能。

假设您正在为 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

构建输出将位于 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

默认情况下,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

请注意,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 功能

Cargo.toml
[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,则不推荐这样做。

tauri.conf.json
{
"bundle": {
"windows": {
"webviewInstallMode": {
"type": "downloadBootstrapper"
}
}
}
}

要嵌入 WebView2 引导程序,将 webviewInstallMode 设置为 embedBootstrapper。这将使安装程序大小增加约 1.8MB,但会增加与 Windows 7 系统的兼容性。

tauri.conf.json
{
"bundle": {
"windows": {
"webviewInstallMode": {
"type": "embedBootstrapper"
}
}
}
}

要嵌入 WebView2 引导程序,请将 webviewInstallMode 设置为 offlineInstaller。这将使安装程序大小增加约 127MB,但允许您的应用程序在没有互联网连接的情况下安装。

tauri.conf.json
{
"bundle": {
"windows": {
"webviewInstallMode": {
"type": "offlineInstaller"
}
}
}
}

使用系统提供的运行时对于安全性而言非常重要,因为 WebView 漏洞补丁由 Windows 管理。如果您想控制每个应用程序的 WebView2 分发(无论是自行管理发布补丁还是在没有互联网连接的环境中分发应用程序),Tauri 可以为您捆绑运行时文件。

  1. Microsoft 网站下载 WebView2 固定版本运行时。在此示例中,下载的文件名为 Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab
  2. 将文件解压到核心文件夹
终端窗口
Expand .\Microsoft.WebView2.FixedVersionRuntime.128.0.2739.42.x64.cab -F:* ./src-tauri
  1. tauri.conf.json 中配置 WebView2 运行时路径
tauri.conf.json
{
"bundle": {
"windows": {
"webviewInstallMode": {
"type": "fixedRuntime",
"path": "./Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64/"
}
}
}
}
  1. 运行 tauri build 以生成包含固定 WebView2 运行时的 Windows 安装程序。

通过将 webviewInstallMode 设置为 skip,您可以从安装程序中移除 WebView2 运行时下载检查。如果用户未安装运行时,您的应用程序将无法工作。

如果用户未安装运行时,您的应用程序将无法工作,并且不会尝试安装它。

tauri.conf.json
{
"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 中引用它

tauri.conf.json
{
"bundle": {
"windows": {
"wix": {
"fragmentPaths": ["./windows/fragments/registry.wxs"],
"componentRefs": ["MyFragmentRegistryEntries"]
}
}
}
}

请注意,ComponentGroupComponentFeatureGroupFeatureMerge 元素 ID 必须在 tauri.conf.jsonwix 对象中的 componentGroupRefscomponentRefsfeatureGroupRefsfeatureRefsmergeRefs 中分别引用,才能包含在安装程序中。

WiX 安装程序默认使用 en-US 语言构建。国际化 (i18n) 可以使用 tauri.bundle.windows.wix.language 属性进行配置,该属性定义了 Tauri 应该针对哪些语言构建安装程序。您可以在 Microsoft 网站上的 Language-Culture 列中找到要使用的语言名称。

要创建针对特定语言的单个安装程序,请将 language 值设置为字符串

tauri.conf.json
{
"bundle": {
"windows": {
"wix": {
"language": "fr-FR"
}
}
}
}

要编译针对多种语言的安装程序,请使用数组。将为每种语言创建一个特定的安装程序,并以语言键作为后缀

tauri.conf.json
{
"bundle": {
"windows": {
"wix": {
"language": ["en-US", "pt-BR", "fr-FR"]
}
}
}
}

可以为每种语言定义一个配置对象以配置本地化字符串

tauri.conf.json
{
"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 引用以下区域设置字符串:LaunchAppDowngradeErrorMessagePathEnvVarFeatureInstallAppFeature。您可以定义自己的字符串,并在自定义模板或片段中用 "!(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 来使用该挂钩文件

tauri.conf.json
{
"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\ 访问

tauri.conf.json
{
"bundle": {
"resources": [
"resources/my-dependency.exe",
"resources/another-one.msi
]
}
}

默认情况下,安装程序只会为当前用户安装您的应用程序。此选项的优点是安装程序不需要管理员权限即可运行,但应用程序会安装在 %LOCALAPPDATA% 文件夹中,而不是 C:/Program Files

如果您希望您的应用程序安装可在系统范围内使用(这需要管理员权限),您可以将 installMode 设置为 perMachine

tauri.conf.json
{
"bundle": {
"windows": {
"nsis": {
"installMode": "perMachine"
}
}
}
}

或者,您可以通过将 installMode 设置为 both,让用户选择应用程序是仅为当前用户安装还是系统范围安装。请注意,安装程序需要管理员权限才能执行。

有关更多信息,请参阅 NSISInstallerMode

NSIS 安装程序是一个多语言安装程序,这意味着您始终只有一个安装程序,其中包含所有选定的翻译。

您可以使用 tauri.bundle.windows.nsis.languages 属性指定要包含的语言。NSIS 支持的语言列表可在 NSIS GitHub 项目中找到。需要一些 Tauri 特定翻译,因此如果您看到未翻译的文本,请随时在 Tauri 的主仓库中提出功能请求。您还可以提供自定义翻译文件

默认情况下,操作系统默认语言用于确定安装程序语言。您还可以配置安装程序在渲染安装程序内容之前显示语言选择器

tauri.conf.json
{
"bundle": {
"windows": {
"nsis": {
"displayLanguageSelector": true
}
}
}
}

如果您的应用程序需要仅在较新 WebView2 版本中可用的功能(例如自定义 URI 方案),您可以指示 Windows 安装程序验证当前 WebView2 版本,如果与目标版本不匹配,则运行 WebView2 引导程序。

tauri.conf.json
{
"bundle": {
"windows": {
"nsis": {
"minimumWebview2Version": "110.0.1531.0"
}
}
}
}

© 2025 Tauri 贡献者。CC-BY / MIT