构建与发布

相关源文件

• .github/workflows/prerelease-comment.yml
• .github/workflows/prerelease.yml
• .github/workflows/release.yml
• apps/v4/registry.json
• apps/v4/scripts/build-registry.mts
• apps/www/content/docs/installation/manual.mdx
• apps/www/next-env.d.ts
• apps/www/public/r/styles/new-york-v4/accordion.json
• apps/www/public/r/styles/new-york-v4/index.json
• packages/cli/README.md
• packages/shadcn/src/migrations/migrate-icons.ts

本文档涵盖了 shadcn-ui 组件系统的构建过程、持续集成工作流和发布管理。它解释了组件如何被处理成注册表，如何通过 GitHub Actions 自动化发布，以及开发者如何创建自定义组件注册表。

有关组件安装和 CLI 使用的信息，请参阅 CLI 工具。有关组件注册表结构和分发的详细信息，请参阅 组件注册表系统。

注册表构建系统

注册表构建系统将源代码组件转换为 CLI 可以使用的可分发 JSON 元数据。此过程主要通过 build-registry.mts 脚本进行管理，涉及多个编译和转换阶段。

构建流水线架构

源文件： apps/v4/scripts/build-registry.mts9-178

注册表索引生成

buildRegistryIndex() 函数创建了一个全面的 TypeScript 索引文件，该文件支持在开发和文档生成过程中进行动态组件加载。

生成的索引文件包含

• 使用 React.lazy() 进行的动态 React 组件导入
• 组件解析的文件路径映射
• 注册表组件的依赖图
• 类别和描述的元数据

源文件： apps/v4/scripts/build-registry.mts9-69

JSON 注册表处理

buildRegistryJsonFile() 函数将内部注册表格式转换为 CLI 工具使用的公共 JSON schema。

功能	输入	输出	目的
buildRegistryJsonFile()	registry.items	registry.json	CLI 可用格式
buildRegistry()	registry.json	public/r/styles/	Web 可访问的 JSON 文件
syncRegistry()	apps/www/public/r/	apps/v4/public/r/	跨应用一致性

转换过程包括

• 路径规范化，包含 registry/new-york-v4/ 前缀
• 文件元数据保留
• 依赖映射
• 组件分类

源文件： apps/v4/scripts/build-registry.mts71-96 apps/v4/scripts/build-registry.mts98-112

发布工作流

该项目使用 GitHub Actions 和 Changesets 进行版本管理，实现了自动发布工作流。该系统支持稳定发布和 Beta 预发布进行测试。

发布架构

源文件： .github/workflows/release.yml1-54 .github/workflows/prerelease.yml1-61

稳定发布流程

稳定发布工作流在每次推送到主分支时触发，并使用 Changesets 进行版本管理。

release.yml 中的关键工作流步骤

1. 构建验证：运行 pnpm shadcn:build 以确保包构建成功
2. Changesets Action：自动检测更改并创建版本 PR
3. NPM 发布：在版本 PR 合并后发布到 NPM

所需的环境变量

• GITHUB_TOKEN：用于创建版本 PR
• NPM_TOKEN：用于发布到 NPM 注册表
• NODE_ENV：设置为 "production" 以进行发布构建

源文件： .github/workflows/release.yml40-53

Beta 发布流程

Beta 发布通过向拉取请求添加 🚀 autorelease 标签来触发，以实现对未发布更改的测试。

Beta 工作流

1. 修改 package.json 的版本号，添加 Beta 后缀
2. 使用 Beta 标签发布到 NPM
3. 在 PR 上评论安装命令
4. 自动移除触发标签

源文件： .github/workflows/prerelease.yml12-48 .github/workflows/prerelease-comment.yml1-66

包管理集成

发布系统与单仓库项目的包管理集成

命令	目的	工作区
pnpm shadcn:build	构建 CLI 包	packages/shadcn
pnpm pub:beta	发布 Beta 版本	packages/shadcn
npx changeset publish	发布稳定版	根工作区
pnpm registry:build	构建组件注册表	apps/www, apps/v4

源文件： .github/workflows/release.yml40 .github/workflows/prerelease.yml48

注册表同步

syncRegistry() 函数通过同步其公共注册表目录，来维护主文档网站（apps/www）和 v4 应用程序之间的一致性。

此同步确保

• 两个应用程序提供相同的注册表内容
• v4 应用可以访问 www 的已构建注册表文件
• 本地开发与生产环境保持一致

源文件： apps/v4/scripts/build-registry.mts114-141

组件文件处理

构建系统将组件文件从其源位置处理到可分发的注册表格式。注册表中的每个组件条目都包含文件路径、依赖项和元数据。

文件路径解析

构建过程处理三种类型的文件引用

1. 内部路径：用于开发索引中的动态导入
2. 公共路径：用于分发的 JSON 注册表
3. 已解析路径：用于文件系统操作的绝对路径

源文件： apps/v4/scripts/build-registry.mts19-46

组件元数据处理

每个注册表项在构建过程中都经过元数据转换

元数据字段	来源	处理方式	输出
名称	注册表定义	直接复制	组件标识符
类型	注册表定义	直接复制	registry:ui, registry:block, 等
files	注册表定义	路径前缀	公共文件引用
dependencies	注册表定义	直接复制	NPM 依赖
registryDependencies	注册表定义	直接复制	内部组件依赖
cssVars	注册表定义	直接复制	主题变量

源文件： apps/v4/scripts/build-registry.mts73-87