[Github] shadcn/ui – 可按需复制与改造的 React 组件方案

Github发现2026-09-30发布 WarpEdit

想在 React 项目里做一套能继续改的界面，又不想从按钮、输入框开始逐个设计？shadcn/ui 提供组件示例、注册表与 CLI，让你把选中的组件代码加入自己的项目。它的价值在于交付可读、可改的源码；接入后也要由项目团队维护这些文件。本文从最小接入步骤讲起，再看它适合怎样的产品界面。

shadcn/ui 组件源码按需加入 React 项目的概念封面 — shadcn/ui 项目封面示意：选择组件、加入项目并继续修改源码；画面不是项目实际操作截图。

源码加入项目，意味着什么

shadcn/ui 官网把“Open Code”列为设计原则：组件代码会进入你的项目，你可以改结构、样式和行为，而不必等上游提供某个配置开关。它同时提供组件文档、组合示例与注册表，CLI 则负责初始化配置和按需添加组件。

这里容易误解的是“复制源码”不等于“没有依赖”。官方 CLI 的 init 会配置依赖、cn 工具函数和 CSS 变量；add 也可能加入组件需要的依赖。它改变的是组件源码的归属方式，不是把 React、Tailwind CSS 或相关底层依赖一并抹掉。

先用 Button 跑通一条路径

已有 React 项目先到官网安装页选择自己的框架。以官网当前的 Vite 路径和 pnpm 为例，先确认项目已按该页面完成 React、Tailwind CSS 与路径别名等准备，再在项目根目录运行：

pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest add button

init 用于建立项目配置，add button 只添加所需的 Button。初始化时按提示选择底层组件方案和样式；不同框架与已有配置的具体选项，应以安装页实际显示为准。不要把这两行命令直接用于尚未建立的空目录，并期待它自动替你补齐所有框架前置条件。

完成后，检查项目里是否出现 components.json 和 components/ui/button.tsx（具体路径取决于别名配置），以及 CLI 写入的样式和依赖变更。在页面中导入 Button，渲染一个按钮，再修改本地组件的样式或变体：页面能显示改动，才算确认“代码进入自己的项目”这一点。官网 Button 页面也提供手动安装与用法示例，适合对照生成的文件。

组件能拼到什么程度

Button 只是入口。官方组件目录还列有表单输入、对话框、导航、表格和图表等条目；需要复用页面片段时，还可以查看 Blocks 和示例。应先按当前页面缺的交互选组件，再决定是否借用更大的区块，避免为了一个按钮把整套展示页照搬进项目。

shadcn/ui 官方组件组合示例，包含按钮、输入框、卡片和图表 — 官方仓库中的组件组合展示，演示按钮、输入框、卡片等元素如何并置。

官方展示图把按钮、输入、卡片、图表等元素放在同一界面中，说明这些条目可以共同构成产品页面。但展示图是视觉与组合参考，不说明某个业务流程已接入真实数据。

shadcn/ui 官方仪表盘示例，包含侧栏、指标卡、图表和表格 — 官方仓库中的仪表盘示例；收入和访客数字仅为示例界面内容。

以仓库中的仪表盘示例为例，侧栏、指标卡、图表和表格已经有完整布局。若要用于真实后台，仍需接入自己的数据源、权限与交互逻辑；图片里的收入、访客和增长数字仅是示例界面内容。

改了源码以后如何跟进上游

本地可改是它最鲜明的优点，也改变了更新方式。上游新增变体或修复后，你的已改文件不会因为依赖升级就自动变成新版本。官方 CLI 提供 add --dry-run 预览变更和 add --diff 查看文件差异；需要更新时，先对照上游版本与本地改动，再决定是否覆盖。不要在未检查差异时使用覆盖选项。

团队项目最好在提交记录中保留组件来源和本地改动目的。这样别人看见 components/ui 下的文件时，知道它们是可维护的项目代码，也能判断某次上游调整是否值得合并。