skillhub-098-shadcn/cli.md

shadcn CLI 参考

配置从 components.json 中读取。

重要说明： 始终使用项目的包管理器来运行命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest。从项目上下文中检查 packageManager 以选择正确的命令。以下示例使用 npx shadcn@latest，但请替换为项目对应的正确运行器。

重要说明： 只使用下面列出的标志。不要发明或猜测标志——如果某个标志未在此处列出，则它不存在。CLI 会从项目的锁定文件中自动检测包管理器；没有 --package-manager 标志。

目录

• 命令：init、add（空跑、智能合并）、search、view、docs、info、build
• 模板：next、vite、start、react-router、astro
• 预设：命名、代码、URL 格式与字段
• 切换预设

---

命令

init — 初始化或创建项目

npx shadcn@latest init [components...] [options]

在已有项目中初始化 shadcn/ui，或创建新项目（当提供了 --name 时）。可选地在同一步骤中安装组件。

标志	缩写	描述	默认值
--template <template>	-t	模板（next、start、vite、next-monorepo、react-router）	—
--preset [name]	-p	预设配置（命名、代码或 URL）	—
--yes	-y	跳过确认提示	true
--defaults	-d	使用默认值（--template=next --preset=base-nova）	false
--force	-f	强制覆盖现有配置	false
--cwd <cwd>	-c	工作目录	当前目录
--name <name>	-n	新项目的名称	—
--silent	-s	静默输出	false
--rtl		启用 RTL 支持	—
--reinstall		重新安装现有 UI 组件	false
--monorepo		搭建 monorepo 项目骨架	—
--no-monorepo		跳过 monorepo 提示	—

npx shadcn@latest create 是 npx shadcn@latest init 的别名。

add — 添加组件

重要说明： 要比较本地组件与上游版本或预览更改，请始终使用 npx shadcn@latest add <component> --dry-run、--diff 或 --view。切勿从 GitHub 或其他来源手动获取原始文件。CLI 会自动处理注册表解析、文件路径和 CSS 差异比较。

npx shadcn@latest add [components...] [options]

接受组件名称、注册表前缀名称（@magicui/shimmer-button）、URL 或本地路径。

标志	缩写	描述	默认值
--yes	-y	跳过确认提示	false
--overwrite	-o	覆盖现有文件	false
--cwd <cwd>	-c	工作目录	当前目录
--all	-a	添加所有可用组件	false
--path <path>	-p	组件的目标路径	—
--silent	-s	静默输出	false
--dry-run		预览所有更改但不写入文件	false
--diff [path]		显示差异。不带路径时显示前 5 个文件；带路径时只显示该文件（隐含 --dry-run）	—
--view [path]		显示文件内容。不带路径时显示前 5 个文件；带路径时只显示该文件（隐含 --dry-run）	—

空跑模式

使用 --dry-run 预览 add 命令会做什么，而不实际写入任何文件。--diff 和 --view 都隐含 --dry-run。

# 预览所有更改。
npx shadcn@latest add button --dry-run

# 显示所有文件的差异（前 5 个）。
npx shadcn@latest add button --diff

# 显示特定文件的差异。
npx shadcn@latest add button --diff button.tsx

# 显示所有文件的内容（前 5 个）。
npx shadcn@latest add button --view

# 显示特定文件的完整内容。
npx shadcn@latest add button --view button.tsx

# URL 也同样支持。
npx shadcn@latest add https://api.npoint.io/abc123 --dry-run

# CSS 差异。
npx shadcn@latest add button --diff globals.css

何时使用空跑模式：

• 当用户询问「这会添加哪些文件？」或「这会更改什么？」时——使用 --dry-run。
• 在覆盖现有组件之前——使用 --diff 先预览更改。
• 当用户想在不安装的情况下查看组件源码时——使用 --view。
• 当需要检查 globals.css 会有哪些 CSS 更改时——使用 --diff globals.css。
• 当用户要求在安装前审查或审核第三方注册表代码时——使用 --view 检查源代码。

npx shadcn@latest add --dry-run 与 npx shadcn@latest view： 当用户想要预览更改对其项目的影响时，优先使用 npx shadcn@latest add --dry-run/--diff/--view，而不是 npx shadcn@latest view。npx shadcn@latest view 只显示原始注册表元数据。npx shadcn@latest add --dry-run 则精确显示在用户项目中会发生什么：解析后的文件路径、与现有文件的差异、以及 CSS 更新。只有当用户想在无项目上下文的情况下浏览注册表信息时，才使用 npx shadcn@latest view。

上游智能合并

有关完整的工作流程，请参见 SKILL.md 中的更新组件。

search — 搜索注册表

npx shadcn@latest search <registries...> [options]

跨注册表进行模糊搜索。也支持别名 npx shadcn@latest list。不使用 -q 时列出所有项目。

标志	缩写	描述	默认值
--query <query>	-q	搜索查询	—
--limit <number>	-l	每个注册表的最大项目数	100
--offset <number>	-o	跳过的项目数	0
--cwd <cwd>	-c	工作目录	当前目录

view — 查看项目详情

npx shadcn@latest view <items...> [options]

显示项目信息，包括文件内容。示例：npx shadcn@latest view @shadcn/button。

docs — 获取组件文档 URL

npx shadcn@latest docs <components...> [options]

输出组件文档、示例和 API 参考的解析后 URL。接受一个或多个组件名称。获取这些 URL 以得到实际内容。

npx shadcn@latest docs input button 的输出示例：

base  radix

input
  docs      https://ui.shadcn.com/docs/components/radix/input
  examples  https://raw.githubusercontent.com/.../examples/input-example.tsx

button
  docs      https://ui.shadcn.com/docs/components/radix/button
  examples  https://raw.githubusercontent.com/.../examples/button-example.tsx

某些组件包含指向底层库的 api 链接（例如 command 组件指向 cmdk）。

diff — 检查更新

不要使用此命令。请改用 npx shadcn@latest add --diff。

info — 项目信息

npx shadcn@latest info [options]

显示项目信息和 components.json 配置。首先运行此命令以发现项目的框架、别名、Tailwind 版本和解析路径。

标志	缩写	描述	默认值
--cwd <cwd>	-c	工作目录	当前目录

项目信息字段：

字段	类型	含义
framework	string	检测到的框架（next、vite、react-router、start 等）
frameworkVersion	string	框架版本（例如 15.2.4）
isSrcDir	boolean	项目是否使用 src/ 目录
isRSC	boolean	是否启用了 React Server Components
isTsx	boolean	项目是否使用 TypeScript
tailwindVersion	string	"v3" 或 "v4"
tailwindConfigFile	string	Tailwind 配置文件路径
tailwindCssFile	string	全局 CSS 文件路径
aliasPrefix	string	导入别名前缀（例如 @、~、@/）
packageManager	string	检测到的包管理器（npm、pnpm、yarn、bun）

Components.json 字段：

字段	类型	含义
base	string	基础库（radix 或 base）——决定组件 API 和可用属性
style	string	视觉风格（例如 nova、vega）
rsc	boolean	来自配置的 RSC 标志
tsx	boolean	TypeScript 标志
tailwind.config	string	Tailwind 配置路径
tailwind.css	string	全局 CSS 路径——这是放置自定义 CSS 变量的位置
iconLibrary	string	图标库——决定图标导入包（例如 lucide-react、@tabler/icons-react）
aliases.components	string	组件导入别名（例如 @/components）
aliases.utils	string	工具导入别名（例如 @/lib/utils）
aliases.ui	string	UI 组件别名（例如 @/components/ui）
aliases.lib	string	Lib 别名（例如 @/lib）
aliases.hooks	string	Hooks 别名（例如 @/hooks）
resolvedPaths	object	每个别名的绝对文件系统路径
registries	object	配置的自定义注册表

链接字段：

info 输出包含一个链接部分，其中包含组件文档、源代码和示例的模板化 URL。对于解析后的 URL，请改用 npx shadcn@latest docs <component>。

build — 构建自定义注册表

npx shadcn@latest build [registry] [options]

将 registry.json 构建为单个 JSON 文件以进行分发。默认输入：./registry.json，默认输出：./public/r。

标志	缩写	描述	默认值
--output <path>	-o	输出目录	./public/r
--cwd <cwd>	-c	工作目录	当前目录

---

模板

值	框架	支持 Monorepo
next	Next.js	是
vite	Vite	是
start	TanStack Start	是
react-router	React Router	是
astro	Astro	是
laravel	Laravel	否

所有模板均通过 --monorepo 标志支持 monorepo 脚手架。当传入该标志时，CLI 使用 monorepo 专用的模板目录（例如 next-monorepo、vite-monorepo）。当既不传递 --monorepo 也不传递 --no-monorepo 时，CLI 会交互式地提示。Laravel 不支持 monorepo 脚手架。

---

预设

通过 --preset 指定预设的三种方式：

1. 命名： --preset base-nova 或 --preset radix-nova
2. 代码： --preset a2r6bw（base62 字符串，以小写字母 a 开头）
3. URL： --preset "https://ui.shadcn.com/init?base=radix&style=nova&..."

重要说明： 切勿尝试手动解码、获取或解析预设代码。预设代码是不透明的——直接将它们传给 npx shadcn@latest init --preset <code>，让 CLI 处理解析。

切换预设

先询问用户：重新安装、合并还是跳过现有组件？

• 重新安装 → npx shadcn@latest init --preset <code> --force --reinstall。用新的预设样式覆盖所有组件文件。在用户未自定义过组件时使用。
• 合并 → npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 获取已安装组件列表，并使用智能合并工作流程逐一更新它们，同时保留本地更改。在用户已自定义过组件时使用。
• 跳过 → npx shadcn@latest init --preset <code> --force --no-reinstall。仅更新配置和 CSS 变量，保持现有组件不变。