统一打包入口

本机打包不会安装 Vex、提交 / 推送代码、创建 tag 或发布 Release。成功看到本轮 READY 后，再自行运行安装包。

一键让 GitHub 构建所有安装包

Windows 双击根目录 publish-release.bat；任意平台也可在根目录执行 python scripts/packaging/publish.py（Linux / macOS 用 python3）。这是远程发布入口，与下面的本机 build.* 分开：不需要本机安装全部原生工具链，也不需要 GitHub CLI 或个人 API token。

发布前先在 apps/vex/pubspec.yaml 更新版本及递增构建号，准备 .github/release-notes/v版本.md，测试后提交并将 main 推送到 GitHub。要求 Git、Python 3.11+、可用的 GitHub SSH 权限、干净工作区、本地与远程 main 一致、新版本标签尚不存在。脚本不会替你提交文件或忽略未提交内容。

输入显示的版本标签确认后，脚本创建附注标签并通过 SSH 推送，只打开 Actions 页面；推送成功不代表安装包已完成。工作流在各自系统上制作 Windows x64、macOS 通用、Linux x64 / ARM64、Android 三架构安装包。测试、安装检查、全部七个安装包及校验文件通过后才公开到 Releases，并进入 releases/latest 默认下载与应用更新检查。iOS / HarmonyOS 可安装包继续暂缓。

python scripts/packaging/publish.py --check-only 仅预检，不创建或推送标签。已有标签请从 Actions 重试对应运行，不删除 / 移动 / 强推标签；网络错误后先核对远程是否已经收到标签，再决定后续操作。build-windows.bat 和各平台 build.* 仍然只在本机构建，不发布。

按平台找脚本

scripts/packaging/
├── build.py               # 统一命令入口、宿主检查、依赖 / 测试 / 构建 / 校验
├── win-x64/
│   ├── build.bat          # Windows 双击入口，保留结果并打开产物目录
│   ├── build.ps1          # Windows 完整流程
│   ├── package.ps1        # 将已有 Flutter Release 制作为 EXE
│   └── install_inno.ps1   # 准备固定版本且经校验的 Inno 编译器
├── linux-x64/build.sh     # Linux x64 完整流程
├── linux-arm64/build.sh   # Linux ARM64 完整流程
├── linux/package.sh      # 两种 Linux 架构共享的 DEB 制作逻辑
├── osx-x64/build.sh       # Intel 入口，仍生成双架构通用 DMG
├── osx-arm64/build.sh     # Apple 芯片入口，同上
├── osx-universal/build.sh # 推荐的 macOS 通用入口
├── osx/                  # DMG 制作、布局检查与哈希锁定依赖
├── android/
│   ├── build.bat          # Windows Android 打包入口
│   ├── build.sh           # Linux / macOS Android 打包入口
│   ├── configure_signing.py # 从已配置的环境变量准备签名；不生成新密钥
│   └── collect.py         # 校验发行签名、包名、版本和 ABI 后收集 APK
├── ios/check.sh          # 仅无签名编译检查，不产出可安装 IPA
└── shared/release_tools.py # 版本元信息、产物命名、SHA-256、发布白名单

build.* 是从源码到安装包的完整入口；package.* / collect.py 是已有编译产物的底层打包步骤。日常只用完整入口，避免漏掉校验。根目录 build-windows.bat 是 Windows 双击快捷入口。

命令与宿主

在仓库根目录执行，下表每一行都是独立命令。macOS / Linux 使用 python3；Windows 使用 python。

也可执行相应目录的 build.bat / bash .../build.sh，它们不依赖终端当前所在目录。构建命令只接受表中目标名称，不提供额外别名；安装包文件名中的 windows-x64、macos-universal 是产物标识，不是构建命令参数。macOS 两个架构入口不是两个不同安装包；均检查主程序和两个 framework 的双架构。

共同需要 Python 3.11+ 和 .flutter-version 指定的 Flutter SDK；脚本不会升级 SDK。将 Flutter bin 加入 PATH，或使用 --flutter、VEX_FLUTTER、FLUTTER_ROOT 指定。Windows BAT 的参数使用 PowerShell 风格，例如 -CheckOnly；统一 Python 入口使用 --check-only。

Linux 原生依赖（Ubuntu 24.04，需用户自行确认安装）：

sudo apt-get update
sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev libsecret-1-dev liblzma-dev libxrandr-dev libayatana-appindicator3-dev dpkg-dev desktop-file-utils

macOS 需要完整 Xcode、已接受的许可、CocoaPods 及对应平台 SDK。DMG 的 Python 依赖自动装入 artifacts/tools/macos-dmg 的独立虚拟环境，并按版本和 SHA-256 校验，不改系统 Python 包。当前采用临时签名，尚无 Developer ID / 公证。

Android 使用 JDK 21，先安装并接受 SDK 许可：platforms;android-36、build-tools;36.0.0、ndk;28.2.13676358，设置 ANDROID_HOME，也可传 --sdk-root。恢复原发行 keystore 和 apps/vex/android/key.properties，设置公开指纹 ANDROID_CERT_SHA256；不要更换发行密钥，不要提交密码 / 密钥。若使用 CI 同名的四项签名环境变量，可先运行 python scripts/packaging/android/configure_signing.py 准备忽略文件；请勿把值写入命令行或文档。签名配置不会随普通克隆下载。

iOS 和 HarmonyOS 的可安装包发布继续暂缓，不提供伪造或不可安装的占位包。

常用选项

# 不下载或编译，只核对本机先决条件
python scripts/packaging/build.py win-x64 --check-only

# 任意系统预览其他平台的配方，不执行命令、不创建目录
python scripts/packaging/build.py linux-arm64 --dry-run

# 指定已有 Flutter，并在构建后不打开资源管理器
python scripts/packaging/build.py win-x64 --flutter C:\tools\flutter\bin\flutter.bat --no-open-folder

默认流程：从 docs 生成内置文档 → 锁定依赖 → 分析与四组 Dart / Flutter 测试 → Python 脚本测试 → 正式 lib/main.dart Release → 原生安装包 → SHA-256 → 产物格式和白名单校验。

• --skip-tests 仅显式跳过分析 / 测试，仍生成内置文档并保留锁文件、编译与产物检查。CI 已先执行完整测试，再传此参数。
• --output artifacts/release 将产物写入 CI 汇总目录；相对路径始终以仓库根目录为基准。日常不必指定。
• Windows 可用 --compiler 指定现有 ISCC.exe；默认准备固定版本工具。
• BAT 自动化设置 VEX_NO_PAUSE=1 可取消结束等待；退出码仍保留。

Windows 默认限制 CMake 并发为 2、MSVC 为 /MP1，可通过已有进程环境变量覆盖。内存较小或本机编译器不稳定时，可在 PowerShell 中先设置 $env:CMAKE_BUILD_PARALLEL_LEVEL = '1'、$env:CL = '/MP1'，再运行入口；编译器崩溃仍会报错中止，不会自动跳过失败或拿旧包当成功结果。

示例：artifacts/local/win-x64/v0.2.2-build4/。macOS 架构别名归并到 osx-universal，Android 的三种 APK 归入 android。重复构建覆盖同名产物，不自动清空目录；失败可能留有旧文件，不能仅凭目录存在判断成功。不要在一个工作副本同时运行多个 Flutter 构建或测试。

完整签名、发布、安装升级及用户数据说明见 安装包与自动发布。