📍 当前位置: 架构图 (2/8) | 导航: ← 上一篇: 总览 | → 下一篇: 核心发现 | 📚 目录

shadcn-ui 架构图#

本文档使用 Mermaid 图表和 ASCII 图来可视化 shadcn-ui 的架构设计。

1. 系统总览#

graph TB
    subgraph "用户项目"
        A[用户代码] --> B[components/ui/]
        A --> C[components.json]
    end

    subgraph "shadcn-ui 项目"
        D[CLI 工具<br/>packages/shadcn] --> E[Registry API]
        F[官网<br/>apps/v4] --> G[组件注册表<br/>registry/]
        G --> H[public/r/]
    end

    subgraph "外部依赖"
        I[@radix-ui/react-*]
        J[Tailwind CSS]
        K[React Hook Form]
    end

    D -.->|npx shadcn add| B
    D -->|获取组件| H
    B --> I
    B --> J
    F -->|构建| H
    G -->|build-registry| H

    style A fill:#e1f5ff
    style D fill:#fff4e6
    style F fill:#f3e5f5
    style H fill:#e8f5e9

2. Monorepo 结构#

┌─────────────────────────────────────────────────────────────┐
│                    shadcn-ui Monorepo                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────────┐       ┌──────────────────────┐    │
│  │   apps/v4/         │       │  packages/shadcn/    │    │
│  │   (Next.js 16)     │       │  (CLI 工具)          │    │
│  ├────────────────────┤       ├──────────────────────┤    │
│  │ • app/             │       │ • src/               │    │
│  │ • registry/        │       │   ├─ commands/       │    │
│  │ • components/      │       │   ├─ registry/       │    │
│  │ • content/docs/    │       │   ├─ utils/          │    │
│  │ • scripts/         │       │   └─ mcp/            │    │
│  │   └─ build-        │       │ • dist/              │    │
│  │     registry.mts   │       │   └─ index.js        │    │
│  │ • public/r/        │◄──────┤                      │    │
│  └────────────────────┘       └──────────────────────┘    │
│         │                              │                    │
│         │                              │                    │
│         ▼                              ▼                    │
│  ┌─────────────────────────────────────────────┐          │
│  │         packages/tests/                     │          │
│  │         (集成测试)                           │          │
│  └─────────────────────────────────────────────┘          │
│                                                             │
└─────────────────────────────────────────────────────────────┘
      pnpm workspace + Turbo 构建管道

3. Registry 系统架构#

sequenceDiagram
    participant User as 用户终端
    participant CLI as shadcn CLI
    participant API as Registry API
    participant CDN as ui.shadcn.com/r/
    participant Local as 本地项目

    User->>CLI: npx shadcn@latest add button
    CLI->>Local: 读取 components.json
    CLI->>API: resolveRegistryDependencies(button)
    API->>CDN: GET /r/styles/new-york-v4/button.json
    CDN-->>API: {files, dependencies, registryDependencies}
    API->>API: 递归解析 registryDependencies
    API-->>CLI: 返回完整依赖树
    CLI->>CLI: 合并 npm 依赖
    CLI->>User: 安装 @radix-ui/react-slot
    CLI->>Local: 写入 components/ui/button.tsx
    CLI->>Local: 更新 components/ui/label.tsx (依赖)
    CLI-->>User: ✓ 组件添加成功

4. Registry 数据流#

┌─────────────────────────────────────────────────────────────┐
│                     Registry 构建流程                        │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
         ┌──────────────────────────────────────┐
         │  registry/bases/{base}/registry.ts   │
         │  (定义基础组件和配置)                 │
         └──────────────────┬───────────────────┘
                            │
                            ▼
              ┌─────────────────────────┐
              │  buildBasesIndex()      │
              │  • 验证 Zod schema      │
              │  • 生成 __index__.tsx   │
              └───────────┬─────────────┘
                          │
                          ▼
         ┌────────────────────────────────┐
         │  Base × Style 矩阵组合         │
         │  base-new-york                 │
         │  base-los-angeles              │
         │  base-miami                    │
         │  radix-new-york                │
         │  radix-los-angeles             │
         │  radix-miami                   │
         └───────────┬────────────────────┘
                     │
                     ▼
       ┌─────────────────────────────┐
       │  transformStyle()           │
       │  • 读取 style-*.css         │
       │  • 创建样式映射 (styleMap)  │
       │  • AST 转换 className       │
       └─────────┬───────────────────┘
                 │
                 ▼
    ┌────────────────────────────┐
    │  buildRegistry()           │
    │  • 生成 JSON 文件          │
    │  • 压缩文件内容            │
    └────────┬───────────────────┘
             │
             ▼
┌────────────────────────────────┐
│  public/r/styles/{style}/      │
│  • button.json                 │
│  • dialog.json                 │
│  • form.json                   │
│  • ... 55+ 组件                │
└────────────────────────────────┘
             │
             ▼
     [CDN / Vercel 部署]

5. 组件依赖关系图#

graph TD
    Dialog[Dialog] --> Button
    Dialog --> Label
    Dialog -.->|npm| RadixDialog[@radix-ui/react-dialog]

    Button -.->|npm| RadixSlot[@radix-ui/react-slot]

    Label -.->|npm| RadixLabel[@radix-ui/react-label]

    Form[Form] --> Button
    Form --> Label
    Form --> Input
    Form -.->|npm| RHF[react-hook-form]
    Form -.->|npm| Zod[zod]

    Input -.->|npm| RadixSlot2[@radix-ui/react-slot]

    Table[Table] --> Badge
    Table --> Button

    DataTable[Data Table] --> Table
    DataTable --> Pagination
    DataTable -.->|npm| TanStack[@tanstack/react-table]

    style Dialog fill:#ffcdd2
    style Form fill:#f8bbd0
    style DataTable fill:#e1bee7
    style Button fill:#c5e1a5
    style Label fill:#c5e1a5
    style Input fill:#c5e1a5

图例：

• 实线箭头：registryDependencies (组件依赖)
• 虚线箭头：dependencies (npm 包依赖)
• 绿色：基础组件
• 红色/粉色：复合组件

6. 三层依赖系统#

┌─────────────────────────────────────────────────────────┐
│                   Dialog 组件依赖树                      │
└─────────────────────────────────────────────────────────┘

dialog
├─ dependencies (npm 包)
│  └─ @radix-ui/react-dialog@^1.0.5
│
├─ registryDependencies (组件)
│  ├─ button
│  │  └─ dependencies
│  │     └─ @radix-ui/react-slot@^1.0.2
│  │
│  └─ label
│     └─ dependencies
│        └─ @radix-ui/react-label@^2.0.2
│
└─ devDependencies
   └─ (无)

合并后的 npm 依赖：
  • @radix-ui/react-dialog@^1.0.5
  • @radix-ui/react-slot@^1.0.2
  • @radix-ui/react-label@^2.0.2

需要复制的文件：
  • components/ui/dialog.tsx
  • components/ui/button.tsx
  • components/ui/label.tsx

7. CLI 工作流程#

stateDiagram-v2
    [*] --> Init: npx shadcn@latest init

    Init --> ConfigCreated: 创建 components.json
    ConfigCreated --> TailwindSetup: 安装 Tailwind CSS
    TailwindSetup --> CSSVarsSetup: 配置 CSS 变量
    CSSVarsSetup --> PathAliasSetup: 设置路径别名
    PathAliasSetup --> Ready: 初始化完成

    Ready --> Add: npx shadcn@latest add [component]

    Add --> ResolveDeps: 解析依赖
    ResolveDeps --> DownloadFiles: 下载文件
    DownloadFiles --> InstallNpm: 安装 npm 包
    InstallNpm --> UpdateConfig: 更新配置
    UpdateConfig --> WriteFiles: 写入文件
    WriteFiles --> ComponentAdded: 组件添加成功

    ComponentAdded --> Diff: npx shadcn@latest diff [component]
    Diff --> CompareVersions: 对比本地与远程
    CompareVersions --> ShowDiff: 显示差异
    ShowDiff --> Ready: 决定是否更新

    ComponentAdded --> Ready
    Ready --> [*]

8. 网站路由架构#

apps/v4/app/
│
├── (app)/                          # 主应用路由组
│   ├── page.tsx                    # 首页
│   │
│   ├── docs/[[...slug]]/          # 文档系统
│   │   └── page.tsx               # 动态文档页面
│   │       ├─ /docs/installation
│   │       ├─ /docs/components/button
│   │       └─ /docs/...
│   │
│   ├── blocks/                     # Block 展示
│   │   ├── page.tsx               # Block 列表
│   │   └── [name]/
│   │       └── page.tsx           # 单个 Block
│   │
│   ├── charts/                     # 图表示例
│   │   └── [type]/
│   │       └── page.tsx
│   │
│   └── examples/                   # 完整示例
│       └── [name]/
│           └── page.tsx
│
├── (view)/                         # 预览路由组 (iframe)
│   └── view/[style]/[name]/
│       └── page.tsx               # 组件隔离预览
│
├── (create)/                       # 创建向导
│   └── create/[...slug]/
│       └── page.tsx
│
└── api/                            # API 路由
    └── og/                         # Open Graph 图片
        └── route.ts

9. 组件预览系统#

┌───────────────────────────────────────────────────────────┐
│               ComponentPreview 渲染策略                    │
└───────────────────────────────────────────────────────────┘

                  ┌─────────────┐
                  │ type 判断   │
                  └──────┬──────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
         ▼                               ▼
    type="block"                   type="component"
         │                               │
         ▼                               ▼
┌─────────────────┐            ┌──────────────────┐
│   移动端预览     │            │   实时渲染       │
│   • PNG 图片     │            │   • <Component/> │
│     (light/dark) │            │   • 代码高亮     │
└─────────────────┘            │   • 复制按钮     │
         +                      └──────────────────┘
┌─────────────────┐
│   桌面端预览     │
│   • iframe       │
│   • 完全隔离     │
│   • 独立样式     │
└─────────────────┘

10. 构建管道#

graph LR
    A[pnpm build] --> B{Turbo 并行执行}

    B --> C[packages/shadcn]
    C --> C1[tsup 构建]
    C1 --> C2[生成 dist/]
    C2 --> C3[多入口点导出]

    B --> D[apps/v4]
    D --> D1[registry:build]
    D1 --> D2[build-registry.mts]
    D2 --> D3[生成 public/r/]
    D3 --> D4[next build]
    D4 --> D5[静态生成]

    C3 --> E[完成]
    D5 --> E

    style A fill:#e3f2fd
    style E fill:#c8e6c9

11. 缓存策略#

┌─────────────────────────────────────────────────────────┐
│                    双层缓存架构                          │
└─────────────────────────────────────────────────────────┘

┌──────────────────────────┐
│  Registry 缓存           │
│  • LRU (max: 500)        │
│  • TTL: 5 分钟           │
│  • Key: style:name       │
│  • 缓存完整组件数据      │
└────────────┬─────────────┘
             │
             ▼
    [getRegistryItem()]
             │
             ▼
┌──────────────────────────┐
│  代码高亮缓存            │
│  • LRU (max: 500)        │
│  • TTL: 1 小时           │
│  • Key: sha256(code+lang)│
│  • 缓存 HTML 高亮结果    │
└────────────┬─────────────┘
             │
             ▼
    [highlightCode()]
             │
             ▼
      [返回高亮的 HTML]

12. 主题系统#

┌─────────────────────────────────────────────────────────┐
│                    CSS 变量层次                          │
└─────────────────────────────────────────────────────────┘

:root (全局)
├─ --background: 0 0% 100%
├─ --foreground: 240 10% 3.9%
├─ --primary: 240 5.9% 10%
├─ --primary-foreground: 0 0% 98%
├─ --secondary: 240 4.8% 95.9%
├─ --muted: 240 4.8% 95.9%
├─ --accent: 240 4.8% 95.9%
├─ --destructive: 0 84.2% 60.2%
├─ --border: 240 5.9% 90%
├─ --input: 240 5.9% 90%
├─ --ring: 240 5.9% 10%
├─ --chart-1 ~ --chart-5
└─ --radius: 0.5rem

        │
        ▼
@media (prefers-color-scheme: dark)
├─ --background: 240 10% 3.9%
├─ --foreground: 0 0% 98%
└─ ... (所有颜色反转)

        │
        ▼
tailwind.config.ts 映射
├─ background: "hsl(var(--background))"
├─ foreground: "hsl(var(--foreground))"
├─ primary: {
│    DEFAULT: "hsl(var(--primary))",
│    foreground: "hsl(var(--primary-foreground))"
│  }
└─ ...

        │
        ▼
Tailwind 类名
├─ bg-background
├─ text-foreground
├─ bg-primary
├─ text-primary-foreground
└─ ...

13. Form 系统 Context 架构#

graph TD
    A[FormProvider<br/>react-hook-form] --> B[Form 组件]

    B --> C[FormField]
    C --> D[FormFieldContext<br/>控制字段名]

    D --> E[FormItem]
    E --> F[FormItemContext<br/>管理 ID]

    F --> G[FormLabel]
    F --> H[FormControl]
    F --> I[FormDescription]
    F --> J[FormMessage]

    H --> K[Input / Select / Textarea]

    style A fill:#ffccbc
    style B fill:#ffccbc
    style C fill:#ffe0b2
    style E fill:#ffe0b2
    style D fill:#fff9c4
    style F fill:#fff9c4
    style G fill:#c5e1a5
    style H fill:#c5e1a5
    style I fill:#c5e1a5
    style J fill:#c5e1a5
    style K fill:#80deea

ARIA 自动关联：

FormControl (id="field-form-item")
    ↓
aria-describedby="field-form-item-description field-form-item-message"
    ↓
FormDescription (id="field-form-item-description")
FormMessage (id="field-form-item-message")

14. CVA 变体系统#

buttonVariants
    │
    ├─ baseClasses (始终应用)
    │  "inline-flex items-center ..."
    │
    └─ variants
       │
       ├─ variant 轴
       │  ├─ default     → bg-primary text-primary-foreground
       │  ├─ destructive → bg-destructive text-white
       │  ├─ outline     → border bg-background
       │  ├─ secondary   → bg-secondary text-secondary-foreground
       │  ├─ ghost       → hover:bg-accent
       │  └─ link        → text-primary underline
       │
       └─ size 轴
          ├─ default   → h-9 px-4 py-2
          ├─ sm        → h-8 px-3
          ├─ lg        → h-10 px-6
          ├─ icon      → size-9
          ├─ icon-sm   → size-8
          └─ icon-lg   → size-10

组合示例：
buttonVariants({ variant: "destructive", size: "lg" })
    ↓
"inline-flex items-center ... bg-destructive text-white h-10 px-6"

15. MCP (Model Context Protocol) 集成#

sequenceDiagram
    participant AI as AI 助手
    participant MCP as MCP 服务器<br/>packages/shadcn/src/mcp
    participant CLI as shadcn CLI
    participant Project as 用户项目

    AI->>MCP: 调用 add_component 工具
    MCP->>CLI: 执行 add 命令
    CLI->>Project: 添加组件
    Project-->>CLI: 成功
    CLI-->>MCP: 返回结果
    MCP-->>AI: 组件已添加
    AI-->>AI: 继续对话

MCP 工具列表：

packages/shadcn/src/mcp/tools.ts
├─ add_component        # 添加组件
├─ init_project         # 初始化项目
├─ diff_component       # 查看差异
├─ list_components      # 列出可用组件
└─ get_component_info   # 获取组件信息

总结#

shadcn-ui 的架构设计体现了以下特点：

1. 清晰的分层: Monorepo 结构清晰分离 CLI、官网、测试
2. 灵活的 Registry: 支持多源、多风格、版本管理
3. 强大的依赖解析: 三层依赖系统自动处理复杂依赖
4. 高性能: 双层 LRU 缓存 + React.lazy + Turbopack
5. 开发者友好: CLI + 文档 + MCP + 详细示例
6. 现代化技术栈: Next.js 16 + React 19 + TypeScript 5.5 + Tailwind 4

这套架构为构建类似的组件分发系统提供了完整的参考范例。