开发工具精选项目

shadcn/ui

把可访问、可组合的组件源码直接加入项目，由团队完整拥有和定制的 UI 分发平台。

GitHub 访问官网

主要语言TypeScript

开源许可MIT

项目类型开发工具

维护状态活跃维护

OVERVIEW

项目概述

shadcn/ui 不是传统的 npm 组件库，而是一套开放代码、组件注册表与命令行工具。开发者把需要的组件源码复制到自己的 React 项目中，再根据产品与设计系统自由修改。

shadcn/ui 以“Open Code”为核心：组件不是隐藏在依赖包内部，而是通过 CLI 或 Registry 安装为项目中的普通源码。它提供经过设计的默认外观、Tailwind CSS 主题体系和可访问性基础，同时允许团队选择 Base UI、Radix 或 React Aria 作为底层组件原语。当前新项目默认采用 Base UI，Radix 仍被完整支持且未弃用。

分发方式开放源码 + Registry

当前 CLIshadcn 4.16.0

主要技术React + Tailwind CSS

FEATURES

主要特点

shadcn/ui 把设计默认值、可访问性原语和源码所有权结合在一起。

开放代码与源码所有权

组件会进入项目的 components 目录，可以直接阅读、调试和修改，不必绕过第三方包的样式覆盖层或等待上游提供扩展点。

多种可访问性原语

可选择 Base UI、Radix 或 React Aria 作为组件基础。新项目默认使用 Base UI，已有 Radix 项目仍可继续维护。

Tailwind CSS 主题体系

通过 CSS 变量、语义化颜色和 Tailwind 工具类组织主题；当前方案支持 Tailwind CSS v4、OKLCH 颜色与深浅模式。

CLI 工作流

init、add、info、view、diff、dry-run 等命令覆盖初始化、安装、检查和更新，让组件变更在写入前可被审阅。

Registry 分发协议

官方与自定义 Registry 都能分发组件、依赖、样式、Hook 和配置，适合团队沉淀内部设计系统或跨项目共享模块。

样式与预设

提供多种视觉风格、基础色、图标库、字体和圆角组合，先建立一致默认值，再继续做品牌化设计。

完整组件与 Blocks

覆盖表单、对话框、导航、数据表格、图表、侧栏等常用界面，并提供更接近真实页面结构的 Blocks。

面向 AI 的开放结构

组件源码、Registry Schema、CLI、Skills 与 MCP 能力让编码代理更容易理解项目约定、查找组件并生成可继续维护的代码。

USE CASES

适用场景

当团队希望快速获得高质量组件，又不想被传统组件库的封装边界限制时，它尤其合适。

SaaS 与管理后台

表单、弹窗、菜单、表格和图表等常见能力齐全，适合快速搭建数据密集型产品界面。

Next.js 应用

与 React、Tailwind CSS 和服务端组件工作流配合自然，是 Next.js 产品常见的界面基础。

Vite React 项目

CLI 可直接初始化 Vite 模板，适合 SPA、内部工具和不需要完整全栈框架的交互应用。

品牌化设计系统

团队可以从可靠默认值出发，修改组件结构、交互与样式，逐步形成完全属于产品的组件系统。

Monorepo 与内部组件注册表

通过 Registry 和别名约定，在多个应用之间分发团队组件、依赖和设计令牌。

AI 辅助界面开发

开放源码和结构化 Registry 便于 AI 工具查阅实际实现、复用现有组件并生成符合项目规范的页面。

EVALUATION

优点与注意事项

技术选型不仅要看能力，也要理解它带来的团队成本。

主要优点

shadcn/ui 擅长的地方

组件源码归项目所有，调试、定制和重构没有黑盒边界。
以成熟的可访问性原语处理键盘交互、焦点和弹层等复杂基础行为。
默认视觉质量高，又能通过 Tailwind CSS 与 CSS 变量深度品牌化。
按需安装组件，不必引入整套组件库和未使用的功能。
CLI、Registry 与组件 Schema 适合构建可复用的团队分发流程。
Base UI、Radix 和 React Aria 三种基础选择覆盖不同的技术偏好。
代码结构清晰，便于团队学习组件实现并进行应用级测试。

需要注意

采用前应考虑的问题

团队需要承担组件维护

复制源码意味着上游修复不会像依赖升级一样自动进入项目。团队需要跟踪重要变更，并决定是否手动合并。

覆盖命令可能丢失定制

对已修改组件使用 add --overwrite 会重写文件。执行前应提交代码，并先查看 --dry-run 或 --diff 的结果。

主要面向 React 生态

它不是跨框架的运行时组件库。Vue、Svelte 等项目应选择各自生态的实现或经过验证的社区移植版本。

依赖 Tailwind 工作方式

大量样式由工具类和 CSS 变量表达；如果团队不接受 Tailwind 或希望样式与组件完全分离，维护体验可能不理想。

底层 Base 选择需要统一

Base UI、Radix 和 React Aria 的 API 与行为细节不同。项目启动时应明确选择，不要在缺少规范时随意混用。

多项目容易产生分叉

各应用独立修改复制后的组件，时间久了可能出现行为与视觉不一致。多应用团队应建立内部 Registry、版本和变更流程。

仍需做应用级可访问性测试

底层原语只能覆盖一部分问题。表单标签、错误反馈、内容语义、颜色对比和完整键盘流程仍需团队验证。

安装第三方 Registry 前要审查来源

Registry 项可以写入源码并声明依赖。应只使用可信地址，在安装前查看文件、依赖和变更范围。

QUICK START

快速开始

下面以现有 React 项目为例，初始化配置、安装组件并组成一个最小登录卡片。

1创建 React + TypeScript 项目

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

2初始化 shadcn/ui

bash

npx shadcn@latest init --base base

3按需添加组件

bash

npx shadcn@latest add button card input label

4组合一个登录卡片

tsx

import { Button } from "@/components/ui/button"
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function LoginCard() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>登录账户</CardTitle>
        <CardDescription>输入邮箱和密码继续。</CardDescription>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="space-y-2">
          <Label htmlFor="email">邮箱</Label>
          <Input id="email" type="email" autoComplete="email" />
        </div>
        <div className="space-y-2">
          <Label htmlFor="password">密码</Label>
          <Input id="password" type="password" autoComplete="current-password" />
        </div>
      </CardContent>
      <CardFooter>
        <Button className="w-full">登录</Button>
      </CardFooter>
    </Card>
  )
}

5在写入前检查变更

bash

npx shadcn@latest add dialog --dry-run
npx shadcn@latest add dialog --diff
npx shadcn@latest info

6配置组件路径与主题

json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "css": "src/index.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

7启动开发服务器

bash

npm run dev

下一步：组件安装后就是项目源码。修改前先确认底层 Base 选择与别名配置；更新已有组件时优先使用 --dry-run 和 --diff，并在覆盖前提交代码。

ALTERNATIVES

类似项目

这些站内项目组成 shadcn/ui 最常见的技术栈；底层原语方案则列为外部参考。

Tailwind CSS

以实用类为核心的 CSS 框架，快速构建定制化界面。

查看项目

React

用于构建 Web 和原生用户界面的组件化 JavaScript 库。

查看项目

Next.js

基于 React 的全栈 Web 框架，覆盖渲染、路由和部署。

查看项目

daisyUI

基于 Tailwind CSS 的纯 CSS 组件库，以语义化类名、丰富组件和多主题系统加速界面开发。

查看项目

Radix UI

无样式、可访问且高度可组合的 React UI 原语，为设计系统处理焦点、键盘和复杂交互。

查看项目

Magic UI

面向 React 与 Tailwind CSS 的开源动画组件集合，通过 shadcn Registry 将可编辑源码复制到项目中。

查看项目

Aceternity UI

面向 React、Next.js、Tailwind CSS 与 Motion 的动画组件和页面素材集合，通过 shadcn Registry 复制源码。

查看项目

React Bits

面向 React 的动画、背景、文字效果与交互组件集合，提供 JavaScript、TypeScript、CSS 和 Tailwind 源码变体。

查看项目

TweakCN

面向 shadcn/ui 与 Tailwind CSS 的可视化主题编辑器，可实时调整设计令牌并导出 CSS 或 Registry 命令。

查看项目

Iconify

统一访问 200 多个开源图标集和 30 万多个 SVG 图标的生态系统，支持组件、CSS、API、设计插件与自托管。

查看项目

Lucide

由社区维护的统一线性 SVG 图标库，提供 1,600 多个图标、Tree Shaking 和多框架组件包。

查看项目

Base UI

无样式、可访问的 React 组件库，也是 shadcn/ui 新项目当前默认的底层原语。

访问官网

React Aria

Adobe 提供的可访问 React Hook 与组件体系，现已成为 shadcn/ui 的一等基础选项。

访问官网

COMPARISON

shadcn/ui vs Material UI

shadcn/ui 与 Material UI 都能提供成熟的 React 组件，但前者分发开放源码，后者主要通过版本化 npm 包提供完整组件库。

比较维度	shadcn/ui	Material UI
核心模式	把组件源码复制进项目并由团队拥有	安装并使用版本化的组件依赖包
默认设计	中性、现代，便于继续塑造品牌视觉	以 Material Design 体系为基础，规范更完整
样式方案	Tailwind CSS、CSS 变量与语义化令牌	主题系统、sx 属性及 CSS-in-JS / Pigment CSS
定制边界	可直接修改组件结构、行为和样式源码	优先通过 Props、主题和覆盖 API 扩展
升级方式	审阅差异后手动合并或覆盖组件文件	升级 npm 版本并处理发布说明和破坏性变更
组件一致性	自由度高，需要团队自行治理分叉	库本身集中维护，跨项目更容易保持一致
按需能力	只安装所需组件及其源码	从组件包按模块导入并依赖其运行时实现
更适合	重视源码控制、定制设计和 Tailwind 工作流	希望完整组件体系、统一 API 和集中升级