---
title: 混合发布包归集说明
doc_type: operations-runbook
domain: runtime
keywords:
  - 一键打包
  - 产物归集
  - macOS 安装包
  - Windows 自助构建包
summary: 基于当前仓库现状，用一个入口统一归集 macOS 安装包和 Windows 自助构建包。
when_to_read:
  - 你要把本次版本的桌面交付物一次性归到同一目录
  - 你当前只能本机构建 macOS，但仍要同时交付 Windows 自助构建能力
read_next:
  - ./app-update-delivery.md
  - ./windows-self-build-for-testers.md
---
# 混合发布包归集说明

这篇文档只解决当前阶段的一件事：在你只能本机构建 macOS 安装包、Windows 仍依赖用户自助构建的前提下，怎样用一个入口把本次版本的交付物统一归到一处。

适用边界：

- macOS 当前可以直接产出 `dmg` 等正式安装包
- Windows 当前不在你的本机构建能力内，只能提供源码级自助构建包
- 目标是统一“交付目录”和“交付清单”，不是伪装成已经具备多平台统一二进制发版

读完后，如果你要确认当前正式交付边界，再回到 [应用更新交付说明](./app-update-delivery.md)；如果你要让 Windows 用户自己打体验版，再看 [Windows 自助打包说明](./windows-self-build-for-testers.md)。

## 当前推荐口径

当前仓库最稳妥的交付方式不是“多平台都由你本机一键打出安装包”，而是：

- macOS：直接交付当前机器能打出的真实安装包
- Windows：交付同版本的自助构建包，让 Windows 用户自己执行仓库内的 PowerShell 打包脚本

一句话：

`统一的是发布目录和清单，不是强行统一成两边都已有现成安装包。`

## 命令入口

仓库新增了独立脚本：

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

默认用法：

```bash
node scripts/assemble_release_bundle.mjs --mode build
```

常用模式：

```bash
# 正常本机构建后再归集
node scripts/assemble_release_bundle.mjs --mode build

# 测试配置打包后再归集
node scripts/assemble_release_bundle.mjs --mode test

# 本地 macOS 正式包构建后再归集
node scripts/assemble_release_bundle.mjs --mode local-release

# 已经手动跑过构建，只做归集
node scripts/assemble_release_bundle.mjs --mode local-release --skip-build
```

## 目录结构

脚本默认输出到：

- `.build/release-bundles/v<version>/`

目录结构示例：

```text
.build/release-bundles/v1.0.9/
  README.txt
  manifest.json
  macos/
    AI Stock Assistant Desktop_1.0.9_x64.dmg
    AI Stock Assistant Desktop.app.tar.gz
    AI Stock Assistant Desktop.app.tar.gz.sig
  windows-self-build/
    AI-Stock-Assistant-Desktop-windows-self-build-v1.0.9.zip
    README.txt
```

目录语义：

- `macos/`：当前宿主机真实构建出的 macOS 可交付产物
- `windows-self-build/`：给 Windows 用户的源码级自助构建包，不是假装已经打好的安装包
- `manifest.json`：本次交付产物清单，包含平台、交付类型、大小和 `sha256`

## 产物口径

`manifest.json` 里当前只区分 2 种 `delivery_type`：

- `installer`：当前机器直接产出的安装包或签名产物
- `self-build-kit`：交给 Windows 用户在本机继续构建的源码归档

当前这套口径刻意把两类东西分开，避免下面这类误导：

- 把 Windows 自助构建包叫成“Windows 安装包”
- 把不能直接安装的源码归档混进本机直接可交付的安装包
- 让后续发布脚本误把自助构建包当成安装器上传

## Windows 自助构建包里有什么

脚本会把当前工作树里的必要仓库文件打成 zip，并额外放入一份简短说明：

- 仓库源码快照
- `package.json` 和锁文件
- `src/`、`src-tauri/`、`scripts/`、`docs/` 等打包所需文件
- `scripts/build_windows_tester_bundle.ps1`
- `WINDOWS-SELF-BUILD-README.txt`

Windows 用户拿到 zip 后，在解压目录里执行：

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

正式说明仍以 [Windows 自助打包说明](./windows-self-build-for-testers.md) 为准。

## 什么时候不要用这条路线

下面两种情况，不建议继续只靠混合发布包：

1. 你已经有稳定的 GitHub Windows runner 或受控 Windows 构建机
2. 你要重新恢复真正的远程多平台自动发版闭环

一旦进入这两个场景，应该升级成真正的多平台二进制发版，把 `windows-self-build/` 替换成真实 `windows/` 安装器目录，而不是继续长期维持源码自助构建交付。
