企业官网建设流程全解析

• 开发工具
• CLI
• 代码生成

导读

create-t3-app 以 pnpm workspace 维护着cli（CLI 生成器）与www（文档站）两个包，每次向cli的源码或模板提交改动，都必须通过.changeset目录下的变更集文件记录版本影响，再由 Changesets 工具链自动完成版本号计算、CHANGELOG 生成与 NPM 发布。本文以仓库根目录 .changeset/README.md 为起点，结合 .changeset/config.json、CI 校验脚本与 GitHub Actions 发布流水线，完整还原这套「写变更集 → 校验 → 聚合版本 → 自动发布」的工作流。读完本文，你将掌握该仓库的版本管理规范，并能照搬到自己的单包或多包项目中。

一、.changeset目录是什么

仓库根目录的 .changeset/README.md 是该目录的官方说明文件，它开门见山地指出：这个文件夹由@changesets/cli自动生成，是一个在多包仓库（multi-package repos）或单包仓库（single-package repos）中帮助你完成版本（version）与发布（publish）的构建工具。README 还提示读者，完整文档与常见问题解答可在 changesets 官方仓库与其 docs/common-questions 文档中找到。

在 create-t3-app 中，这一机制承载着核心职责：每一次会影响cli行为的改动，都要留下一个变更集（changeset）文件，作为未来版本号升级与 CHANGELOG 生成的唯一事实来源。当前.changeset目录中的实际文件包括：

.changeset/ ├── README.md ├── config.json ├── beige-clouds-behave.md ├── curly-zoos-add.md ├── quick-snakes-give.md └── tender-humans-hide.md

其中README.md是说明文档，config.json是 Changesets 的行为配置，其余四个.md文件则是尚未发布（pending）的变更集——它们是理解这套机制的最佳真实样本。

二、配置解析：.changeset/config.json的每个字段

.changeset/config.json 是 Changesets 在仓库内的配置文件，完整内容如下：

{ "$schema": "https://unpkg.com/@changesets/config@2.1.1/schema.json", "changelog": [ "@changesets/changelog-github", { "repo": "t3-oss/create-t3-app" } ], "commit": false, "fixed": [], "linked": [], "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": ["@ct3a/www"], "changedFilePatterns": ["src/**", "template/**"] }

各字段的含义与该项目中的实际作用如下：

• $schema：指向 changesets config 2.1.1 的 JSON Schema，让编辑器在编辑本文件时提供字段校验与补全。
• changelog：指定 CHANGELOG 的生成方式。这里使用@changesets/changelog-github，并传入{ "repo": "t3-oss/create-t3-app" }，意味着生成的 changelog 条目会带上 GitHub 上的 PR 编号、提交哈希与贡献者昵称——这正是 cli/CHANGELOG.md 中每条记录格式的来源（见下文第六节）。
• commit: false：changeset version命令执行时不会自动提交（commit）版本变更，提交动作由发布流水线中的changesets/action完成。
• fixed: []/linked: []：不启用「固定版本组」与「联动版本组」。本项目只有cli需要发布，因此不需要把多个包的版本强制绑在一起。
• access: "public"：发布到 NPM 时使用 public 访问级别（create-t3-app是公开包）。
• baseBranch: "main"：以main作为计算变更集状态的基准分支，CI 中的校验也依赖它（见第四节）。
• updateInternalDependencies: "patch"：当同仓库内部包之间的依赖（internal dependencies）发生变化时，以patch粒度更新依赖声明范围。本项目cli与www之间实际不存在发布依赖，该值属于通用配置。
• ignore: ["@ct3a/www"]：将文档站www包排除在版本计算与发布之外——它只被构建部署，从不发布到 NPM。包名与目录的对应关系见根目录 pnpm-workspace.yaml（packages: cli, www），www的包名可在 www/package.json 中确认。
• changedFilePatterns: ["src/**", "template/**"]：声明了「哪些文件路径的变更会被视为包发生了变更」——即cli的src/**（CLI 源码）与template/**（脚手架模板）。从源码结构看，cli/template目录正是生成新项目时被复制的模板文件，因此对模板的任何改动同样需要变更集记录。

三、变更集文件：patch 与 minor 的真实样本

变更集文件是这套机制的「最小单元」。一个标准变更集由两部分组成：以---包裹的 frontmatter（声明哪个包、升哪一级版本号）与正文（人类可读的变更说明）。仓库中四个未发布的变更集恰好覆盖了不同场景：

补丁级修复（patch），一次性修复多个 issue：

--- "create-t3-app": patch --- fix #1903 #2157 #2163

对应文件：.changeset/beige-clouds-behave.md。patch表示向下兼容的问题修复，同时解决三个 issue 可以合并进同一个变更集。

次要功能（minor），新增行为但不破坏兼容：

--- "create-t3-app": minor --- Fixes Biome formatter during the initial installation process

对应文件：.changeset/curly-zoos-add.md。它描述了对脚手架安装流程中 Biome 格式化行为的改进。minor与patch的语义遵循语义化版本（SemVer）：minor进入版本号的次版本位，patch进入修订位，major（不兼容变更）则会触发主版本升级。

安全补丁（security bump），说明安全更新动机：

--- "create-t3-app": patch --- fix(security): bump react and next

以及：

--- "create-t3-app": patch --- fix(security): bump react (CVE-2025-55182)

对应文件分别为 .changeset/quick-snakes-give.md 与 .changeset/tender-humans-hide.md。可见该仓库在升级依赖以修复安全漏洞时，也会以变更集的形式记录，确保安全修复进入发布说明。

几点实操经验可以从这些样本中提炼：

• 每个变更集只声明一个包（此处均为"create-t3-app"），多包各自独立声明；
• 多个不相关的修复不要挤在一个变更集里，但一次 PR 解决多个 issue 时可以在同一个变更集中引用多个编号；
• 变更集文件名是随机生成的形容词-名词组合（如beige-clouds-behave），文件名本身没有业务含义，无需修改。

四、如何新增一个变更集：命令与提交规范

贡献指南 CONTRIBUTING.md 明确规定了新增变更集的流程：当你的改动会影响 CLI 或生成的应用的行为、需要出现在 changelog 中时，运行：

pnpm changeset

按提示选择受影响的包（create-t3-app）并填写变更说明，工具会在.changeset下生成一个新的.md变更集文件，随后提交：

git add .changeset/*.md && git commit -m "chore: add changeset"

根目录 package.json 中声明的脚本与依赖也印证了这套流程："release": "changeset version"用于在发布前聚合变更集，而@changesets/cli（^2.27.3）与@changesets/changelog-github（^0.4.8）被列在根依赖中，是这套工具链的实际载体。

CI 强制校验：忘记写变更集会导致流水线失败

提交变更集不是可选项，而是被 CI 强制执行的要求。.github/workflows/ci.yml 中的check-changeset任务会在每次 Pull Request 时运行：

git fetch origin main:main changes=$(git diff --name-only main...${{ github.sha }} | grep '^cli/' || true) if [[ -n "$changes" ]]; then pnpm changeset status --since origin/main fi

这段逻辑的含义是：只要本次提交相对main分支的差异中涉及cli/目录（源码或模板），就必须通过pnpm changeset status --since origin/main的校验——即确认确实存在针对create-t3-app包的变更集；否则 CI 失败。这正是「改了 CLI 就必须写变更集」的工程化落地方式。

五、发布流水线：从 Version PR 到 NPM 发布

当变更集被合并进main后，.github/workflows/release.yml 接管后续流程。它监听main分支的 push 事件，使用changesets/action@v1，分两个阶段工作：

1. 创建版本 PR（version）：如果存在未消费的变更集，action 会创建一个标题为chore(release): version packages的 PR，执行版本脚本 .github/changeset-version.js。该脚本（源自 Cloudflare Wrangler 的同类实现）依次执行：

exec("npx changeset version"); exec("npm install");

changeset version会读取.changeset/*.md，统一提升cli/package.json的版本号、删除已消费的变更集文件，并基于变更说明生成 CHANGELOG；随后npm install同步更新锁文件（这是对changeset version不自动更新 lockfile 的已知问题的官方 workaround）。

2. 发布（publish）：版本 PR 合回main后，action 再次触发并运行npx changeset publish，把新版本发布到 NPM。发布配置了NPM_CONFIG_PROVENANCE: true（通过 OIDC token 生成构建来源证明），并校验pnpm check与pnpm build:cli通过后才执行。

发布产物：自动生成的 CHANGELOG

CHANGELOG 由@changesets/changelog-github生成，cli/CHANGELOG.md 是它的直接产物。以 7.38.0 为例，每条记录都包含「PR 编号 + 提交哈希 + 贡献者 + 变更描述」，并按Minor Changes/Patch Changes分组：

### Minor Changes - [#2000](https://github.com/t3-oss/create-t3-app/pull/2000) [`41de302b...`] Thanks [@ronanru](https://github.com/ronanru)! - update to next.js 15 and next-auth v5

这与变更集 frontmatter 中的minor/patch级别一一对应，也印证了第三节对版本语义的说明。

六、预发布通道：beta 与 next 版本是怎么来的

除了正式的版本发布，仓库还维护了两条预发布通道，分别用于 PR 联调（beta）与迭代预览（next）。

beta 通道由 .github/workflows/prerelease.yml 驱动：当 PR 被打上🚀 autorelease标签时，先运行 .github/version-script-beta.js，把版本号改写为patch+1-beta.<commit短哈希>形式，再通过pnpm pub:beta（见 cli/package.json 的pub:beta脚本：pnpm build && npm publish --tag beta）发布到 NPM 的beta标签。发布成功后，.github/workflows/prerelease-comment.yml 会自动在 PR 上留言安装命令，并移除🚀 autorelease标签：

pnpm create t3-app@<BETA_PACKAGE_VERSION>

next 通道对应 .github/version-script-next.js，逻辑与 beta 一致，只是版本后缀改为-next.<commit短哈希>，对应cli/package.json中的pub:next脚本（npm publish --tag next）。两条通道的核心逻辑相同：用 git 短哈希做预发布版本标识，避免污染正式版本序列。

七、常见问题与实操要点

根据 .changeset/README.md 的指引，changesets 官方文档的 common-questions 部分覆盖了更多常见问题；结合本仓库的实际结构，以下几类问题最常遇到：

改了cli但没写变更集？CI 的check-changeset任务会直接失败。回到本地运行pnpm changeset补齐变更集并提交即可，无需重写历史。

变更集写错版本级别（patch/minor）？直接编辑.changeset/*.md的 frontmatter 中的"create-t3-app": patch|minor|major即可，版本计算只发生在合并后。

不想让某次改动触发版本升级？改动不涉及changedFilePatterns中声明的src/**与template/**（例如只改文档或 CI 配置），CI 的 diff 检查不会命中cli/变更判断，也就不需要变更集。www目录的改动同理——它被ignore排除，从不参与发布。

版本 PR 如何合并？changeset version之后，版本 PR 中会看到版本号提升、CHANGELOG 更新与变更集文件被删除三处变化，人工审查无误后合回main，发布便自动触发。

结语

通过本仓库可以看到，Changesets 并不是一个「写几个 md 文件」的简单约定，而是一条完整的自动化链路：开发者提交变更集 → CI 用changeset status强制校验 → 合并后changeset version聚合版本并生成 CHANGELOG →changeset publish发布到 NPM，另有 beta/next 预发布通道支撑 PR 阶段的提前验证。这套以 .changeset/README.md 为入口、以 .changeset/config.json 为中枢、以.github下多个工作流为执行的体系，正是 create-t3-app 这类高频迭代 CLI 项目保持版本纪律的关键。如果你的项目也在用 pnpm workspace 管理多个包并需要发布到 NPM，完全可以照抄这套「配置 + 变更集 + CI 校验 + release 流水线」的组合。

• 开发工具
• CLI
• 代码生成