shadcn/ui 的使用流程与传统组件库（如 Ant Design 或 Material UI）完全不同。它不是通过 import { Button } from 'shadcn-ui' 来使用的，而是将组件的源代码直接复制到你自己的项目中。

以下是 shadcn/ui 的具体使用实现步骤，以 React + Next.js + Tailwind CSS 为例：

第一步：环境准备

在使用之前，你的项目必须满足以下前提条件：

1. 框架：React (推荐 Next.js) 或 Vue (实验性支持)。
2. 样式库：必须安装并配置好 Tailwind CSS。
3. 构建工具：Vite, Next.js, Remix 等。
4. 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）。

执行后发生了什么？

1. 生成了 components.json 配置文件。
2. 在 app/globals.css (Next.js) 或 index.css 中注入了大量的 CSS 变量（用于定义颜色、半径等主题系统）。
3. 安装了必要的依赖（主要是 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)：

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 最强大的地方。因为代码在你手里：

1. 修改样式：直接打开 components/ui/button.tsx，修改 Tailwind 类名。例如，想把所有按钮的圆角改大，直接改 rounded-md 为 rounded-xl。
2. 修改逻辑：如果默认的 Dialog 行为不符合需求，直接修改 dialog.tsx 里的 Radix UI props 或逻辑。
3. 主题切换：修改 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 的高质量源代码，并可以将其作为自己设计系统的基石。