shadcn/ui 的使用流程与传统组件库（如 Ant Design 或 Material UI）完全不同。它不是通过 import { Button } from 'shadcn-ui' 来使用的，而是将组件的源代码直接复制到你自己的项目中。
以下是 shadcn/ui 的具体使用实现步骤，以 React + Next.js + Tailwind CSS 为例：
第一步：环境准备
在使用之前，你的项目必须满足以下前提条件：
- 框架：React (推荐 Next.js) 或 Vue (实验性支持)。
- 样式库 ：必须安装并配置好 Tailwind CSS。
- 构建工具：Vite, Next.js, Remix 等。
- TypeScript (强烈推荐，虽然支持 JS，但官方主要维护 TS 版本)。
第二步：初始化 (Initialization)
在你的项目根目录下，运行官方 CLI 工具进行初始化。这会创建一个配置文件 components.json，并设置好路径别名和基础样式变量。
npx shadcn@latest init运行过程中你会看到交互式提示：
- Style: 选择默认风格（Default）或纽约风格（New York）。
- Base Color: 选择主色调（如 Slate, Gray, Zinc 等）。
- CSS Variables: 确认是否使用 CSS 变量来管理主题颜色（推荐 Yes）。
- Components Path : 确认组件存放路径（默认为
@/components）。
执行后发生了什么？
- 生成了
components.json配置文件。 - 在
app/globals.css(Next.js) 或index.css中注入了大量的 CSS 变量（用于定义颜色、半径等主题系统）。 - 安装了必要的依赖（主要是
class-variance-authority,clsx,tailwind-merge,lucide-react等工具库，以及底层的radix-ui组件）。
第三步：添加组件 (Adding Components)
这是核心步骤。你不需要安装组件包，而是"拉取"代码。
命令格式：
npx shadcn@latest add <组件名>示例：添加一个按钮 (Button) 和一个对话框 (Dialog)
npx shadcn@latest add button dialog执行后发生了什么？
CLI 会自动下载这些组件的源代码文件，并放置在你配置的目录中（通常是 components/ui/）。
你的项目结构会变成这样：
src/
├── components/
│ └── ui/
│ ├── button.tsx <-- 代码直接在这里，你可以随意修改！
│ ├── dialog.tsx <-- 代码直接在这里
│ └── ...
├── lib/
│ └── utils.ts <-- 提供 cn() 函数，用于合并类名第四步：在代码中使用 (Usage)
现在，这些组件就是你本地普通的 React 组件了。你可以像导入自己写的组件一样导入它们。
示例代码 (page.tsx 或 App.tsx)：
TypeScript
import { Button } from "@/components/ui/button";
import {
Dialog,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input"; // 假设你也添加了 input
export default function Demo() {
return (
<Dialog>
<DialogTrigger asChild>
<Button variant="outline">打开设置</Button>
</DialogTrigger>
<DialogContent className="sm:max-w-[425px]">
<DialogHeader>
<DialogTitle>编辑个人资料</DialogTitle>
<DialogDescription>
在这里修改你的个人信息。点击保存后生效。
</DialogDescription>
</DialogHeader>
<div className="grid gap-4 py-4">
<div className="grid grid-cols-4 items-center gap-4">
<label htmlFor="name" className="text-right">用户名</label>
<Input id="name" defaultValue="Pedro Duarte" className="col-span-3" />
</div>
</div>
<DialogFooter>
<Button type="submit">保存更改</Button>
</DialogFooter>
</DialogContent>
</Dialog>
);
}第五步：定制与修改 (Customization)
这是 shadcn 最强大的地方。因为代码在你手里：
- 修改样式 ：直接打开
components/ui/button.tsx，修改 Tailwind 类名。例如，想把所有按钮的圆角改大，直接改rounded-md为rounded-xl。 - 修改逻辑 ：如果默认的 Dialog 行为不符合需求，直接修改
dialog.tsx里的 Radix UI props 或逻辑。 - 主题切换 ：修改
globals.css中的 CSS 变量（如--primary,--background），即可一键切换深色/浅色模式或品牌色。
进阶技巧
1. 批量更新组件
如果 shadcn 官方修复了某个组件的 Bug 或增加了新功能，你可以运行以下命令来更新本地已有的组件：
npx shadcn@latest add button --overwrite
# 或者更新所有已安装的组件
npx shadcn@latest add --all --overwrite注意：--overwrite 会覆盖你本地的修改，如果你深度定制过某个组件，请谨慎使用或手动合并。
2. 创建自定义变体 (Variants)
shadcn 组件通常使用 class-variance-authority (cva) 来管理变体。你可以在组件文件中轻松添加新的变体。
例如在 button.tsx 中添加一个 "ghost-danger" 变体：
const buttonVariants = cva(
"...",
{
variants: {
variant: {
default: "...",
destructive: "...",
// 新增自定义变体
"ghost-danger": "hover:bg-red-100 hover:text-red-600",
},
// ...
},
}
)然后在使用时：<Button variant="ghost-danger">删除</Button>。
总结
shadcn/ui 的实现本质是：CLI 工具 + 代码生成 + 标准化规范。
- 以前：你依赖一个黑盒 npm 包。
- 现在：你拥有了一套符合最佳实践的、基于 Radix 和 Tailwind 的高质量源代码，并可以将其作为自己设计系统的基石。