shadcn/ui

shadcn/ui 不是传统意义上的组件库。

它更像一套“组件代码生成工具”：通过 CLI 把 Button、Dialog、Input 这些组件代码添加到你的项目里。添加完成后，组件文件就在你的项目源码中，可以直接修改。

它解决什么问题

做 React / Next.js 项目时，经常会重复写这些基础 UI：

Button
Input
Dialog
Dropdown
Tabs
Form

如果完全自己写，样式、交互、无障碍细节都要处理；如果使用传统组件库，组件又常常被封装在依赖包里，不太好深度修改。

shadcn/ui 的思路是：直接把一份结构清晰、默认好看的组件源码放进项目，让你既能快速开始，也能自由修改。

它的工作方式

shadcn/ui 的核心不是运行时组件库，而是 CLI。

CLI 主要负责：

初始化项目配置。
生成 components.json。
添加组件源码。
安装组件需要的依赖。

比如执行：

npx shadcn@latest init

会生成类似：

components.json

再执行：

npx shadcn@latest add button

会生成类似：

src/components/ui/button.tsx

之后你在项目里使用的是本地文件：

import { Button } from "@/components/ui/button";

也就是说，运行时并不是从 shadcn/ui 这个包里 import Button，而是从你项目自己的 components/ui/button.tsx 里 import。

运行时依赖

生成后的组件代码会用到一些实际依赖。

常见依赖包括：

@radix-ui/react-slot：让组件可以把样式和行为传给子元素，常用于 asChild。
class-variance-authority：管理组件变体，比如按钮的大小、颜色、样式类型。
clsx：按条件拼接 className。
tailwind-merge：合并 Tailwind class，避免冲突。
lucide-react：常用图标。

所以可以这样理解：

shadcn CLI：负责生成和添加代码。
components.json：记录组件生成配置。
src/components/ui/*：真正存在项目里的组件源码。
@radix-ui/*、class-variance-authority、clsx 等：组件运行时真正用到的依赖。

和普通组件库的区别

普通组件库通常这样用：

import { Button } from "some-ui-library";

组件源码在依赖包里，你主要通过 props、主题配置或覆盖样式来调整。

shadcn/ui 通常这样用：

import { Button } from "@/components/ui/button";

组件源码就在项目里。你可以直接改：

JSX 结构。
Tailwind class。
组件 props。
变体配置。
默认交互。

这也是它最重要的特点：不是安装一套黑盒组件，而是把可维护的组件源码放进项目。

基本使用方式

初始化：

npx shadcn@latest init

按需添加组件：

npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add input

使用组件：

import { Button } from "@/components/ui/button";

export function SaveButton() {
  return <Button>保存</Button>;
}

Demo：添加 Dialog 组件

以 Dialog 弹窗为例，看一下 shadcn/ui 生成组件代码的过程。

1. 执行命令

npx shadcn@latest add dialog

这条命令会做几件事：

检查 components.json 配置。
安装 Dialog 需要的依赖。
生成 Dialog 组件源码。
把组件放到你的 components/ui 目录里。

常见生成文件：

src/components/ui/dialog.tsx

常见新增依赖：

@radix-ui/react-dialog

Dialog 组件内部通常还会用到项目里的工具函数，比如：

import { cn } from "@/lib/utils";

cn 一般是 clsx + tailwind-merge 的封装，用来合并 className。

2. 生成后的组件是什么

生成的 dialog.tsx 大概会导出这些组件：

Dialog
DialogTrigger
DialogContent
DialogHeader
DialogTitle
DialogDescription
DialogFooter
DialogClose

这些组件不是从 shadcn/ui 运行时加载的，而是你项目里的本地源码。

你使用时是这样导入：

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

3. 在页面中使用

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function DeleteUserDialog() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="destructive">删除用户</Button>
      </DialogTrigger>

      <DialogContent>
        <DialogHeader>
          <DialogTitle>确认删除用户？</DialogTitle>
          <DialogDescription>
            删除后数据将无法恢复，请谨慎操作。
          </DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  );
}