shadcn如何使用

shadcn/ui 是目前最流行的前端 UI 组件库之一，但它的使用方式与传统的 Ant Design 或 MUI 不同。它不是一个 npm 依赖包，而是一个组件代码生成器。

以下是 shadcn/ui 的核心使用流程：

---

1. 初始化项目

首先，你需要在现有的 React 项目（推荐 Next.js, Vite, 或 Remix）中运行初始化命令。这会创建 components.json 配置文件并配置 Tailwind CSS。

npx shadcn@latest init

在执行过程中，它会询问你全局样式文件的位置、是否使用 TypeScript 以及你喜欢的颜色风格。

2. 添加组件

这是 shadcn 最独特的地方：你只下载你需要的组件。例如，如果你想使用按钮（Button），运行：

npx shadcn@latest add button

发生了什么？

• 它不会把代码藏在 node_modules 里。
• 它会直接在你的项目目录下（通常是 components/ui/）生成一个 button.tsx 文件。
• 这意味着： 你拥有这个组件的全部代码，你可以直接修改源代码来满足你的特殊需求。

3. 在代码中使用

像引用普通本地组件一样引入并使用它：

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

export default function Home() {
  return (
    <div>
      <Button variant="outline">点击我</Button>
    </div>
  )
}

---

核心优势与技巧

• 完全控制权： 因为代码在你的目录下，你不需要通过复杂的 theme 配置去覆写样式，直接改 .tsx 文件里的 Tailwind 类名即可。
• 配合 Lucide Icons： shadcn 默认推荐使用 lucide-react 图标库，配合使用效果极佳。
• CLI 自动处理依赖： 当你 add 一个复杂组件（如 Calendar 或 Dialog）时，CLI 会自动帮你安装底层的无样式组件库 Radix UI。

常用命令表

操作	命令
初始化	npx shadcn@latest init
添加组件	npx shadcn@latest add [组件名]
批量添加	npx shadcn@latest add button card input
检查更新	npx shadcn@latest diff

---

建议： 如果你是在做 AI 驱动的项目或复杂的前端架构，shadcn 的这种"源代码交付"模式非常适合集成，因为它能显著减少打包体积并提高自定义上限。

开启一个新的 Next.js 项目

如果准备开启一个新的 Next.js 项目，那是使用 shadcn/ui 的最佳时机，因为 shadcn/ui 本身就是围绕 Next.js 的特性（如 App Router 和 Server Components）进行优化的。

按照以下步骤，你可以快速搭建一个高性能、高颜值的开发环境：

---

第一步：创建 Next.js 项目

首先，使用 Next.js 官方脚手架。确保勾选 Tailwind CSS 和 TypeScript。

npx create-next-app@latest my-app --typescript --tailwind --eslint

第二步：运行 shadcn 初始化

进入项目目录并执行初始化命令。它会自动检测你的 tailwind.config.ts 和路径别名。

cd my-app
npx shadcn@latest init

推荐配置建议：

• Style: 选择 New York (更现代，紧凑)。
• Base color: Slate 或 Zinc 比较百搭。
• CSS variables: 选择 Yes (这样你可以通过修改 CSS 变量轻松换肤)。

第三步：安装基础布局组件

对于一个新项目，我建议先安装这几个高频组件，它们能帮你迅速搭出页面框架：

npx shadcn@latest add button navigation-menu card separator

---

第四步：实战建议（针对 Next.js）

1. 区分服务端与客户端组件

shadcn 的组件通常在顶部带有 "use client"（如果它们包含交互，如 Dropdown）。

• 布局文件 (layout.tsx): 保持为服务端组件。
• 交互部分: 将 shadcn 组件封装在小的客户端组件中，或者直接在需要交互的页面顶部声明。

2. 暗黑模式支持

Next.js 配合 shadcn 实现暗黑模式非常简单。你需要安装 next-themes：

1. 安装：npm install next-themes
2. 创建一个 theme-provider.tsx。
3. 在 layout.tsx 中包裹住 {children}。
4. 运行 npx shadcn@latest add dropdown-menu 来做一个切换按钮。

3. 目录结构预览

初始化完成后，你的项目结构会变成这样：

├── app/
├── components/
│   ├── ui/          <-- 这里放 shadcn 自动生成的代码 (不要手动改，除非要定制)
│   └── main-nav.tsx <-- 这里放你自己组合的业务组件
├── lib/
│   └── utils.ts     <-- 包含重要的 cn() 函数，用于动态合并 Tailwind 类名
├── public/
├── tailwind.config.ts
└── components.json  <-- shadcn 的配置文件

---

进阶：使用 v0.dev (可选但强烈推荐)

既然你用的是 Next.js，强烈建议关注 v0.dev 。

这是 Vercel 开发的 AI 工具。你可以用自然语言描述一个 UI（例如："一个带侧边栏的仪表盘"），它会直接生成基于 shadcn/ui + Tailwind 的代码。你只需要一键复制或使用 npx v0 add 就能把 AI 生成的组件搬进项目。