distributing-tauri-for-windows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Distributing Tauri Applications for Windows

Tauri应用Windows分发指南

This skill covers Windows distribution for Tauri v2 applications, including MSI/NSIS installer creation, customization, and Microsoft Store submission.

本技能涵盖Tauri v2应用的Windows分发内容，包括MSI/NSIS安装程序创建、自定义配置，以及Microsoft Store提交流程。

Installer Formats Overview

安装程序格式概述

Tauri supports two Windows installer formats:

Format	Extension	Build Platform	Notes
WiX MSI	`.msi`	Windows only	Traditional Windows installer
NSIS	`-setup.exe`	Cross-platform	Can build on Linux/macOS

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

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

Building Installers

构建安装程序

Standard Build (Windows)

标准构建（Windows）

bash

npm run tauri build

bash

npm run tauri build

or

yarn tauri build

or

pnpm tauri build

or

cargo tauri build

undefined

cargo tauri build

undefined

Target Architectures

目标架构

bash

undefined

bash

undefined

64-bit (default)

64位（默认）

npm run tauri build -- --target x86_64-pc-windows-msvc

32-bit

32位

npm run tauri build -- --target i686-pc-windows-msvc

ARM64 (requires additional VS build tools)

ARM64（需要额外VS构建工具）

npm run tauri build -- --target aarch64-pc-windows-msvc

undefined

npm run tauri build -- --target aarch64-pc-windows-msvc

undefined

Cross-Platform NSIS Build (Linux/macOS)

跨平台NSIS构建（Linux/macOS）

NSIS installers can be built on non-Windows systems:

Prerequisites (Linux):

bash

undefined

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

前置依赖（Linux）：

bash

undefined

Install NSIS and build tools (Debian/Ubuntu)

安装NSIS和构建工具（Debian/Ubuntu）

sudo apt install nsis lld llvm clang

Install Windows Rust target

安装Windows Rust目标

rustup target add x86_64-pc-windows-msvc

Install cargo-xwin

安装cargo-xwin

cargo install --locked cargo-xwin


**Prerequisites (macOS):**
```bash

cargo install --locked cargo-xwin


**前置依赖（macOS）：**
```bash

Install via Homebrew

通过Homebrew安装

brew install nsis llvm

Add LLVM to PATH

将LLVM添加至PATH

export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

Install Windows Rust target

安装Windows Rust目标

rustup target add x86_64-pc-windows-msvc

Install cargo-xwin

安装cargo-xwin

cargo install --locked cargo-xwin


**Build command:**
```bash
npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc

cargo install --locked cargo-xwin


**构建命令：**
```bash
npm run tauri build -- --runner cargo-xwin --target x86_64-pc-windows-msvc

WebView2 Installation Modes

WebView2安装模式

Configure how WebView2 runtime is installed on end-user machines:

Mode	Internet Required	Size Impact	Best For
`downloadBootstrapper`	Yes	0 MB	Default, smallest installer
`embedBootstrapper`	Yes	~1.8 MB	Better Windows 7 support
`offlineInstaller`	No	~127 MB	Offline/air-gapped environments
`fixedVersion`	No	~180 MB	Controlled enterprise deployment
`skip`	No	0 MB	Not recommended

配置终端用户机器上WebView2运行时的安装方式：

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

Configuration

配置方式

json

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

For

fixedVersion

, add the path:

"path": "./WebView2Runtime"

json

{
  "bundle": {
    "windows": {
      "webviewInstallMode": {
        "type": "embedBootstrapper"  // 可选值：downloadBootstrapper, offlineInstaller, fixedVersion
      }
    }
  }
}

若使用

fixedVersion

，需添加路径配置：

"path": "./WebView2Runtime"

WiX MSI Customization

WiX MSI自定义配置

Custom WiX Template

自定义WiX模板

Replace the default template:

json

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

替换默认模板：

json

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

WiX Fragments

WiX片段

Add custom functionality via XML fragments:

1. Create fragment file (

src-tauri/windows/fragments/registry.wxs

xml

<?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. Reference in configuration:

json

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

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

1. 创建片段文件（

src-tauri/windows/fragments/registry.wxs

）：

xml

<?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. 在配置中引用：

json

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

Internationalization (WiX)

国际化配置（WiX）

json

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

json

{
  "bundle": {
    "windows": {
      "wix": {
        "language": ["en-US", "fr-FR", "de-DE"],  // 单一语言示例："fr-FR"
        "localePath": "./windows/locales"  // 可选：自定义语言文件路径
      }
    }
  }
}

NSIS Installer Customization

NSIS安装程序自定义配置

Install Modes

安装模式

Mode	Admin Required	Install Location	Use Case
`perUser`	No	`%LOCALAPPDATA%`	Default, no elevation
`perMachine`	Yes	`%PROGRAMFILES%`	System-wide install
`both`	Yes	User choice	Flexible deployment

json

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

模式	需要管理员权限	安装路径	适用场景
`perUser`	否	`%LOCALAPPDATA%`	默认选项，无需权限提升
`perMachine`	是	`%PROGRAMFILES%`	系统级全局安装
`both`	是	用户可选	灵活部署场景

json

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

Installer Hooks

安装程序钩子

Extend installation with custom NSIS scripts:

1. Create hooks file (

src-tauri/windows/hooks.nsh

nsis

!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. Reference in configuration:

json

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

通过自定义NSIS脚本扩展安装流程：

1. 创建钩子文件（

src-tauri/windows/hooks.nsh

）：

nsis

!macro NSIS_HOOK_PREINSTALL
  ; 文件安装前执行
  DetailPrint "Preparing installation..."
!macroend

!macro NSIS_HOOK_POSTINSTALL
  ; 安装完成后执行
  DetailPrint "Configuring application..."
  ; 示例：安装VC++运行库
  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
  ; 卸载前执行
  DetailPrint "Cleaning up..."
!macroend

!macro NSIS_HOOK_POSTUNINSTALL
  ; 卸载完成后执行
  DetailPrint "Removal complete"
!macroend

2. 在配置中引用：

json

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

Internationalization (NSIS)

国际化配置（NSIS）

NSIS installers support multiple languages in a single file:

json

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

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

json

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

Minimum WebView2 Version

最低WebView2版本要求

Require a specific WebView2 version:

json

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

指定所需的WebView2最低版本：

json

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

Complete Configuration Example

完整配置示例

json

{
  "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"
      }
    }
  }
}

json

{
  "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"
      }
    }
  }
}

Special Configurations

特殊配置

Windows 7 Support

Windows 7支持

json

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

Enable Windows 7 notification support in

Cargo.toml

toml

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

json

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

在

Cargo.toml

中启用Windows 7通知支持：

toml

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

FIPS Compliance

FIPS合规配置

Set environment variable before building:

PowerShell:

powershell

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

Command Prompt:

cmd

set TAURI_BUNDLER_WIX_FIPS_COMPLIANT=true
npm run tauri build

构建前设置环境变量：

PowerShell：

powershell

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

命令提示符：

cmd

set TAURI_BUNDLER_WIX_FIPS_COMPLIANT=true
npm run tauri build

Microsoft Store Distribution

Microsoft Store分发

Requirements

前提条件

Microsoft account with developer enrollment
Offline installer WebView2 mode (required by Store policy)
Publisher name different from product name

已注册开发者的Microsoft账号
使用WebView2离线安装模式（商店政策要求）
发布者名称与产品名称不同

Store-Specific Configuration

商店专属配置

Create

tauri.microsoftstore.conf.json

json

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

创建

tauri.microsoftstore.conf.json

文件：

json

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

Generate Store Icons

生成商店图标

bash

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

This generates all required icon sizes including Microsoft Store assets.

bash

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

该命令会生成所有所需尺寸的图标，包括Microsoft Store要求的资源文件。

Build for Store

为商店构建应用

bash

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

bash

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

Submission Process

提交流程

Build with offline installer configuration
Sign installer with valid code signing certificate
Create app listing in Partner Center (Apps and Games)
Reserve unique app name
Upload installer to distribution service
Link installer URL in Store listing
Submit for certification

使用离线安装模式配置构建应用
使用有效的代码签名证书为安装程序签名
在合作伙伴中心创建应用列表（应用和游戏板块）
预留唯一的应用名称
将安装程序上传至分发服务
在商店列表中关联安装程序URL
提交审核

Publisher Name Constraint

发布者名称限制

Your publisher name cannot match your product name. If your bundle identifier is

com.myapp.myapp

, explicitly set a different publisher:

json

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

发布者名称不能与产品名称相同。若你的包标识符为

com.myapp.myapp

，需显式设置不同的发布者名称：

json

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

Code Signing

代码签名

Using Certificate Thumbprint

使用证书指纹

json

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

json

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

Environment Variables

环境变量配置

bash

undefined

bash

undefined

Certificate path

证书路径

export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="your-password"

Or via tauri.conf.json

或通过tauri.conf.json配置

undefined

undefined

Timestamp Servers

时间戳服务器

Common timestamp servers:

DigiCert:
```
http://timestamp.digicert.com
```
Sectigo:
```
http://timestamp.sectigo.com
```

GlobalSign:

http://timestamp.globalsign.com/tsa/r6advanced1

常用时间戳服务器：

DigiCert:
```
http://timestamp.digicert.com
```
Sectigo:
```
http://timestamp.sectigo.com
```

GlobalSign:

http://timestamp.globalsign.com/tsa/r6advanced1

Troubleshooting

故障排查

MSI Build Fails on Non-Windows

非Windows系统上MSI构建失败

MSI files can only be built on Windows using WiX Toolset. Use NSIS for cross-platform builds.

MSI文件仅能在Windows系统上通过WiX Toolset构建。跨平台构建请使用NSIS格式。

WebView2 Not Installing

WebView2未安装

Check webview install mode configuration
Verify internet connectivity for bootstrapper modes
For offline mode, ensure installer size is acceptable

检查WebView2安装模式配置
验证引导程序模式下的网络连接
离线模式下确认安装程序体积符合预期

NSIS Cross-Compilation Errors

NSIS交叉编译错误

Verify NSIS is installed and in PATH
Check LLVM/clang installation
Ensure Windows Rust target is installed
Verify cargo-xwin is installed

验证NSIS已安装并添加至PATH
检查LLVM/clang安装状态
确认已安装Windows Rust目标
验证cargo-xwin已安装

Certificate Not Found

证书未找到

Verify certificate is installed in Windows certificate store
Check thumbprint matches exactly (no spaces)
Ensure certificate has private key access

验证证书已安装至Windows证书存储
检查指纹完全匹配（无空格）
确保证书具有私钥访问权限