★ FEATURED ARTICLE 开发工具CLI代码生成【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址https://gitcode.com/gh_mirrors/cr/create-t3-app点击查看免费下载导读create-t3-app 以 pnpm workspace 维护着cliCLI 生成器与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/config2.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: falsechangeset 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.yamlpackages: cli, wwwwww的包名可在 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的语义遵循语义化版本SemVerminor进入版本号的次版本位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/actionv1分两个阶段工作创建版本 PRversion如果存在未消费的变更集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。发布publish版本 PR 合回main后action 再次触发并运行npx changeset publish把新版本发布到 NPM。发布配置了NPM_CONFIG_PROVENANCE: true通过 OIDC token 生成构建来源证明并校验pnpm check与pnpm build:cli通过后才执行。发布产物自动生成的 CHANGELOGCHANGELOG 由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把版本号改写为patch1-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-appBETA_PACKAGE_VERSIONnext 通道对应 .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代码生成【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址https://gitcode.com/gh_mirrors/cr/create-t3-app点击查看免费下载相关推荐Turborepo Monorepo 集成 Changesets变更集驱动的版本管理与自动化发布实战Turborepo Monorepo 集成 Changesets变更集驱动的版本管理与自动化发布实战 Turborepo 为 JavaScript/TypeS构建工具开发工具CLIStack-chan 的 Changesets 发布基础以 .changeset 目录为核心的版本变更与发布治理指南Stack chan 的 Changesets 发布基础以 .changeset 目录为核心的版本变更与发布治理指南 本篇技术指南围绕 Stack chan嵌入式物联网智能硬件机器人硬件开发前端AI 应用Changesets 版本管理与发布指南从 changeset version 到 changeset publish 的完整流程Changesets 版本管理与发布指南从 changeset version 到 changeset publish 的完整流程 版本管理与发布是 Chan开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
