shadcn/ui 实战：复制即用的现代 React 组件库

一句话结论：shadcn/ui 把"组件库"变成"代码片段"。你可以完全控制代码、样式和依赖。

核心概念

传统组件库（Material UI）：
import { Button } from '@mui/material';
- 依赖打包后 ~100KB
- 样式不易覆盖
- 升级容易 break

shadcn/ui：
npx shadcn@latest add button
- 把代码复制到你的项目
- 0 依赖（你拥有代码）
- 升级随你

实战：5 分钟搭建

Step 1：初始化

npx create-next-app@latest my-app
cd my-app
npx shadcn@latest init

Step 2：选主题

# 多个内置主题
npx shadcn@latest init --theme slate

Step 3：添加组件

# 单个组件
npx shadcn@latest add button

# 多个组件
npx shadcn@latest add button card dialog input

# 完整 dashboard
npx shadcn@latest add dashboard

Step 4：使用

import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";

export default function Home() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>欢迎使用 shadcn/ui</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>点击我</Button>
        <Button variant="outline">次要按钮</Button>
        <Button variant="destructive">危险操作</Button>
      </CardContent>
    </Card>
  );
}

5 个核心优势

1. 代码完全可控

# 组件就在你的项目里
src/components/ui/button.tsx
# 可以任意修改

2. 零运行时依赖

# 不需要安装 @shadcn/ui 包
# 节省 bundle 体积

3. 与 Tailwind 完美集成

// 用 cn() 工具合并 className
<Button className="bg-blue-500 hover:bg-blue-600">
  自定义样式
</Button>

4. 主题灵活

/* globals.css */
:root {
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
}

[data-theme="dark"] {
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
}

5. 与 Next.js 完美集成

// RSC 友好
// 默认在 Server Component 渲染
<Button>服务端渲染</Button>

5 个常见坑

坑 1：组件重复

# 误操作：多次 add 同一组件
# 解决：检查 src/components/ui/ 是否有重复

坑 2：依赖冲突

# shadcn 自动安装依赖
# 但可能与其他包版本冲突
# 解决：手动锁定 package.json

坑 3：自定义主题混乱

/* ❌ 混乱：直接覆盖 class */
.button { background: red; }

/* ✅ 正确：用 CSS 变量 */
:root {
  --primary: 0 100% 50%;
}

坑 4：Server Component 报错

// ❌ 错：onClick 在 Server Component
<Button onClick={...}>点击</Button>

// ✅ 正确：加 'use client'
'use client';
<Button onClick={...}>点击</Button>

坑 5：升级困难

shadcn 更新 ≠ 你的代码更新
你需要手动重新 add 组件
或用 git diff 看变更

何时用 shadcn

✅ 适合

• Next.js / Vite + React + Tailwind 项目
• 想要现代化 UI
• 想要完全控制

❌ 不适合

• 非 React 项目
• 不喜欢 Tailwind
• 需要复杂设计系统

参考

• shadcn/ui 官方文档
• shadcn CLI

---

本文基于 shadcn/ui 最新版本。