Astryx Monorepo工程实践：pnpm 11 + Changesets 可信发布流水线完全指南
【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx
Astryx 是一个开源、完全可定制且面向 AI Agent 的设计系统（Design System）。它的 Monorepo 工程体系由三大支柱组成：pnpm 11 工作区管理、Changesets 版本管理，以及基于npm OIDC 可信发布的零长期 Token 发布流水线。本文面向新手，带你快速看懂这套体系是如何运作的，以及为什么它值得你在自己的项目中借鉴。
📦 Monorepo 布局：一份 workspace 配置统领全局
Astryx 的仓库按职责分为四层：packages/（核心库、CLI、各主题包）、apps/（文档站、Storybook、沙盒）、internal/（内部工具与测试设施）、scripts/（仓库级脚本）。全部公共包都以@astryxdesign/*命名，共 12 个可发布包。
pnpm 11：配置从 package.json 迁移到 pnpm-workspace.yaml
仓库锁定pnpm@11.10.0（见 package.json 的packageManager字段）。pnpm 11 把原来分散在.npmrc和package.json里的配置统一收进了 pnpm-workspace.yaml，有几个对新手很实用的细节：
- 依赖目录扁平化：
nodeLinker: hoisted+shamefullyHoist，保持 Yarn 1 风格的node_modules布局，避免构建工具和测试偶发导入找不到依赖。 - Catalog 版本统一：
vite、@stylexjs/stylex、prettier、esbuild等全仓库工具只在 catalog 里声明一次，所有消费方写"catalog:"，升级时改一处即可，永远不会出现"两个 vite 大版本并存"的裂脑问题。 - 供应链防线：
minimumReleaseAge: 10080（7 天）阻止刚发布、可能含恶意代码的新版本混入依赖图；overrides里每条都是"活的安全地板"，并注释了依赖来源和删除条件（如 pnpm-workspace.yaml#L47-L80）。 - 构建脚本白名单：pnpm 11 用
allowBuilds映射替代旧版onlyBuiltDependencies，只有esbuild、sharp等少数包被允许执行安装期脚本。
🚦 Changesets 版本管理：让 changelog 自己"长"出来
锁步版本：12 个包共用一套版本号
.changeset/config.json 把core、cli、build和全部 7 个主题包放进fixed数组——它们版本永远一致。任何一个包升级，全套同步 bump，消费者不会出现"core 领先 theme 两个版本"的地狱场景；而 Storybook、Sandbox 等内部应用则被列入ignore，不参与发布。
三步走：changeset → version → publish
- 写 changeset：开发者运行
pnpm changeset:new。它不是裸的changeset命令，而是仓库封装的 scripts/changeset-new.mjs，会自动检测本次改动涉及哪些包并预选好，还会记录贡献者身份——不用手工枚举 frontmatter。 - CI 门禁把关：scripts/check-changesets.mjs 强制四条约定：0.x 阶段 breaking 变更只能 bump minor、必须带
[category]标签、必须署名贡献者、frontmatter 里的包必须真实存在。格式不合规的 PR 直接红灯。 - Version Packages PR：合并后运行
pnpm version-packages，它串联changeset version、codemod 提升（把暂存在next/目录的破坏性变更迁移脚本转正为正式版本）、内部依赖同步和 changelog 格式化，全部落盘为文件改动，再开一个 PR 人工复核。
🔐 可信发布流水线：CI 里没有一个 NPM_TOKEN
npm OIDC：用"身份"代替"密码"
传统做法是在 CI 里存一个NPM_TOKEN长期凭证——它泄露一次就前功尽弃。Astryx 采用npm Trusted Publishing（OIDC）：发布时 CI 向 GitHub 换取一个短生命周期身份令牌，当场兑换成 registry 凭证，并为每个包打上provenance（来源溯源）印章。信任关系配错会直接响亮地失败，没有 Token 可兜底，详见 docs/release.md。
一个 release.yml 统领 stable 与 canary 双轨
npm 每个包只允许一个可信发布者配置，所以所有发布都收敛在 release.yml 一个工作流文件里：
| 发布轨 | 触发方式 | 产物 |
|---|---|---|
| Stable（latest） | 手动 dispatch | 已 bump 的正式版本，支持 dry-run 预览 |
| Canary | 每次 push 到 main | 0.x.y-canary.<sha>，用户可npm i @astryxdesign/core@canary |
两个 Job 各自独立的并发组：频繁的 canary 推送永远不会挤占或取消一次 stable 发布。发布全程版本幂等——已发布过的版本自动跳过，重跑零副作用。
配套设施：一键配信任 + 定期清 canary
- scripts/npm/setup-trusted-publishing.mjs：维护者本地运行的一次性脚本，三种模式（审计 /
--bootstrap抢注包名 /--setup-trust注册信任配置），幂等、可 dry-run。 - scripts/npm/prune-canaries.mjs：canary 发布后自动清理旧版本，默认只动 npm 允许的 72 小时窗口内版本，保持 registry 上 Versions 列表干净。
💡 新手可抄作业的 5 个要点
- 配置集中化：pnpm 11 下把 hoist、overrides、版本 pin 全部收进
pnpm-workspace.yaml，并用 catalog 统一工具版本； - 供应链设"地板"：
minimumReleaseAge+ 带删除条件的安全 override，比盲目latest稳得多； - 锁步版本：强耦合的包组用
fixed数组锁定，杜绝版本漂移； - changeset 也要门禁：用自定义脚本自动检测受影响包 + CI 校验格式，changelog 质量交给机器；
- 去 Token 化：npm OIDC 可信发布 + provenance，CI 里不留任何长期凭证，且发布幂等可重跑。
更多细节可查阅 docs/release.md、docs/architecture/ 以及根目录 CONTRIBUTING.md。
【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
