Skip to content
← 返回 Research
← 返回 Research

shadcn/ui

shadcn/ui 实用研究 —— v4 新版从环境搭建到基本使用的实操路线。全部内容 基于本机实测（Node v24.16.0 / pnpm 11.25.0 / Vite 8.2.2 / Tailwind CSS v4 / TypeScript 7.0.2 / shadcn CLI 4.20.1，Vite react-ts 模板，macOS arm64）。

本主题是实用研究：不读 shadcn/ui 源码，而是「装起来、用起来、定制起来」。 旧版"源码阅读指南"已清除替换。

Sub Topics

阅读顺序 主题 描述
1 环境与初始化 技术栈定案（pnpm + Vite 8 + Tailwind v4 + TypeScript）、创建项目、接入 Tailwind、init 流程与 components.json 逐字段
2 组件添加与基本使用 add 用法、依赖自动解析、常用组件清单与最小示例、Base UI 新范式（render prop / Field 组合）
3 进阶使用 组件更新（diff/overwrite）、主题定制（oklch 变量/radius/dark）、表单集成（RHF + zod）、registry 机制与框架差异

推荐阅读顺序

  1. 环境与初始化 → 环境与初始化：先把项目跑起来——TypeScript 升级、 Tailwind v4 接入、init 成功，得到 components.json 和 button.tsx
  2. 组件添加与基本使用 → 组件添加与基本使用：add 常用组件、 理解依赖自动解析，把 button/card/dialog/field 用起来
  3. 进阶使用 → 进阶使用：更新组件、主题定制、表单集成、 自定义 registry，以及 Vite 脚手架下的实测要点

版本快照（2026-09-04 实测）

组件 版本 备注
Node v24.16.0 shadcn CLI 要求 Node >= 20.18.1
pnpm 11.25.0 包管理器
Vite 8.2.2 react-ts 模板，rolldown 构建
React 19.2.8
TypeScript 7.0.2 （跟随当前 TypeScript 主版本）
Tailwind CSS 4.3.3 v4 CSS-first，无 tailwind.config.js
shadcn CLI 4.20.1 v4 架构，style=base-nova（固定版本 -D 装入项目）
基元 @base-ui/react 1.7.0 Base UI（非旧版 Radix UI）
工具 cn 0.2.4 cn() 类合并（init 安装，取代 clsx + tailwind-merge）
图标 lucide-react 1.40.0 components.json 的 iconLibrary
动画 tw-animate-css 1.4.0 组件动效（init 写入 index.css）

版本细项与更新基准见 setup.md 第 1 节（两处保持一致）。

实测要点（详细见各篇）

  • init/add 前先装 Tailwind v4 并配好 @/* 别名（paths 用相对写法 "./src/*"），否则 preflight 报 No Tailwind CSS configuration found / Could not find valid path aliases
  • 根 tsconfig.json（solution-style）也要配同样的 paths —— CLI 靠它把 组件写进 src/；只配 tsconfig.app.json 会落到项目根的字面 @/components/ui/
  • v4 的 form registry 项是空 stub，真实表单组件是 field（Base UI Field）
  • Base UI 用 render={<Button/>} 替代 Radix 的 asChild

相关笔记

Backlinks (2) 
flowchart LR
  n0["AI"]
  n1["Database"]
  n2["Dev Tools"]
  n3["Emoji"]
  n4["Frontend"]
  n5["Game Dev"]
  n6["Collection"]
  n7["Languages"]
  n8["Maps"]
  n9["Media"]
  n10["Monitor"]
  n11["Study Materials"]
  n12["Plans"]
  n13["Storage"]
  n14["对象存储基本用法（Bucket / Object / 常用操作）"]
  n15["挂载 Bucket 为本地文件系统（FUSE Mount）"]
  n16["对象存储签名 URL（Signed URL）原理与实战"]
  n17["对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"]
  n18["Prototypes"]
  n19["Research"]
  n20["Better Auth 源码阅读指南"]
  n21["DuckDB 环境与基本使用"]
  n22["DuckDB 实战研究"]
  n23["DuckDB 模拟数据"]
  n24["PostgreSQL 数据用 DuckDB 加速查询"]
  n25["HK 角色阅读"]
  n26["HK 台词阅读"]
  n27["Hollow Knight 英语主题"]
  n28["HK 物品阅读"]
  n29["HK 地点阅读"]
  n30["HK 世界观 / Lore 阅读"]
  n31["英语学习 Dashboard"]
  n32["English Scraps Archive"]
  n33["English Scraps 使用指南"]
  n34["Jellyfin 源码阅读指南"]
  n35["Lux 资料整理"]
  n36["Nest Commander 学习资料"]
  n37["NestJS 源码阅读指南"]
  n38["Protomaps 自建底图研究"]
  n39["自制 PMTiles 地图（最简单例子）"]
  n40["MapLibre 集成 Protomaps"]
  n41["PMTiles 格式与工具链"]
  n42["上海地区底图项目"]
  n43["Redash 源码阅读指南"]
  n44["Rust 学习计划"]
  n45["shadcn/ui 进阶使用"]
  n46["shadcn/ui 组件添加与基本使用"]
  n47["shadcn/ui 实用研究（从环境到基本使用）"]
  n48["shadcn/ui 环境与初始化"]
  n49["TRIP 项目核心原理与代码阅读指南"]
  n1 --> n22
  n1 --> n24
  n4 --> n47
  n6 --> n0
  n6 --> n1
  n6 --> n2
  n6 --> n3
  n6 --> n4
  n6 --> n5
  n6 --> n7
  n6 --> n8
  n6 --> n9
  n6 --> n10
  n6 --> n11
  n6 --> n12
  n6 --> n13
  n6 --> n19
  n14 --> n16
  n14 --> n17
  n14 --> n18
  n15 --> n14
  n15 --> n16
  n15 --> n17
  n16 --> n18
  n17 --> n14
  n17 --> n16
  n17 --> n18
  n18 --> n14
  n18 --> n15
  n18 --> n16
  n18 --> n17
  n18 --> n38
  n19 --> n20
  n19 --> n22
  n19 --> n31
  n19 --> n34
  n19 --> n35
  n19 --> n36
  n19 --> n37
  n19 --> n38
  n19 --> n43
  n19 --> n44
  n19 --> n47
  n19 --> n49
  n21 --> n23
  n22 --> n1
  n22 --> n19
  n22 --> n21
  n22 --> n23
  n22 --> n24
  n23 --> n21
  n23 --> n24
  n24 --> n22
  n24 --> n23
  n27 --> n25
  n27 --> n26
  n27 --> n28
  n27 --> n29
  n27 --> n30
  n27 --> n33
  n31 --> n27
  n31 --> n32
  n31 --> n33
  n33 --> n31
  n33 --> n32
  n38 --> n8
  n38 --> n39
  n38 --> n40
  n38 --> n41
  n38 --> n42
  n39 --> n41
  n40 --> n18
  n40 --> n42
  n41 --> n39
  n41 --> n42
  n42 --> n40
  n42 --> n41
  n45 --> n46
  n46 --> n45
  n46 --> n48
  n47 --> n4
  n47 --> n19
  n47 --> n45
  n47 --> n46
  n47 --> n48
  n48 --> n46
  click n0 "../../../collection/ai/" "AI"
  click n1 "../../../collection/database/" "Database"
  click n2 "../../../collection/dev-tools/" "Dev Tools"
  click n3 "../../../collection/emoji/" "Emoji"
  click n4 "../../../collection/frontend/" "Frontend"
  click n5 "../../../collection/game-dev/" "Game Dev"
  click n6 "../../../collection/" "Collection"
  click n7 "../../../collection/languages/" "Languages"
  click n8 "../../../collection/maps/" "Maps"
  click n9 "../../../collection/media/" "Media"
  click n10 "../../../collection/monitor/" "Monitor"
  click n11 "../../../collection/reading/" "Study Materials"
  click n12 "../../../collection/scraps/plans/" "Plans"
  click n13 "../../../collection/storage/" "Storage"
  click n14 "../../../knowledge/infrastructure/cloud/object-storage/basic-usage/" "对象存储基本用法（Bucket / Object / 常用操作）"
  click n15 "../../../knowledge/infrastructure/cloud/object-storage/mount-bucket/" "挂载 Bucket 为本地文件系统（FUSE Mount）"
  click n16 "../../../knowledge/infrastructure/cloud/object-storage/signed-url/" "对象存储签名 URL（Signed URL）原理与实战"
  click n17 "../../../knowledge/infrastructure/cloud/object-storage/vendors-comparison/" "对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"
  click n18 "../../../prototypes/" "Prototypes"
  click n19 "../../" "Research"
  click n20 "../better-auth/" "Better Auth 源码阅读指南"
  click n21 "../duckdb/basic-usage/" "DuckDB 环境与基本使用"
  click n22 "../duckdb/" "DuckDB 实战研究"
  click n23 "../duckdb/mock-data/" "DuckDB 模拟数据"
  click n24 "../duckdb/postgresql-acceleration/" "PostgreSQL 数据用 DuckDB 加速查询"
  click n25 "../english/hollow-knight/characters/" "HK 角色阅读"
  click n26 "../english/hollow-knight/dialogues/" "HK 台词阅读"
  click n27 "../english/hollow-knight/" "Hollow Knight 英语主题"
  click n28 "../english/hollow-knight/items/" "HK 物品阅读"
  click n29 "../english/hollow-knight/locations/" "HK 地点阅读"
  click n30 "../english/hollow-knight/lore/" "HK 世界观 / Lore 阅读"
  click n31 "../english/" "英语学习 Dashboard"
  click n32 "../english/scraps/archive/" "English Scraps Archive"
  click n33 "../english/scraps/" "English Scraps 使用指南"
  click n34 "../jellyfin/" "Jellyfin 源码阅读指南"
  click n35 "../lux/" "Lux 资料整理"
  click n36 "../nest-commander/" "Nest Commander 学习资料"
  click n37 "../nestjs/" "NestJS 源码阅读指南"
  click n38 "../protomaps/" "Protomaps 自建底图研究"
  click n39 "../protomaps/make-own-map/" "自制 PMTiles 地图（最简单例子）"
  click n40 "../protomaps/maplibre/" "MapLibre 集成 Protomaps"
  click n41 "../protomaps/pmtiles/" "PMTiles 格式与工具链"
  click n42 "../protomaps/shanghai-map/" "上海地区底图项目"
  click n43 "../redash/" "Redash 源码阅读指南"
  click n44 "../rust/" "Rust 学习计划"
  click n45 "advanced/" "shadcn/ui 进阶使用"
  click n46 "components/" "shadcn/ui 组件添加与基本使用"
  click n47 "./" "shadcn/ui 实用研究（从环境到基本使用）"
  click n48 "setup/" "shadcn/ui 环境与初始化"
  click n49 "../trip/" "TRIP 项目核心原理与代码阅读指南"
Links (5)