企业官网建设流程全解析

Base UI 完整发布流程指南：从 changelog 生成、npm 发布到文档部署与 GitHub Release

【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui

导读

本文基于 Base UI 官方仓库中 scripts/README.md 整理而成，完整讲解 Base UI（Unstyled React UI 组件库）从"准备发布"到"npm 包发布"再到"文档部署"与"GitHub Release 发布"的全流程。文中不仅保留原文档的全部命令与操作步骤，还结合根目录 package.json、lerna.json、scripts/changelog.config.mjs 等仓库源码，补充每条命令的底层实现与配置细节。阅读完本文，你将掌握 Base UI 官方维护者发布一个完整版本的标准化操作，理解其中每条命令的作用与边界条件。

[!NOTE] 以下指令面向拥有发布权限的 Base UI 核心团队（core team）。普通贡献者无法执行发布相关命令，但可以借此理解项目的发布机制与版本管理约定。

一、发布前的整体流程概览

Base UI 采用 pnpm workspace + Lerna 的 monorepo 结构（见根目录 package.json 与 lerna.json，Lerna 配置为independent独立版本模式）。一次典型发布（release）分为四个阶段：

1. Prepare the release of the packages：准备包发布，包括升级版本号、生成 changelog、创建文档版本页；
2. Release the packages：通过pnpm release:publish发布 npm 包（触发 GitHub Actions）；
3. Publish the documentation：将最新代码强制推送到docs-vX分支，由 Netlify 部署文档站点；
4. GitHub release：审核并发布在发布步骤中以草稿形式创建的 GitHub Release。

整个流程的可用脚本都定义在根目录 package.json 的scripts字段中，下面逐阶段展开。

二、Prepare the release of the packages：准备包发布

2.1 创建分支并升级根版本号

1. 基于当前main分支创建一个新的 Git 分支（例如release/v1.8.0）。
2. 更新根目录 package.json 中的version字段，使其与@base-ui/react的目标版本保持一致。例如当前仓库根版本为1.8.0，对应@base-ui/react的v1.8.0版本。

从源码看：根 package.json 声明"name": "@base-ui/monorepo"、"version": "1.8.0"，并配置"engines": { "node": ">=22.23.2", "pnpm": "11.26.0" }，且preinstall使用only-allow强制使用 pnpm，发布前请确保本地 Node 与 pnpm 版本满足要求。

2.2 生成并整理顶层 changelog

3. 运行pnpm release:changelog生成 changelog：

pnpm release:changelog

• 该命令实际调用code-infra generate-changelog（见根 package.json 中"release:changelog": "code-infra generate-changelog"）。
• 生成结果必须前置（prepend）到仓库顶层 CHANGELOG.md 的最前面。仓库现有 CHANGELOG.md 顶部即按# Versions→## v1.8.0→### 组件分类的结构排列，并以注释<!-- generated comparing v1.7.0...master -->标注生成区间。
• 运行pnpm release:changelog --help可查看该命令的更多参数。

changelog 的生成规则从哪来？根目录 scripts/changelog.config.mjs 定义了生成配置：

• format：版本号格式化为v{{version}}；日期与条目格式会受FORMAT环境变量影响（docs模式下日期为加粗**MMM DD, YYYY**，条目附带 PR 链接；非 docs 模式条目末尾追加by @{{author}}）。
• filter：自动排除作者名以[bot]结尾的机器人提交，排除带internal、dependencies、test、release、docs、website等标签的提交，并从贡献者列表中排除 Copilot。
• categorization：按组件维度（strategy: 'component'）归类，识别component:、hook:前缀标签，支持categoryOverrides（如scope: all components→ "General changes"、component: otp field→ "OTP Field"）与flags（breaking change标签强制加 🚨 前缀），未命中的条目落入General changes兜底分类。

4. 根据需要手动完善 changelog，尤其是要完整描述所有 breaking changes。
5. 生成适用于文档格式的 changelog：

pnpm release:changelog:docs

• 该命令通过设置FORMAT=docs环境变量复用同一生成器（见根 package.json 中"release:changelog:docs": "FORMAT=docs code-infra generate-changelog"），产出带日期与 PR 链接、不含作者、适合文档页面展示的格式。

2.3 创建文档发布页面

6. 在docs/src/app/(docs)/react/overview/releases/<version-slug>/page.mdx创建新的发布页面，其中<version-slug>使用连字符格式，例如v1.1.0对应v1-1-0。将上一步生成的 changelog 粘贴进去，并遵循既有发布页的格式：

   • 标题使用# vX.Y.Z；
   • 用<Subtitle>组件标注发布日期；
   • 添加<Meta name="description" content="..." />标签；
   • 移除贡献者列表。

   仓库中已有完整示例：v1.8.0 发布页/react/overview/releases/v1-8-0/page.mdx)、v1.7.0 发布页/react/overview/releases/v1-7-0/page.mdx) 以及v1-0-0到v1-8-0的全系列历史发布页，可直接参考其 MDX 结构。

7. 将第 4 步在顶层 CHANGELOG.md 中做的改动同步复制到新发布页，并按文档格式适配。

8. 在 docs/src/data/releases.ts 中新增一条发布记录，包含version、versionSlug、date、highlights字段；如果是当前最新版本，将latest: true标记移动到新条目。该文件的Release接口定义如下：

export interface Release { version: string; versionSlug: string; date: string; highlights: string[]; latest?: true; }

2.4 执行版本升级并提交 PR

9. 运行版本升级命令：

pnpm release:version

• 该命令实际执行lerna version --no-changelog --no-push --no-git-tag-version --no-private（见根 package.json）。
• 保持稳定公开包（@base-ui/react）的版本与根package.json版本一致；--no-private表示跳过私有包，--no-push/--no-git-tag-version表示不自动推送、不打 Git tag，留给 PR 流程处理。

10. 打开一个 PR 提交以上全部改动，等待 review 与 CI 变绿。
11. 当 PR 接近合并时，在 Base UI 的 Slack 频道发布merge freeze（合并冻结）公告，确保在发布完成、文档部署完成前，main分支不再合入其他改动。
12. 待 CI 全绿且通过 review 后，合并该 PR。

三、Release the packages：发布 npm 包

1. 运行发布命令：

pnpm release:publish

• 该命令实际执行code-infra publish --github-release（见根 package.json）。
• 首次运行或间隔较久后运行，可能会要求你用 GitHub 账号完成身份认证。

2. 命令会自动拉取最新已合并的 release PR，并在发布前请求确认。
3. 如果你已经知道目标 commit 的 sha，可以直接指定：

pnpm release:publish --sha <your-sha>

4. 其他可用标志：

5. 该命令会调用仓库的PublishGitHub Actions 工作流，并在终端打印工作流运行页 URL，可打开查看最新的 workflow run。
6. 随后界面会显示 "@username requested your review to deploy to npm-publish"，点击Review deployments并授权你的 workflow run。绝不批准不是你发起的 workflow run（安全要求）。

发布前的构建约束（从源码看）：根 package.json 中还有release:build脚本，即pnpm docs:generate-llms && cross-env BASE_UI_PUBLISH_DOCS=1 lerna run --concurrency 8 --no-private build --skip-nx-cache --。它设置了BASE_UI_PUBLISH_DOCS=1环境变量，这一点与 packages/react/scripts/stagePublishedDocs.mjs 中的逻辑对应——该脚本只有在BASE_UI_PUBLISH_DOCS被设置时，才会把docs/public下的 markdown 文件（由pnpm docs:generate-llms生成）复制到published-docs/目录随包发布；否则直接跳过。docs:generate-llms由 docs/package.json 中的node --experimental-strip-types ./scripts/generateLlmTxt/index.mjs实现，用于生成可供 LLM / Agent 阅读的文档文本。

四、Publish the documentation：部署文档站点

文档必须更新到对应的docs-vX分支上：v1.X版本用docs-v1，v2.X版本用docs-v2，以此类推。

将最新的 upstreammaster强制推送到文档发布分支，从而用最新改动部署文档：

pnpm docs:deploy

从源码看：根 package.json 中"docs:deploy": "pnpm --filter docs run deploy"，而 docs/package.json 中"deploy": "git fetch upstream master && git push -f upstream FETCH_HEAD:docs-v1"——即先从upstream拉取master，再将FETCH_HEAD强制推送到docs-v1分支。注意：该命令要求你的 Git remote 中已配置名为upstream的远程仓库，且当前部署目标分支固定为docs-v1。

部署完成后：

• 可在 Netlify Dashboard 上跟踪docs-v1过滤的部署进度；
• docs-v1部署完成后，站点将可通过 Base UI 的 Netlify 预览域名访问。

文档部署完成后，在 Base UI 的 Slack 频道解除 merge freeze。

五、GitHub release：发布正式 Release

文档部署完成后，前往 GitHub Releases 页面，找到在发布步骤中以draft（草稿）模式创建的 Release，审核后点击发布。

• 如果发布的是非稳定版本（如 alpha、beta、RC），务必勾选 "Set as a pre-release"复选框，将其标记为预发布版本。

六、流程要点回顾与检查清单

一次完整的 Base UI 发布，可以浓缩为以下检查清单：

掌握以上流程，你就能完整理解 Base UI 这样一个大型 monorepo 项目是如何将一次代码变更安全地转变为 npm 包、官方文档与 GitHub Release 的。对于普通贡献者而言，理解这些步骤也有助于在提交 PR 时更好地配合维护者的发布节奏（例如避免在 merge freeze 期间合入非紧急改动）。

【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui