shadcn/ui 上手教程:从初始化到使用
Alex Mercer
- 3 minutes read - 1423 words只要你最近两年写过 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 开始,加个按钮,读一遍它的源码——一个下午,你就能把整套思路装进脑子里。