Skip to content
LaTale edited this page Jan 26, 2026 · 6 revisions

发布流程指南 (Release Guide)

本项目使用 Changesets 配合 GitHub Actions 进行全自动化的版本管理和发布。

1. 常规发布流程

第一步:创建变更集 (Changeset)

在开发功能或修复 Bug 后,准备提交代码前,请运行以下命令来记录变更:

pnpm changeset

CLI 会引导你完成以下步骤:

  1. 选择需要更新的包(通常只有一个)。
  2. 选择版本更新类型:
    • Patch: 修复 Bug,非破坏性更改。
    • Minor: 新功能,向下兼容。
    • Major: 破坏性更改。
  3. 输入变更描述(这将出现在 Changelog 中)。

完成后,会生成一个 .changeset/xxxx-xxxx.md 文件。请将此文件确认为 Git 提交的一部分并推送到 master 分支。

第二步:生成版本 PR

当带有 changeset 的代码合并到 master 后,GitHub Action(changeset-version.yml)会自动运行。它会:

  1. 消费掉 .changeset 目录下的文件。
  2. 更新 package.json 版本号。
  3. 更新 CHANGELOG.md。
  4. 自动创建一个名为 “Version Packages” 的 Pull Request。

触发条件(重要)

仅当 master 分支的提交包含 .changeset/*.md 变更时,才会触发 PR 的创建或更新。
普通提交不会触发该 PR;如需手动执行,可通过 workflow_dispatch 触发。
如需“只触发 PR 创建/更新但不变更版本”,可以执行 pnpm changeset --empty 生成空 changeset 文件并提交,以触发流程。

自动更新机制 (Continuous Updates)

如果在该发布 PR 尚未合并时,master 分支又合入了新的 Changeset:

  1. Action 会再次被触发。
  2. 它会更新同一个 PR,而不是创建新的。
  3. 实现逻辑:
    • Action 会检查是否存在来自 changeset-release/master 分支的活跃 PR。
    • 如果存在,它会基于最新的 master 重新运行 changeset version。
    • 然后通过 Force Push 更新该分支。
    • 结果是:PR 始终反映“如果现在发布,将会发布的所有内容的最新状态”。

合并后发现问题时的处理

如果 feature 已合并到 main 后发现问题,需要继续修复,推荐步骤:

  1. 从主分支创建新分支:git checkout -b hotfix/fix-bug-xyz main。
  2. 在新分支上进行修复代码。
  3. 添加新 changeset:运行 npx changeset,选择受影响的包、bump 类型(通常 patch for bug fix),并描述变更(例如:“patch: 修复合并 PR #123 中的边界条件 bug”)。这会生成一个新的 .changeset/xxx.md 文件。
  4. 提交并推送:git add . && git commit -m "fix: resolve bug in feature XYZ" && git push origin hotfix/fix-bug-xyz。
  5. 创建新 PR,目标分支为 main,审查通过后合并。
  6. 合并后,Action 会检测新 changeset,自动创建或更新 Release PR(如果已有开放的 Release PR,它会聚合新变更)。
  7. 审查并合并 Release PR 后,如已配置 publish,将自动发布新版本。

第三步:确认并发布

  1. Review 那个自动生成的 “Version Packages” PR。
  2. 确认无误后,Merge 该 PR 到 master。
  3. Merge 动作会触发发布流水线(changeset-publish.yml):
    • 自动构建并测试。
    • 发布到 VS Code Marketplace。
    • 发布到 Open VSX Registry。
    • 自动创建 GitHub Release 并上传 .vsix 文件。

2. 发布失败后的手动重试 (Manual Retry)

场景:如果自动发布流程失败(例如 Token 过期、网络问题),而你已经修复了问题并合并到了 master,但不需要再次升版本号时,使用此方法强制重发。

操作步骤

  1. 修复问题:确保导致发布失败的问题已在 master 分支修复。
  2. 进入 Actions:打开 GitHub 仓库的 Actions tab 页。
  3. 选择 Workflow:在左侧边栏找到 “Publish to VSCode Marketplace”(对应 release.yml)。
  4. 手动触发:
    • 点击右侧的 Run workflow 下拉按钮。
    • Use workflow from:保持选择 master。
    • Version to publish:留空(默认会自动读取 package.json 中的当前版本)。
    • 点击绿色按钮 Run workflow。

此操作将忽略“版本是否变化”的检查,强制使用当前代码和当前版本号重新执行构建和发布。


3. 必需的配置 (Secrets)

自动化发布依赖于 GitHub Repository Secrets。请确保在 Settings -> Secrets and variables -> Actions 中配置了以下变量:

Secret Name 用途 获取方式
VSCE_TOKEN VS Code Marketplace 发布权限 Azure DevOps Personal Access Token(Scope: Marketplace -> Manage)
OVSX_TOKEN Open VSX Registry 发布权限 Open VSX Settings