distributing-tauri-for-windows

分发 Tauri Windows 应用

本指南介绍 Tauri v2 应用的 Windows 分发，包括创建和自定义 MSI/NSIS 安装程序，以及提交到 Microsoft Store。

安装程序格式概览

Tauri 支持两种 Windows 安装程序格式：

格式	扩展名	构建平台	备注
WiX MSI	.msi	仅限 Windows	传统 Windows 安装程序
NSIS	-setup.exe	跨平台	可在 Linux/macOS 上构建

构建安装程序

标准构建（Windows）

npm run tauri build
# or
yarn tauri build
# or
pnpm tauri build
# or
cargo tauri build

目标架构

# 64-bit (default)
npm run tauri build -- --target x86_64-pc-windows-msvc

# 32-bit
npm run tauri build -- --target i686-pc-windows-msvc

# ARM64 (requires additional VS build tools)
npm run tauri build -- --target aarch64-pc-windows-msvc

跨平台 NSIS 构建（Linux/macOS）

可在非 Windows 系统上构建 NSIS 安装程序：

前置条件（Linux）：

# Install NSIS and build tools (Debian/Ubuntu)
sudo apt install nsis lld llvm clang

# Install Windows Rust target
rustup target add x86_64-pc-windows-msvc

# Install cargo-xwin
cargo install --locked cargo-xwin

前置条件（macOS）：

# Install via Homebrew
brew install nsis llvm

# Add LLVM to PATH
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

# Install Windows Rust target
rustup target add x86_64-pc-windows-msvc

# Install cargo-xwin
cargo install --locked cargo-xwin

构建命令：

npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc

WebView2 安装模式

配置如何在终端用户的计算机上安装 WebView2 运行时：

模式	是否需要互联网	大小影响	适用场景
downloadBootstrapper	是	0 MB	默认，安装程序最小
embedBootstrapper	是	~1.8 MB	更好地支持 Windows 7
offlineInstaller	否	~127 MB	离线/隔离网络环境
fixedVersion	否	~180 MB	受控的企业部署
skip	否	0 MB	不推荐

配置

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "embedBootstrapper"  // or: downloadBootstrapper, offlineInstaller, fixedVersion
      }
    }
  }
}

对于 fixedVersion，添加路径："path": "./WebView2Runtime"

WiX MSI 自定义

自定义 WiX 模板

替换默认模板：

{
  "bundle": {
    "windows": {
      "wix": {
        "template": "./windows/custom-template.wxs"
      }
    }
  }
}

WiX 片段

通过 XML 片段添加自定义功能：

1. 创建片段文件（src-tauri/windows/fragments/registry.wxs）：

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Fragment>
    <ComponentGroup Id="MyFragmentRegistryEntries">
      <Component Id="MyRegistryEntry" Directory="INSTALLDIR">
        <RegistryKey Root="HKCU" Key="Software\MyApp">
          <RegistryValue Type="string" Name="InstallPath" Value="[INSTALLDIR]" KeyPath="yes"/>
        </RegistryKey>
      </Component>
    </ComponentGroup>
  </Fragment>
</Wix>

2. 在配置中引用：

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

国际化（WiX）

{
  "bundle": {
    "windows": {
      "wix": {
        "language": ["en-US", "fr-FR", "de-DE"],  // Single: "fr-FR"
        "localePath": "./windows/locales"  // Optional: custom locale files
      }
    }
  }
}

NSIS 安装程序自定义

安装模式

模式	是否需要管理员权限	安装位置	使用场景
perUser	否	%LOCALAPPDATA%	默认，无需提升权限
perMachine	是	%PROGRAMFILES%	全系统安装
both	是	由用户选择	灵活部署

{
  "bundle": {
    "windows": {
      "nsis": {
        "installMode": "perMachine"
      }
    }
  }
}

安装程序钩子

使用自定义 NSIS 脚本扩展安装流程：

1. 创建钩子文件（src-tauri/windows/hooks.nsh）：

!macro NSIS_HOOK_PREINSTALL
  ; Run before file installation
  DetailPrint "Preparing installation..."
!macroend

!macro NSIS_HOOK_POSTINSTALL
  ; Run after installation completes
  DetailPrint "Configuring application..."
  ; Example: Install VC++ Redistributable
  ReadRegStr $0 HKLM "SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64" "Installed"
  ${If} $0 != "1"
    ExecWait '"$INSTDIR\vc_redist.x64.exe" /quiet /norestart'
  ${EndIf}
!macroend

!macro NSIS_HOOK_PREUNINSTALL
  ; Run before uninstallation
  DetailPrint "Cleaning up..."
!macroend

!macro NSIS_HOOK_POSTUNINSTALL
  ; Run after uninstallation
  DetailPrint "Removal complete"
!macroend

2. 在配置中引用：

{
  "bundle": {
    "windows": {
      "nsis": {
        "installerHooks": "./windows/hooks.nsh"
      }
    }
  }
}

国际化（NSIS）

NSIS 安装程序支持在单个文件中包含多种语言：

{
  "bundle": {
    "windows": {
      "nsis": {
        "languages": ["English", "French", "German", "Spanish"],
        "displayLanguageSelector": true
      }
    }
  }
}

最低 WebView2 版本

要求特定的 WebView2 版本：

{
  "bundle": {
    "windows": {
      "nsis": {
        "minimumWebview2Version": "110.0.1531.0"
      }
    }
  }
}

完整配置示例

{
  "bundle": {
    "active": true,
    "targets": ["msi", "nsis"],
    "icon": ["icons/icon.ico"],
    "windows": {
      "certificateThumbprint": "YOUR_CERTIFICATE_THUMBPRINT",
      "timestampUrl": "http://timestamp.digicert.com",
      "webviewInstallMode": {
        "type": "embedBootstrapper"
      },
      "wix": {
        "language": ["en-US", "de-DE"],
        "fragmentPaths": ["./windows/fragments/registry.wxs"],
        "componentRefs": ["MyRegistryEntries"]
      },
      "nsis": {
        "installMode": "both",
        "installerHooks": "./windows/hooks.nsh",
        "languages": ["English", "German"],
        "displayLanguageSelector": true,
        "minimumWebview2Version": "110.0.1531.0"
      }
    }
  }
}

特殊配置

Windows 7 支持

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "embedBootstrapper"
      }
    }
  }
}

在 Cargo.toml 中启用 Windows 7 通知支持：

[dependencies]
tauri = { version = "2", features = ["windows7-compat"] }

FIPS 合规性

构建前设置环境变量：

PowerShell：

$env:TAURI_BUNDLER_WIX_FIPS_COMPLIANT = "true"
npm run tauri build

命令提示符：

set TAURI_BUNDLER_WIX_FIPS_COMPLIANT=true
npm run tauri build

Microsoft Store 分发

要求

1. 拥有已注册开发者计划的 Microsoft 帐户
2. 使用 WebView2 离线安装程序模式（Store 政策要求）
3. 发布者名称必须与产品名称不同

Store 专用配置

创建 tauri.microsoftstore.conf.json：

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "offlineInstaller"
      }
    }
  },
  "identifier": "com.yourcompany.yourapp",
  "publisher": "Your Company Name"
}

生成 Store 图标

npm run tauri icon /path/to/app-icon.png

这会生成所有所需的图标尺寸，包括 Microsoft Store 素材。

为 Store 构建

npm run tauri build -- --config tauri.microsoftstore.conf.json

提交流程

1. 使用离线安装程序配置进行构建
2. 使用有效的代码签名证书对安装程序签名
3. 在 Partner Center（Apps and Games）中创建应用列表
4. 预留唯一的应用名称
5. 将安装程序上传到分发服务
6. 在 Store 列表中添加安装程序 URL
7. 提交认证

发布者名称限制

发布者名称不能与产品名称相同。如果你的捆绑标识符为 com.myapp.myapp，请明确设置不同的发布者名称：

{
  "identifier": "com.myapp.myapp",
  "publisher": "MyApp Software Inc"
}

代码签名

使用证书指纹

{
  "bundle": {
    "windows": {
      "certificateThumbprint": "YOUR_CERTIFICATE_THUMBPRINT",
      "timestampUrl": "http://timestamp.digicert.com"
    }
  }
}

环境变量

# Certificate path
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="your-password"

# Or via tauri.conf.json

时间戳服务器

常用时间戳服务器：

• DigiCert：http://timestamp.digicert.com
• Sectigo：http://timestamp.sectigo.com
• GlobalSign：http://timestamp.globalsign.com/tsa/r6advanced1

故障排除

在非 Windows 系统上构建 MSI 失败

只能在 Windows 上使用 WiX Toolset 构建 MSI 文件。跨平台构建请使用 NSIS。

WebView2 未安装

1. 检查 WebView 安装模式配置
2. 在引导程序模式下，确认网络连接正常
3. 在离线模式下，确保安装程序的大小可以接受

NSIS 交叉编译错误

1. 确认已安装 NSIS，且其位于 PATH 中
2. 检查 LLVM/clang 是否已安装
3. 确保已安装 Windows Rust 目标
4. 确认已安装 cargo-xwin

找不到证书

1. 确认已在 Windows 证书存储区中安装证书
2. 检查指纹是否完全匹配（不含空格）
3. 确保证书具有私钥访问权限