# 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` — 初始化或创建项目

```bash
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 差异比较。

```bash
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`。

```bash
# 预览所有更改。
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 中的更新组件](./SKILL.md#updating-components)。

### `search` — 搜索注册表

```bash
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` — 查看项目详情

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

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

### `docs` — 获取组件文档 URL

```bash
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` — 项目信息

```bash
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` — 构建自定义注册表

```bash
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` 获取已安装组件列表，并使用[智能合并工作流程](./SKILL.md#updating-components)逐一更新它们，同时保留本地更改。在用户已自定义过组件时使用。
- **跳过** → `npx shadcn@latest init --preset <code> --force --no-reinstall`。仅更新配置和 CSS 变量，保持现有组件不变。