shadcn/ui 上手教程：从初始化到使用

只要你最近两年写过 React，大概率绕不开 shadcn/ui。它第一眼看上去平平无奇，用过之后却会悄悄改变你对"组件库"这件事的理解。这篇就讲讲怎么在真实项目里把它跑起来。

它其实不是一个组件库

理解 shadcn/ui，第一件要想明白的事是：它跟你熟悉的那些组件库不一样。它不是一个躺在 node_modules 里、让你 import 一个 <Button> 的大包。当你向它要一个组件时，CLI 会把组件的源码直接复制进你的项目。最后你导入的那个按钮，是你自己的代码：

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

这听起来是个小细节，但恰恰是它的精髓所在。每一行代码都归你。当你需要一个作者从没设想过的变体时，直接改文件就行——不必跟一个封闭的 API 较劲，也不用等上游发版。

准备工作

你需要装好 Node.js，并有一个能放组件的 React 框架。shadcn/ui 支持 Next.js、Vite、TanStack Start、React Router、Astro 和 Laravel。样式基于 Tailwind CSS v4，初始化那一步会帮你配好，不用手动接线。

第一步：初始化

在项目根目录运行 init。注意 CLI 的包名现在就叫 shadcn（早期教程里写的 shadcn-ui 已经改名了；如果你照旧命令敲出来报 “command not found”，原因就在这）。

npx shadcn@latest init

这一步会安装依赖、加上一个用于合并 className 的小工具 cn、配好 CSS 变量，并写入一个 components.json 文件记录你的选择。过程中会问你选一个基础色（neutral、gray、zinc、stone 或 slate）。不想一个个回答，可以用 npx shadcn@latest init -d 走默认配置。

如果你手上还没有项目，CLI 也能用模板直接帮你建一个：

npx shadcn@latest init -t next

第二步：添加组件

接下来按名字把需要的组件拉进来，可以一次写多个：

npx shadcn@latest add button card dialog

每个组件都会以清晰可读的源码形式落到 components/ui/ 目录里。动手之前，建议先预览一下某条命令会写入什么——加上 --dry-run，它只给你看计划，不碰任何文件：

npx shadcn@latest add button --dry-run

第三步：使用

像导入任何本地模块一样导入并渲染它：

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

export default function Page() {
  return (
    <div className="p-8">
      <Button>点我</Button>
      <Button variant="outline">或者这个</Button>
    </div>
  );
}

因为代码就是你的，打开 components/ui/button.tsx 看清楚这些变体到底是怎么定义的，大概只要三十秒。想加个新变体，就在那里加。

主题定制

主题走的是初始化时定义的 CSS 变量，所以换配色通常根本不用动组件文件。除了基础色，较新的版本还提供了预设（preset）——把一整套设计系统（配色、字体、圆角）打包成一个短码。初始化时就能套用：

npx shadcn@latest init --preset nova

你还能选底层用的基础组件库。shadcn/ui 构建在 Radix UI 或 Base UI 之上，用 --base radix 或 --base base 切换，看你更习惯哪套无障碍原语。

几条值得记住的 CLI 命令

CLI 能做的远不止 init 和 add，下面几条很省时间：

• npx shadcn@latest search：跨注册表搜索组件。
• npx shadcn@latest view <组件>：打印源码，让你先读再决定要不要加。
• npx shadcn@latest docs <组件>：拉取文档、示例和 API 链接。
• npx shadcn@latest info：报告当前框架、版本、CSS 变量，以及已安装了哪些组件。

最后这条在你隔了几个月回到老项目、想不起当初配了什么时，特别有用。

小结

用 shadcn/ui，最大的心态转变是从"装一个依赖"变成"添加一份你完全掌控的起始代码"。上手只需要一个项目的时间，之后再看到那种打不开、改不了的组件，反而会觉得别扭。从 init 开始，加个按钮，读一遍它的源码——一个下午，你就能把整套思路装进脑子里。

• React
• Tailwind
• 前端
• Shadcn