企业官网建设流程全解析

• UI组件
• 前端

本篇技术指南以 NG-ZORRO（ng-zorro-antd）仓库的官方发布技能文档 .agents/skills/version-release/SKILL.md 为主体，结合scripts/release/release.ts等源码实现，系统讲解该仓库从「准备发版分支」到「发布 npm 包、部署官网、发布 GitHub Release」的完整流程。读者读完可掌握：如何用非交互式prepare模式准备本地发版文件、如何维护三份 changelog、如何为 API 与 Demo 打版本标签、如何走 Azure 发布与部署管线，以及整套流程中的安全红线与 Agent 操作清单。

适用范围与关键项目事实

本指南只针对NG-ZORRO/ng-zorro-antd仓库的真实发版流程，不是通用的 npm 发布清单。它覆盖以下环节：准备发版分支与发版 PR、使用 agent 友好的stage-release prepare模式准备本地发版文件、维护根目录 changelog 与两份文档 changelog、通过 Azure 发布管线发布 npm 包、通过 Azure 部署文档站点，以及 GitHub Release、博客与社交通告等发布后跟进。

在动手之前，必须先记住几个容易踩坑的「项目事实」：

• 根目录 package.json 的版本号是0.0.0-NOT-USED，不要把它当作真实发版版本。
• 库的真实版本号位于 components/package.json（当前为22.1.0）。
• Angular 版本号 token 位于 components/version/version.ts，其中VERSION = new Version('22.1.0')。
• 发版辅助脚本是npm run stage-release，实现在 scripts/release/release.ts（根 package.json 中定义为"stage-release": "tsx scripts/release/release.ts"）。
• 不带子命令运行npm run stage-release会进入原始的交互式人工流程（逐阶段选择 Fetch upstream → Bump version → Update changelog → Build release → Push library release → Push site release）。
• Agent 工作应使用非交互式 prepare 模式：npm run stage-release -- prepare --version <version> --base <branch>。
• prepare 模式只准备本地发版文件，不会构建、推送、发布或部署。
• 发版 PR 通常需要更新三份 changelog 文件：根目录 CHANGELOG.md、docs/changelog.en-US.md 与 docs/changelog.zh-CN.md。
• 构建、库发布与站点部署通常由 Azure 管线完成，官方 npm 发布默认不执行本地npm publish。

动手前的仓库状态检查

不要凭空猜测仓库状态，先执行如下检查命令：

git status --short git branch --show-current git remote -v node -v cat components/package.json git tag --list | grep -v -E '(experimental|alpha|resource)' | sort -V | tail -20

需要确认四件事：

1. 工作树是干净的（运行npm run stage-release之前必须如此）。
2. 存在一个指向NG-ZORRO/ng-zorro-antd的 remote，脚本会自动把它识别为 upstream。
3. 本地 Node 版本满足根 package.json 的engines要求（当前为^22.22.3 || ^24.15.0 || >=26.0.0）。
4. 目标版本必须大于当前 components/package.json 中的版本。

如果工作树里有用户未提交的改动，除非用户明确要求，否则不要覆盖或暂存这些改动。这一点在源码中也有体现：scripts/release/release.ts 的prepareRelease会调用hasWorkingTreeChanges()（内部执行git status --porcelain）检查工作树，若有未提交改动且非 dry-run 直接报错退出。

使用非交互式 Prepare 模式准备发版 PR

当用户要求「准备发版」「创建发版 PR」或「升级版本号」时，统一使用 prepare 模式：

npm run stage-release -- prepare --version <version> --base <branch>

示例：

npm run stage-release -- prepare --version 21.3.2 --base v21 npm run stage-release -- prepare --version 22.0.0 --base master

prepare 模式实际做了什么

结合 scripts/release/release.ts 的实现，prepare 模式会依次：

• 校验--version必填、格式合法（validVersion在 scripts/release/parse-version.ts 中用正则/^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.(\d+))?$/校验）；
• 校验工作树干净（git status --porcelain）；
• 通过getUpstreamRemoteName()自动探测指向NG-ZORRO/ng-zorro-antd的 remote 名；
• 执行git fetch --prune --tags <remote> <base>拉取目标基分支与标签；
• 用git merge-base --is-ancestor校验当前HEAD基于目标基分支；
• 校验目标版本大于当前版本（checkVersionNumber在 parse-version.ts 中按 major → minor → patch → prerelease 依次比较，prerelease 的优先级顺序为alpha < beta < rc）；
• 从合并进基分支的标签中探测上一个发版标签（git tag --merged <base>），打印 changelog 边界previousTag..HEAD；
• 更新 components/package.json 与 components/version/version.ts（updateVersionFiles通过正则Version\('.+'\);替换版本号）；
• 运行npm run changelog生成 changelog；
• 打印 changelog 边界与应使用的 PR 基分支。

prepare 模式不会运行本地构建、推送发版分支、发布 npm 或部署站点。

使用 --dry-run 先行演练

想在不写任何文件的前提下核对基分支与 changelog 边界，加--dry-run：

npm run stage-release -- prepare --version 21.3.2 --base v21 --dry-run

dry-run 模式下工作树有改动也只会告警而不会中断（见 release.ts）。

原始的交互式模式仍保留给人类发版者：

npm run stage-release

版本号规则

prepare 模式只更新两处版本：

• components/package.json
• components/version/version.ts

如果用户给了版本号且合法，就使用它；如果用户没给，先查看当前版本、近期标签与待发布上下文，再推荐一个版本。允许的格式为：

• x.y.z
• x.y.z-alpha.n
• x.y.z-beta.n
• x.y.z-rc.n

禁止手动编辑根 package.json 的发布版本（那里是0.0.0-NOT-USED占位）。

Changelog：三份文件的维护

prepare 模式通过执行npm run changelog生成或刷新 changelog 内容。该命令在根 package.json 中定义为：

"changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s --pkg components/package.json && tsx scripts/site/replace-scope-prefix.ts"

即用conventional-changelog（conventionalcommits 预设）生成到 CHANGELOG.md，再经scripts/site/replace-scope-prefix.ts处理 scope 前缀。生成结果只是起点，还需要人工审阅并同步更新三份文件：

• CHANGELOG.md：保持根目录 changelog 既有格式（## version (日期)的样式）。
• docs/changelog.en-US.md：保持文档页格式，包括 frontmatter（order、title、toc、tag）与 intro 内容。
• docs/changelog.zh-CN.md：应为公开发布说明的中文翻译，不能直接照抄英文原文。

格式要点：

• 在每份文件顶部附近新增目标版本小节，遵循该文件既有的## <version>与日期排版。
• 不要把同一段 Markdown 无脑粘贴进三份文件——文档 changelog 有独立的页面结构。
• 中文条目要自然翻译，同时保留 PR 链接、issue 链接、commit 链接、组件 scope 与代码标识符。
• 英文文案要适合作为公开发布说明。

审阅每个发布条目时确认：目标版本标题存在、重要 PR 已体现且分组合理、噪声已清理。英文与中文发布说明都审阅完成之前，不要标记 changelog 步骤完成。

API 与 Demo 的版本标签

对于每个 minor 或 major 发版，在 changelog 审阅之后、发版 commit 与 PR 之前，这是必做步骤。需要为发布范围内新引入的特性，在其既有 API 文档和 Demo 文档中补上缺失的版本标签。Patch 版本跳过此步骤（除非用户明确要求修正版本标签）。

• 在components/<component>/doc/index.en-US.md与index.zh-CN.md中，使用 API 表格的Version/版本列。列缺失时新增该列，无关行留空，保留既有版本值；保持表格单元格对齐（包括空的 global-config 单元格）。
• 新 API 标注引入版本，例如22.1.0。如果只是既有 API 新增了能力，要限定表述：responsive object: 22.1.0/响应式对象：22.1.0，不要暗示整个 API 是新的。
• 在components/<component>/demo/<demo>.md的 YAML frontmatter 中添加version: <version>，针对新引入或新演示该特性的 demo。这是 demo 版本徽标；保留既有顺序、标题、双语描述与 demo 源码。
• 使用发布历史中的实际引入版本。保留更早的版本标签；bugfix 与未变化的 API 或 demo 不新增特性版本标签。
• 此步骤只限于版本列与 demo frontmatter；保留描述、类型、默认值、示例与指南内容。额外解释、API 改写或新 demo 属于单独提出的文档变更。

完成标准：每个新特性的适用 API 行与 demo 都已检查，中英文版本标签一致，diff 中只包含预期标签与必要的表格格式调整。没有适用 API 行或 demo 的特性不需要新增文字。

提交并创建发版 PR

创建发版分支：

git checkout -b release/<version>

只暂存属于该 PR 的发版文件，通常包括：

• CHANGELOG.md
• docs/changelog.en-US.md
• docs/changelog.zh-CN.md
• components/package.json
• components/version/version.ts
• 版本标签步骤中修改过的组件 API 与 demo Markdown 文件

提交信息使用：

chore(release): release <version>

将发版分支推送到用户的 fork 或配置的origin，然后创建 PR。使用仓库的 PR 模板.github/PULL_REQUEST_TEMPLATE.md。

PR 基分支必须与 prepare 时的--base一致。例如 prepare 用了--base v21，PR 就要打到NG-ZORRO/ng-zorro-antd:v21而不是master。正常公共发布列车（release train）的 PR 目标通常是master；维护版本只有在明确要求时才使用对应的维护分支。这也是源码中pushLibraryRelease的行为基础：交互模式会创建release/<version>分支并以chore(release): release <version>提交（见 release.ts）。

构建、发布与部署交给 Azure

Agent 的默认流程不要本地执行Build release、Push library release、Push site release。本地脚本（交互模式）虽包含这些阶段，但项目预期的工作流是 Azure 负责：

• 构建发布产物
• 发布 npm 包
• 部署文档网站

如果用户要求做一次本地构建作为额外 sanity check，可以在明确说明「这只是验证、不是官方发布/部署路径」的前提下运行npm run build。

Azure 发布与站点部署

仅在发版 PR 通过 CI、维护者准备发布时使用此流程。官方包的发布通过 Azure 完成：

1. 打开 Azure 发布管线。
2. 进入对应 release。
3. 点击Publish发布 npm（需要审批）。
4. 点击Deploy更新网站。

不要为官方 NG-ZORRO 包本地执行npm publish，除非维护者明确覆盖正常 Azure 流程。网站更新优先使用 Azure 的Deploy操作；网站也可能通过 cron 自动更新；手动登录服务器只是内部兜底手段，不是 Agent 默认动作。

站点发布在源码中有对应实现：scripts/release/release-site.ts 会把构建输出拷贝进ng-zorro.github.io目录、过滤掉.DS_Store、schematics、server、.idea、.vscode、.git等文件，创建release/<version>分支并提交release: <version>后推送。

发布后的跟进

npm 发布与站点部署完成后：

1. 合并发版 PR 到目标分支。
2. 在 GitHub Releases 页面创建 GitHub Release（对应仓库的 releases 入口）。
3. major 与 minor 版本：更新官方博客。
4. major 与 minor 版本：准备简短的社交通告，附上官网与发布说明链接。

Patch 版本通常不需要博客或社交通告，除非用户要求。

安全红线（Safety Rules）

整套流程中必须遵守以下规则：

• 不要把npm publish作为默认发布路径。
• 不要从脏工作树开始发版。
• 不要覆盖用户改动。
• 用户要求维护版本时不要猜测发版分支；先检查分支，有歧义就问清楚。
• 不要未经明确确认就驱动交互式npm run stage-release流程进入 build 或 push 阶段。
• 不要创建基分支与prepare --base不一致的发版 PR。
• 除非维护者明确要求，不要手动创建或推送标签。
• 构建失败、CI 失败或 Azure 发布步骤失败后，不要继续。

这些规则在 release.ts 的实现中均有一一对应的硬校验：版本格式与递增校验、工作树干净校验、upstream remote 探测、HEAD基于基分支校验等。

Agent 发版检查清单

作为 Agent 协助 NG-ZORRO 发版时的完整步骤：

1. 检查 git 状态、remotes、Node 版本、当前包版本与近期标签。
2. 判断这是 patch、minor、prerelease 还是维护版本。
3. 运行npm run stage-release -- prepare --version <version> --base <branch>。
4. 核对components/package.json、components/version/version.ts、CHANGELOG.md、docs/changelog.en-US.md、docs/changelog.zh-CN.md。
5. 对 minor 与 major 发版，完成上述 API 与 demo 版本标签审阅。
6. 在release/<version>分支上提交发版文件。
7. 使用.github/PULL_REQUEST_TEMPLATE.md创建发版 PR，基分支与prepare --base相同。
8. 创建 PR 后即停止，除非用户明确要求继续 Azure 发布。
9. 官方发布使用 Azure 的Publish与Deploy，不要默认本地npm publish。
10. 完成 GitHub Release、博客与社交通告等发布后任务（如适用）。

关键文件索引

• UI组件
• 前端