---
title: Windows 自助打包说明
doc_type: operations-runbook
domain: runtime
keywords:
  - Windows 打包
  - 测试安装包
  - 自助构建
  - PowerShell
summary: 给 Windows 测试者或协作者一套可直接执行的本地打包流程，用于产出体验版安装包并回传给维护者。
when_to_read:
  - 你要让朋友在自己的 Windows 机器上打包体验版
  - 你暂时不打算保留远程 Windows 自动发版链路
  - 你需要产出 Windows 安装包并回传给维护者人工分发
read_next:
  - ./app-update-delivery.md
  - ../constraints/README.md
---
# Windows 自助打包说明

这篇文档只解决一件事：让 Windows 测试者或协作者在自己的机器上，把当前仓库打成可安装的体验版。

适用场景：

- 你不保留 GitHub Windows 自动发版链路
- 你想先给朋友发 Windows 体验版
- 你愿意让协作者自己在 Windows 机器上本地打包

读完之后，下一步回到 [应用更新交付说明](./app-update-delivery.md) 看统一发布和更新口径。

## 这条路线的边界

- 这套流程产出的是 Windows 本地体验版安装包。
- 默认关闭 updater 产物签名，不要求把正式 updater 私钥发给测试者。
- 这意味着测试者可以本地安装体验，但不能直接代表维护者产出远程自动发布版本。
- 如果你要把 Windows 产物发给其他人，请让测试者把构建结果回传给维护者人工分发。

一句话：

`这套流程解决“让朋友自己打出 Windows 体验版”，不解决“把签名私钥分发给朋友”。`

## 机器要求

脚本默认会尽量自动补齐这些环境：

| 组件 | 建议版本 | 用途 |
| --- | --- | --- |
| Node.js | 22.x | 前端与 Tauri CLI |
| Rust | stable | 构建桌面主程序 |
| Visual Studio Build Tools | 最新可用版 | Windows C++ 工具链 |
| WebView2 Runtime | 最新可用版 | 运行 Windows 桌面端 |
| Git | 最新可用版 | 拉代码 |

注意：

- 首次执行脚本时，可能会触发 `winget`、官方安装器和 UAC 弹窗。
- 其中 `Visual Studio Build Tools` 安装时间最长，常见情况在 10 到 30 分钟之间。
- 如果脚本自动安装后仍然缺依赖，不要手改脚本，直接把完整终端输出发给维护者。

## 一键脚本

仓库已经提供 PowerShell 脚本：

- [build_windows_tester_bundle.ps1](/Users/winkd/my-projects/ai-stock-assistant-project/ai-stock-assistant-desktop-tauri/scripts/build_windows_tester_bundle.ps1)

脚本做的事：

1. 自检 Windows 构建环境
2. 尽量自动安装 Node、Git、Rust、WebView2 和 VS Build Tools
3. 导入 MSVC 构建环境
4. 安装 Node 依赖
5. 构建 renderer 和 sidecar
6. 用 Windows 测试配置打包 Tauri 安装包
7. 收集 `msi` / `nsis` 产物
8. 额外打一个 zip，方便回传给维护者

## 执行步骤

### 1. 拉代码

```powershell
git clone https://github.com/dengwenke/ai-stock-assistant-desktop-tauri.git
cd ai-stock-assistant-desktop-tauri
```

### 2. 执行脚本

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build_windows_tester_bundle.ps1
```

如果你使用的是 PowerShell 7，也可以：

```powershell
pwsh -File .\scripts\build_windows_tester_bundle.ps1
```

如果你已经手动装好了依赖，不想让脚本再自动补环境，可以加：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build_windows_tester_bundle.ps1 -SkipAutoInstall
```

如果你只想重新打包，不想重复安装依赖和前端资源，也可以按需跳过：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build_windows_tester_bundle.ps1 `
  -SkipAutoInstall `
  -SkipNpmCi `
  -SkipBundlePrereqs
```

## 产物位置

脚本完成后会输出两类结果：

- 目录：`.build\windows-tester-release\v<version>\`
- 压缩包：`.build\windows-tester-release\AI-Stock-Assistant-Desktop-windows-tester-v<version>.zip`

目录里通常会包含：

- `msi\` 安装包目录
- `nsis\` 安装包目录
- `README.txt`

## 怎么交付给维护者

如果测试者只是自己本地体验，直接使用目录里的 `msi` 或 `exe` 安装包即可。

如果测试者要把 Windows 构建结果回传给维护者人工分发，最简单的方式是：

1. 发送 `.build\windows-tester-release\AI-Stock-Assistant-Desktop-windows-tester-v<version>.zip`
2. 维护者解压后检查 `msi` 或 `exe`
3. 维护者再按当前版本分发口径把安装包发给目标用户

## 为什么默认不生成正式 updater 产物

当前测试配置文件是：

- [tauri.test.conf.json](/Users/winkd/my-projects/ai-stock-assistant-project/ai-stock-assistant-desktop-tauri/src-tauri/tauri.test.conf.json)

它会覆盖：

- `bundle.createUpdaterArtifacts = false`
- `plugins.updater.active = false`

这样做的原因只有一个：

- 测试安装包不再依赖 updater 私钥，也不会因为测试环境里的 updater 配置导致应用启动失败

如果后续你重新启用受控的 Windows 远程构建环境，再单独恢复对应发版链路即可。

## 常见失败点

### 缺少 `cargo` 或 `rustup`

脚本会先尝试自动安装 Rust stable；如果仍失败，再把终端输出发给维护者。

### 缺少 MSVC 工具链

脚本会先尝试通过 `winget` 自动安装 Visual Studio Build Tools；如果安装器中途被取消或失败，需要重新运行脚本。

### `npx tauri build` 找不到 WebView2 相关依赖

脚本会先尝试自动安装 WebView2 Runtime；如果仍报错，再把终端输出发给维护者。

### 打包成功但没有找到 `msi` 或 `exe`

先检查：

- `src-tauri\target\release\bundle\msi`
- `src-tauri\target\release\bundle\nsis`

如果这两个目录都没有内容，说明 Tauri bundler 阶段没真正完成，需要保留终端日志发给维护者排查。
