ugp

ugp CLI 使用说明

顶层命令总览（ugp -h）

在仓库根目录执行：

// 本地安装并执行
cargo install --path . && ugp publish --stable --only-publish
cargo run -p ugp -- -h

典型输出如下（与实际版本号略有差异属于正常）：

ugp 0.9.8
仅适用用内部环境使用！应用快速发布工具，支持配置初始化（init）， 版本号更新（next）和一键发布（publish）流程

Usage: ugp [OPTIONS] <COMMAND>

Commands:
  publish  发布
  next     下一个版本
  init     初始化
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose  启用详细日志模式
  -h, --help     Print help
  -V, --version  Print version

含义说明：

• publish：发布相关流程（构建安装包 + 生成发布文件 + 版本历史维护）
• next：计算下一个版本号（major/minor/patch/next/custom）
• init：初始化 .ugp 目录及配置文件
• help：查看整个 CLI 或某个子命令的使用说明（例如 ugp publish --help）
• -v/--verbose：打开详细日志输出，方便排查发布问题

ugp 是配套的发布辅助 CLI，用于：

• 读取 src-tauri/tauri.conf.json 中的应用信息（名称、版本）
• 根据 .ugp/config.toml 的配置生成升级包发布文件
• 生成/维护 .ugp/version 下的版本信息（历史版本）

推荐在仓库根目录运行以下命令。

1. 初始化配置 ugp init

cargo run -p ugp -- init

• 引导创建 .ugp/config.toml
• 建议把 .ugp 目录加入版本控制，方便团队共享配置

2. 计算下一个版本号 ugp next

cargo run -p ugp -- next

行为：

• 从 src-tauri/tauri.conf.json 读取当前版本（例如 2.3.24）
• 提供以下选项：
  • major：2.3.24 -> 3.0.0
  • minor：2.3.24 -> 2.4.0
  • patch：2.3.24 -> 2.3.25
  • next：等同 patch
  • custom：手动输入任意版本号
• 当前实现只计算并展示新版本号，不会写回配置文件
  如需自动改 tauri.conf.json / Cargo.toml，需要后续扩展逻辑

3. 发布版本 ugp publish

cargo run -p ugp -- publish        # 交互选择 beta/stable/rollback
cargo run -p ugp -- publish --beta # 直接发布测试版
cargo run -p ugp -- publish --stable
cargo run -p ugp -- publish --rollback
cargo run -p ugp -- publish --beta --only-publish   # 只发布，不重新打包

流程（简化）：

1. 读取 .ugp/config.toml，拿到：
   • 安装包路径：install_package_path
   • 发布路径：release_package_path
   • 发布 URL：release_url
2. 从 src-tauri/tauri.conf.json 中读取应用名称、版本号
3. 从 install_package_path 下拷贝：
   • MSI 安装包：{productName}_{version}_{arch}_zh-CN.msi
   • 签名文件：同名 .msi.sig
4. 生成 releases.json / releases_beta.json：
   • notes 字段来自 README.md 渲染后的 HTML
   • force_update 按发布类型设置
5. 落盘到 ./.ugp/version 并按配置复制到网络共享目录
6. 若为 stable，额外生成当前版本号对应的历史文件：
   • ./.ugp/version/{version}.json

3.1 发布子命令参数

• --beta
  • 直接发布测试版（不弹选择菜单）
• --stable
  • 直接发布生产版（目前主要做确认提示，后续可扩展为生产环境发布流程）
• --rollback
  • 从历史版本中选择一个版本进行“信息回退”（仅回退 releases.json 相关信息，不动安装包）
• --only-publish
  • 与 --beta / --stable 搭配使用
  • 默认 ugp publish 会先执行一次打包命令（详见下文构建命令），加上 --only-publish 后只做发布动作，不重新构建安装包

3.2 构建命令（UGP_BUILD_CMD）

ugp publish 在发布前需要有可用的安装包。构建安装包时的命令顺序为：

1. 如果设置了环境变量 UGP_BUILD_CMD，优先执行，例如：

   # Windows PowerShell 示例
   $env:UGP_BUILD_CMD = "pnpm tauri build"
   cargo run -p ugp -- publish --beta
   
   # 或使用 npm
   $env:UGP_BUILD_CMD = "npm run tauri -- build"
   cargo run -p ugp -- publish --beta
   
   # 或使用 cargo-tauri
   $env:UGP_BUILD_CMD = "cargo tauri build"
   cargo run -p ugp -- publish --beta
   

   • 内部通过系统 shell 执行：
     • Windows：cmd /C <UGP_BUILD_CMD>
     • macOS/Linux：sh -lc '<UGP_BUILD_CMD>'
   • 所以你在终端能直接跑通的命令，配置到 UGP_BUILD_CMD 一般都能正常执行。

2. 如果未设置 UGP_BUILD_CMD，会按顺序自动尝试：

   pnpm tauri build
   npm run tauri -- build
   cargo tauri build
   

   找到第一个执行成功的命令即视为构建成功。

4. 查看版本历史 get_version_history

内部工具函数 generate::get_version_history() 会：

• 读取 ./.ugp/version 目录下所有 .json 文件
• 排除聚合文件：releases.json、releases_beta.json
• 使用 semver 解析并按版本大小排序（2.10.0 > 2.9.0）
• 返回 Vec<String>，例如：["1.3.0", "1.9.0", "2.0.0", "2.3.24"]

注意事项

• 运行路径

  • 默认假设当前工作目录为仓库根目录
  • tauri.conf.json 路径：./src-tauri/tauri.conf.json
  • 发布配置路径：./.ugp/config.toml

• 文件命名约定

  • 安装包：{productName}_{version}_{arch}_zh-CN.msi
  • 签名文件：同名 .msi.sig
  • 历史版本：.ugp/version/{version}.json

• 版本号格式

  • 必须符合 x.y.z 语义化版本规范（如 2.3.24）
  • ugp next 和版本历史排序都依赖此格式

• 发布前准备

  • 确保 Tauri 应用已经打包完成，目标 MSI 及 .sig 存在
  • 确认 .ugp/config.toml 中的网络路径有写权限
  • 推荐在 CI 或专用发布机上运行 ugp，避免路径不一致

• 构建环境

  • Windows：
    • 建议使用 PowerShell 或 CMD，确保 pnpm / npm / cargo 命令在当前 shell 下可用
    • 构建时会统一通过 cmd /C 执行命令，行为与手动在终端里输入一致
  • macOS / Linux：
    • 需要在 sh 的环境下能找到相应命令（PATH 配置正确）
  • 如遇到 “命令执行失败” 或 “未找到可用的构建命令” 错误，优先在终端单独跑一遍对应命令确认，并考虑显式设置 UGP_BUILD_CMD。

如需进一步扩展（例如自动写回版本、发布后自动推送 Git tag 等），可以在现有命令基础上新增子命令或扩展 publish/next 的行为。