企业官网建设流程全解析

Tiptap 发布流程：如何新增 release 分支并同步 npm dist-tag 配置？

【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap

当你需要为 Tiptap 开启一条新的发布线（例如维护一个大版本分支）时，光建好 git 分支是不够的：仓库的自动发布 CI 只会对「在触发列表里、且在发布配置里登记过」的分支执行构建和发布。这篇文章的任务是把一个新分支接入 Tiptap 的发布流程，并确保它使用的 npm dist-tag、Slack 公告标签和 Changesets 版本 PR 信息都随配置同步生效。前提是仓库已经使用 changesets、npm trusted publishing（provenance）和 GitHub Actions 作为发布基础设施，这些在本仓库中已经就绪。

先搞清楚：两处配置必须保持同步

按 CONTRIBUTING.md 中 “Adding a new release branch” 一节，新增一条 release line 需要同时更新两个位置：

1. 工作流触发列表— 在 .github/workflows/publish.yml 的on.push.branches中加入新分支名；
2. 发布配置— 在 .github/publish-config.json 中加入一条对应的branches条目，写明 dist-tag 和发布相关文案。

两处列表必须保持同步：分支只出现在其中一边时，要么工作流永远不会被触发（只加了配置、没加触发列表），要么触发后是一个无害的空操作（只加了触发列表、没加配置）。

当前仓库的两个文件是这么配的。publish.yml 的触发条件：

on: push: branches: - main - v2

publish-config.json 的完整内容：

{ "branches": { "main": { "distTag": "latest", "label": "stable", "title": "Release new stable release", "commit": "chore(release): release new stable release" }, "v2": { "distTag": "v2-latest", "label": "v2", "title": "Release new v2 stable release", "commit": "chore(release): release new v2 stable release" } } }

注意两边是一一对应的：main和v2在两个文件里都存在。你的新分支也要做到这一点。

第一步：把分支名加入 publish.yml 的触发列表

编辑 .github/workflows/publish.yml，在on.push.branches列表末尾追加新分支名。假设你要新增的分支叫v3（实际替换成你要建的分支名）：

on: push: branches: - main - v2 - v3

这一步只负责让 push 事件触发 Publish 工作流，本身不携带任何发布参数。

第二步：在 publish-config.json 中添加 dist-tag 配置条目

在 .github/publish-config.json 的branches对象里，以分支名为 key 增加一个条目。每个条目固定四个字段，含义见下表（来自 CONTRIBUTING.md）：

以下是一个示例条目，v3、next、prerelease是示例值，title与commit由你按该发布线的惯例自行拟定（文档只要求它们是版本 PR 的标题与 commit message）：

"v3": { "distTag": "newline-dist-tag", "label": "v3", "title": "Release new v3 stable release", "commit": "chore(release): release new v3 stable release" }

字段校验是严格的：四个字段缺一不可，且都必须是字符串，否则解析器会抛出Branch "..." is missing required string field "..." in publish-config.json错误。

推送前在本地验证配置

CI 的resolve-config任务在解析分支之前会先跑配置测试，你也可以在本地直接执行同一条命令：

node --test .github/scripts/__tests__/*.test.mjs

这条命令运行 resolve-publish-config.test.mjs，它对真实的publish-config.json做四类检查：

• 文件是合法 JSON 且包含branches对象；
• 至少配置了一个分支；
• 每个分支条目都带齐distTag、label、title、commit四个字符串字段；
• 每个已配置分支都能通过解析器（resolve-publish-config.mjs）成功解析。

另外可以单独用 CLI 解析某个分支，确认输出是否符合预期：

node .github/scripts/resolve-publish-config.mjs <branch-name>

其中<branch-name>替换为你新增的分支名。解析器按精确名称查找分支，不做部分匹配（测试里明确验证了main-foo不会命中main）。命中时按 key=value 形式输出各字段（camelCase 转 snake_case），以当前仓库的v2分支为例，输出为：

configured=true dist_tag=v2-latest label=v2 title=Release new v2 stable release commit=chore(release): release new v2 stable release

分支没有配置条目时，只输出一行configured=false。如果你的新分支解析出来的是configured=false，说明第二步的配置没写对或没保存，先修正再推送。

首次发布前：确认 npm 上的 dist-tag 存在

CONTRIBUTING.md 要求：在从新分支做第一次发布之前，确认对应的 dist-tag 已经存在于 npm 上，命令为：

npm dist-tag add <package>@<version> <tag>

其中<package>、<version>、<tag>分别替换为目标包名、已发布的版本号和你要使用的 dist-tag（即配置里的distTag值）。跳过这一步，新分支上的首次发布会失败。

推送后：CI 如何消费这份配置

把两个文件改好并推送后，push 到该分支会触发 Publish 工作流，各任务的执行逻辑如下（来自 publish.yml）：

1. resolve-config：先跑上面的配置测试，再执行node .github/scripts/resolve-publish-config.mjs "${{ github.ref_name }}"，按分支名精确解析出configured、dist_tag、label、title、commit五个输出。如果分支在配置里缺失，工作流干净退出——不构建、不发布、不发通知，这正是「只加了一边配置」时你会看到的现象。
2. build：仅在configured == 'true'时运行，安装依赖、执行vp run build && vp run build:demos、跑check:package-exports，并把packages/*/dist与packages-deprecated/*/dist打包成 artifact。
3. release：运行 changesets 发布流程，其中publish步骤实际执行vp exec changeset publish --tag <dist_tag>，版本 PR 的标题和 commit message 取配置里的title与commit；发布通过 npm provenance（trusted publishing）完成。
4. notify-slack / notify-slack-failure：发布成功后发送 Slack 通知，消息格式为[Tiptap Editor <label>]: Published packages from branch <分支名> with npm tag <dist-tag>；resolve-config 或 release 失败时发送失败通知，消息中带本次 run 的日志链接。

验证是否生效就按这条链检查：resolve-config 任务输出的dist_tag等字段是否为你在 publish-config.json 里写的值 → build 是否实际执行（而不是因configured=false被跳过）→ release 任务的 changesets 步骤是否以正确的--tag完成发布 → Slack 是否收到带分支名和 dist-tag 的公告。

边界与常见失效现象

• 分支名精确匹配：解析器只接受完整分支名，v2-feature这类名字不会命中v2条目；如果你的发布分支命名带后缀，配置里的 key 必须与之完全一致。
• 配置缺失 ≠ 报错：分支只加在on.push.branches而没进 publish-config.json 时，工作流会静默空跑（clean exit），不会构建也不会通知。看到 push 后「什么都没发生」时，先查 resolve-config 的输出是不是configured=false。
• 字段校验失败会直接 fail：缺字段、字段非字符串、branches不是对象、或 JSON 解析失败，resolve-config 任务会以对应错误信息失败，并通过 notify-slack-failure 发出通知。
• npm dist-tag 未预建：新分支首次发布失败时，对照文档确认是否执行过npm dist-tag add <package>@<version> <tag>。

完成上述两处配置、本地测试通过、npm dist-tag 就绪之后，向新分支推送一次即可走完整条发布链路；此后该分支上每次产生版本变更的推送，都会自动按同一份distTag/label/title/commit配置执行构建、发布和 Slack 公告。

【免费下载链接】tiptapThe headless rich text editor framework for web artisans.项目地址: https://gitcode.com/GitHub_Trending/ti/tiptap