进阶使用

本页目的： 组件更新（diff/overwrite）、主题定制（oklch 变量）、表单集成（react-hook-form + zod + field）、registry 机制与框架差异。全部基于本机实测（macOS arm64）。

上一篇：组件添加与基本使用。

1. 组件更新与对比

v4 CLI 中旧 shadcn diff 命令已弃用，改为 add --diff：

# 查看本地组件与 registry 的差异（不写盘）
pnpm exec shadcn add button --diff

# 强制覆盖本地版本（源码被改过时用 --overwrite 更新）
pnpm exec shadcn add button --overwrite

# 预览改动再落盘
pnpm exec shadcn add dialog --dry-run

实测 add button --diff：对未生成的组件显示 (create) 计划块并打出完整文件内容；对已存在且一致的组件直接提示 Skipped (files might be identical)。更新思路：先 --diff 看差异 → 小范围自己改 / 大版本用 --overwrite 拉回。

2. 主题定制（CSS-first）

Tailwind v4 + shadcn 的主题全部在 src/index.css（无 tailwind.config.js）：

色板：@theme inline 把语义色映射到 CSS 变量（--color-primary → var(--primary)）；:root / .dark 下定义 oklch 值，如 --primary: oklch(0.205 0 0)（neutral 基色）
圆角：--radius: 0.625rem 派生 --radius-sm/md/lg/xl/2xl/3xl/4xl （各乘系数），改一个 --radius 全局生效
dark 模式：@custom-variant dark (&:is(.dark *)) —— 给根元素加 .dark 类切换；主题切换组件用 next-themes（实测 sonner 场景已安装）
字体：默认 Geist（@fontsource-variable/geist），换 --font-sans / --font-heading 即可
菜单外观：components.json 的 menuColor / menuAccent 控制 sidebar/菜单配色（base-nova 新增字段）

3. 表单集成（react-hook-form + zod）

shadcn v4 表单 = field 组件 + react-hook-form + zod：

pnpm add react-hook-form zod @hookform/resolvers
pnpm exec shadcn add field input label

import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import { z } from "zod"

const schema = z.object({ email: z.string().email() })

// Field 组合子组件承载 RHF 的 register 状态
<form onSubmit={form.handleSubmit((v) => console.log(v))}>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <FieldContent>
      <Input id="email" type="email" {...form.register("email")} />
    </FieldContent>
    {form.formState.errors.email && (
      <FieldError>{form.formState.errors.email.message}</FieldError>
    )}
  </Field>
  <Button type="submit">Submit</Button>
</form>

提示：Base UI Field 自带状态管理，但与 RHF 结合时推荐让 RHF 作为唯一状态源（register + formState.errors 显式传入），避免双状态源打架。

4. registry 机制

4.1 在线 registry 结构（实测抓取）

默认样式 registry URL：https://ui.shadcn.com/r/styles/base-nova/registry.json，顶层结构：

{
  "name": "...",
  "homepage": "...",
  "items": [ ... ]   // 全部可用组件（实测 216 个）
}

每个 item 的关键字段（实测 dialog/field/form）：

字段	含义	实测例子
`name`	组件名	`field`
`dependencies`	npm 依赖	（如 sonner 组件的 sonner 包）
`registryDependencies`	依赖的其他 registry 组件	`field → label, separator`
`files`	组件文件（registry 内路径）	`registry/base-nova/ui/field.tsx`

实测：base-nova registry 中 form 的 files 为空数组（stub，已移除）； field 才是真正表单组件。

4.2 组件检索

search/list 默认不配置 registry 时会提示：

No registries are configured in components.json.
Provide a registry or namespace to search, e.g. shadcn search @shadcn.

显式给命名空间即可（实测）：

pnpm exec shadcn search @shadcn -q dialog -l 5
# → @shadcn/dialog (ui)、@shadcn/dialog-example (example)、@shadcn/sidebar-13 (block) …

registry item 有类型：ui（组件）、example（示例）、block（整块布局，如 sidebar-13 之类）。

4.3 自定义 registry / 私有组件库

components.json 的 registries 字段登记额外 registry（默认 {}）
CLI 自带 build（构建 registry）、registry（管理）、preset、apply 等子命令——可把自写组件发布成私有 registry（本页未实测，保留官方文档指引）

5. 框架差异

维度	Vite（本页实测）	Next.js	Astro
接入	@tailwindcss/vite 插件 + CSS @import	官方有 Next 专用指南（postcss）	有官方指南
`rsc`（components.json）	`false`	`true`（App Router）	—
别名	tsconfig paths + vite resolve.alias	`paths` in tsconfig	类似
组件代码	通用 TSX，无框架特异性	部分组件有 RSC 特定分支	同左

实测 Vite 场景：rsc: false、"use client" directive 仍会出现在组件文件头部（如 dialog.tsx）——对纯客户端 SPA 无害。

6. 参考链接

资源	链接
组件更新	https://ui.shadcn.com/docs/components/updating
主题定制	https://ui.shadcn.com/docs/theming
自定义 registry	https://ui.shadcn.com/docs/registry
Registry spec	https://ui.shadcn.com/docs/registry/spec
Base UI	https://base-ui.com/

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 "./" "shadcn/ui 进阶使用"
  click n46 "../components/" "shadcn/ui 组件添加与基本使用"
  click n47 "../" "shadcn/ui 实用研究（从环境到基本使用）"
  click n48 "../setup/" "shadcn/ui 环境与初始化"
  click n49 "../../trip/" "TRIP 项目核心原理与代码阅读指南"

Links (1)

shadcn/ui 组件添加与基本使用