本文档描述了 shadcn/ui 代码库的整体系统架构，包括单仓库结构、组件分发模型和构建系统。有关 CLI 命令的详细信息，请参阅 CLI 工具。有关组件组织和类型，请参阅 组件系统。
shadcn/ui 系统被组织为一个 pnpm 工作区（workspace）单仓库，包含多个应用程序和包。工作区配置定义了两个主要应用程序目录和一个用于共享工具的 packages 目录。
工作区在根目录的 package.json 中定义，其工作区指向 apps/* 和 packages/* 目录。构建编排由 Turborepo 处理，而依赖管理则使用 pnpm 工作区来实现包之间的有效链接。
来源： package.json11-14 pnpm-lock.yaml1-6
与传统的 npm 包库不同，shadcn/ui 通过注册表系统分发组件的源代码。这种“复制粘贴”模式允许用户直接在其项目中拥有和自定义组件。
注册表系统通过 build-registry.mts 处理组件源文件和元数据，生成内部使用索引文件和公共分发文件。CLI 工具从公共注册表中获取组件，并将其直接复制到用户项目中。
来源： apps/v4/scripts/build-registry.mts9-69 apps/v4/registry.json1-20 packages/shadcn/package.json49-50
该系统维护两个 Next.js 应用程序，它们在 shadcn/ui 生态系统中服务于不同的目的。
文档站点使用 Next.js 和 Contentlayer 进行 MDX 处理，并作为主要的注册表构建器。它生成供 CLI 工具使用的公共注册表文件。
来源： apps/www/package.json80-82 apps/www/package.json8-10 apps/www/tsconfig.json20-23
v4 应用程序代表了下一代文档站点，使用了最新版本的 React 和 Tailwind CSS。它与 www 应用程序协调以进行注册表同步。
来源： apps/v4/package.json78-83 apps/v4/package.json7-8 apps/v4/scripts/build-registry.mts114-141
注册表构建系统将组件源文件转换为可供 CLI 使用的分布式格式。
构建过程包括四个主要阶段：索引生成、路径修复、CLI 构建执行和注册表同步。每个阶段都会转换注册表数据以适应不同的使用模式。
来源： apps/v4/scripts/build-registry.mts9-68 apps/v4/scripts/build-registry.mts71-96 apps/v4/scripts/build-registry.mts98-112
活动 CLI 包 (packages/shadcn) 提供了组件安装和项目设置的主要接口。
CLI 架构将命令处理与核心功能分离，设有专门的模块用于配置、注册表交互、代码转换和依赖管理。
来源： packages/shadcn/package.json61-86 packages/shadcn/src/migrations/migrate-icons.ts1-16 packages/shadcn/package.json29-42
monorepo 在应用程序和包之间维护不同的依赖策略。
| 组件 | React 版本 | Next.js 版本 | Tailwind 版本 | 目的 |
|---|---|---|---|---|
apps/www | 18.3.1 | 14.3.0-canary.43 | 3.4.6 | 稳定文档 |
apps/v4 | 19.1.0 | 15.3.1 | 4.1.8 | 下一代 |
packages/shadcn | 不适用 | 不适用 | 不适用 | CLI 工具 |
packages/cli | 不适用 | 不适用 | 不适用 | 已弃用 |
版本策略允许 v4 应用程序测试尖端功能，同时保持主文档站点的稳定性。CLI 包保持框架无关性，以支持各种项目配置。
来源： apps/www/package.json84-86 apps/v4/package.json81-83 packages/cli/CHANGELOG.md3-5 packages/shadcn/CHANGELOG.md3-7