企业官网建设流程全解析

shadcn/ui CLI 命令深度参考：init、apply、add（dry-run）、search、info、build 全解与源码级说明

【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui

本文基于 shadcn/ui 仓库中面向 AI Agent 的技能参考文档 skills/shadcn/cli.md 编写，系统梳理 shadcn CLI 的全部核心命令（init、apply、add、search、view、docs、info、build）、模板体系与预设（Preset）机制。读完本文，你能准确使用npx shadcn@latest完成项目初始化、组件添加与变更预览（dry-run/diff/view）、注册表搜索、项目诊断和自定义注册表构建，并且知道每个命令在 packages/shadcn 源码中的真实行为依据。

CLI 入口与运行方式

shadcn CLI 的所有配置均从项目根目录的components.json读取。仓库中的真实示例可参考 apps/v4/components.json：

{ "$schema": "https://ui.shadcn.com/schema.json", "style": "new-york", "rsc": true, "tsx": true, "tailwind": { "config": "", "css": "app/globals.css", "baseColor": "neutral", "cssVariables": true, "prefix": "" }, "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/registry/new-york-v4/ui", "lib": "@/lib", "hooks": "@/hooks" }, "iconLibrary": "lucide" }

运行命令时始终应使用项目自身的包管理器执行器：npx shadcn@latest、pnpm dlx shadcn@latest或bunx --bun shadcn@latest，具体选择取决于项目package.json中声明的packageManager。下文的示例统一使用npx shadcn@latest，实际使用时请替换为对应执行器。

从源码结构看，CLI 基于 commander 构建，入口 packages/shadcn/src/index.ts 中注册了 init、apply、add、diff、docs、view、search、migrate、eject、info、build、mcp、preset、registry 等子命令，其中diff、eject等命令在 Agent 工作流文档中未作为常用命令列出。

两个重要使用约束（直接来自技能文档）：

• 只使用文档明确记载的 flag：不要臆造参数。CLI 会自动从项目 lockfile 检测包管理器，不存在--package-manager参数。
• 比较本地组件与上游差异、预览变更时，始终使用npx shadcn@latest add <component> --dry-run、--diff或--view，不要手动从 GitHub 抓取原始文件——CLI 会自动处理注册表解析、文件路径映射和 CSS diff。

init — 初始化或创建项目

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

init用于在已有项目中初始化 shadcn/ui，或在提供--name时创建新项目，并可在同一步骤中安装组件。npx shadcn@latest create是init的别名——这一点在 packages/shadcn/src/commands/init.ts 中可直接确认（.alias("create")）。

源码行为补充。从 packages/shadcn/src/commands/init.ts 的 commander 定义看，上述之外还定义了--base（base, radix, aria三个基础库）、--css-variables/--no-css-variables、--pointer等 flag；技能文档只列出 Agent 场景下常用的子集。几个值得注意的实现细节：

• --defaults的实际展开：defaults分支会把模板补为next、基础库补为base（见 init.ts），并与默认预设nova组合生成 init URL。
• 模板校验：非法模板名会立即报错并退出，同时打印可用模板列表（init.ts）。
• 已有components.json时的处理：未传--force时会交互式询问是否覆盖；选择覆盖后自动置force = true。--reinstall会收集项目已安装的组件并加入本次安装列表以覆盖重写。
• 失败自动回滚：init 在写入前会备份components.json，并注册exit监听器在进程异常退出时恢复备份（init.ts），保证中途失败不会留下损坏的配置。
• monorepo 探测：在 monorepo 根目录执行且未指定--monorepo时，CLI 会提示应在具体的 workspace 中运行（init.ts）；--monorepo与--no-monorepo都未传时，交互式询问。
• base 解析优先级：--baseflag > 预设/URL 中携带的 base > 从已有components.json的style推断 > 交互询问（init.ts）。

apply — 对已有项目应用预设

npx shadcn@latest apply [preset] [options]

apply将预设应用到已有项目，覆盖由预设驱动的配置、字体、CSS 变量以及检测到的 UI 组件。

位置参数[preset]等价于--preset <preset>；两者同时提供时必须一致，否则报错退出——这一校验逻辑可见 packages/shadcn/src/commands/apply.ts 的resolveApplyPreset。若未提供任何 preset，CLI 会引导打开ui.shadcn.com/create的自定义预设构建器，并在给出 preset code 后提示执行shadcn apply --preset <preset>。

源码行为补充。

• 前置条件硬校验：apply只在存在components.json的已有项目中工作；目录为空或找不到配置时，会直接提示先运行shadcn init（apply.ts）。
• 自动保留当前 base：apply会用现有配置的style解析出当前 base（base或radix），并将其注入解析后的 init URL 中（resolveApplyInitUrl，见 apply.ts），即预设切换不会悄悄改变组件基础库。
• 部分应用：从源码结构看，apply还支持--only theme,font参数，允许只应用预设的主题或字体部分而不重装组件（apply.ts），该 flag 未出现在技能文档的 flag 表中，属于源码额外能力。
• monorepo 同步：应用完成后，CLI 会把 style、baseColor、rtl、iconLibrary 等设计设置同步到链接的 workspace 的components.json，失败时整体回滚备份（apply.ts）。

add — 添加组件

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

add接受四种组件来源：组件名、带注册表前缀的名字（如@magicui/shimmer-button）、GitHub item 地址（owner/repo/item）、URL 或本地路径。

Dry-Run 模式

--dry-run用于在写任何文件之前预览add将执行的操作；--diff和--view均隐含--dry-run。这一语义在源码中是一行的判断：packages/shadcn/src/commands/add.ts 中const isDryRun = options.dryRun || options.diff || options.view，随后走dryRunComponents预览分支而不落盘。

完整示例（继承自技能文档）：

# 预览全部变更。 npx shadcn@latest add button --dry-run # 显示所有文件的 diff（最多前 5 个）。 npx shadcn@latest add button --diff # 显示指定文件的 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 # 也支持公开的 GitHub 注册表。 npx shadcn@latest add owner/repo/item --dry-run # CSS diff（查看 globals.css 将发生什么变化）。 npx shadcn@latest add button --diff globals.css

何时使用 dry-run（技能文档给出的判断准则）：

• 用户问“这个会添加哪些文件 / 会改什么”时 — 用--dry-run；
• 覆盖已有组件之前 — 先用--diff预览变更；
• 用户想检查组件源码但不安装时 — 用--view；
• 用户想确认globals.css会经历哪些 CSS 变更时 — 用--diff globals.css；
• 用户要求在安装前审查第三方注册表代码时 — 用--view检查源码。

add --dry-run与view的区别：当用户想预览对自身项目的变更时，优先npx shadcn@latest add --dry-run/--diff/--view。view只显示注册表的原始元数据；add --dry-run则展示在用户项目中真正会发生的事——解析后的文件路径、与现有文件的 diff、CSS 更新。只有当用户想在无项目上下文时浏览注册表信息，才使用view。

其他 add 源码行为：在未初始化（无components.json）的项目中直接add时，CLI 会引导补跑一次 init 流程而不是直接失败（add.ts）；安装registry:style/registry:theme这类会覆盖 CSS 变量与组件的条目时，CLI 会先弹出警告确认（add.ts）；--all会拉取注册表索引并过滤掉当前 base 下不可选/已弃用的组件。

Smart Merge（来自上游的智能合并）

完整的组件更新工作流（先 diff、再逐文件审查、保留本地改动地合并上游更新）见 skills/shadcn/SKILL.md 中的 "Updating Components" 一节。核心思想是：用add <component> --diff对比上游与本地差异，逐文件确认后再执行覆盖式安装，避免丢失本地定制。

search — 搜索注册表

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

跨注册表进行模糊搜索，list是search的别名（源码中.alias("list")，见 packages/shadcn/src/commands/search.ts）。支持命名空间（@acme）、公开的 GitHub 注册表源（owner/repo）以及注册表目录 URL。不传-q时列出全部条目；不传任何注册表时，搜索components.json中配置的所有注册表。

源码行为补充：--type的值会先对照SEARCHABLE_TYPES校验，未知类型会明确报错并打印合法类型列表，而不是静默返回空结果（search.ts）。此外，"搜索所有已配置注册表"模式下单个注册表失败会被容忍并汇总到results.errors（--json模式下机器可读），只有全部注册表都失败时才以非零码退出（search.ts）。

view、docs 与 diff

view — 查看条目详情

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

显示条目信息（含文件内容）。示例：

npx shadcn@latest view @shadcn/button npx shadcn@latest view owner/repo/item

view只输出注册表的原始元数据，适合"无项目上下文的浏览"；需要评估对本地项目的影响时请改用add --dry-run/--diff/--view（见上文）。

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 — 检查更新（不推荐使用）

技能文档明确：不要使用独立的diff命令，改用npx shadcn@latest add --diff——后者能结合项目上下文输出解析后的路径与文件级 diff。

info — 项目信息

npx shadcn@latest info [options]

显示项目信息与components.json配置。在动手改项目前先运行info，以了解项目的框架、别名、Tailwind 版本和解析后的路径。

Project Info 字段：

Components.json 字段：

Links 字段：info的输出还包含一个Links部分，提供组件文档、源码、示例的模板化 URL；需要解析后的具体 URL 时，请使用npx shadcn@latest docs <component>。

build — 构建自定义注册表

npx shadcn@latest build [registry] [options]

将registry.json构建为可分发的独立 JSON 文件。默认输入./registry.json，默认输出./public/r。

本仓库即是一个活例子：apps/v4/registry.json 是注册表源定义，apps/v4/public/r/ 下是构建产物（数百个组件 JSON 文件）。编写规则、include、条目定义、registryDependencies与 GitHub 注册表行为，见 skills/shadcn/registry.md。

模板（Templates）

所有模板都支持通过--monorepoflag 搭建 monorepo 项目。传入该 flag 时，CLI 使用对应的 monorepo 模板目录（如next-monorepo、vite-monorepo）；两者都未传时交互式询问。Laravel 不支持 monorepo 脚手架。

仓库根目录的 templates/ 目录下可以看到真实模板项目：next-app、next-monorepo、vite-app、vite-monorepo、react-router-app、react-router-monorepo、astro-app、astro-monorepo、start-app、start-monorepo，命名与上表的 monorepo 后缀规则一一对应。

预设（Presets）的三种指定方式

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

1. 命名预设：--preset nova或--preset lyra
2. Preset code：--preset a2r6bw（带版本前缀的 base62 字符串，例如a2r6bw或b0）
3. URL：--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."

重要：永远不要试图手动解码、抓取或解析 preset code。Preset code 是不透明的（opaque）——直接传给npx shadcn@latest init --preset <code>，由 CLI 完成解析。对已有项目覆盖预设时用npx shadcn@latest apply --preset <code>。

源码印证：init/apply 均通过 packages/shadcn/src/preset/preset.ts 提供的isPresetCode/decodePreset处理 code（见 init.ts）。一个关键细节是preset code 不编码 base：decodePreset解出的字段缺少 base 时，CLI 会用当前项目/交互结果中的 base 补齐后再生成 init URL（init.ts），这解释了下文"临时目录需显式传--base"的原因。

切换预设的工作流

切换预设前，先询问用户：对已有组件是overwrite、merge还是skip？

• Overwrite / Re-install→npx shadcn@latest apply --preset <code>。用新预设风格覆盖所有检测到的组件文件。适用于用户尚未定制组件的场景。
• Merge→npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行npx shadcn@latest info获取已安装组件列表，再用 SKILL.md 的 smart merge 工作流逐个更新，保留本地改动。适用于用户已定制组件的场景。
• Skip→npx shadcn@latest init --preset <code> --force --no-reinstall。只更新配置与 CSS 变量，现有组件保持不动。

两条硬性约束：预设命令必须始终在用户项目目录内运行；apply只能在存在components.json的已有项目中使用。CLI 会自动从components.json保留当前 base（basevsradix）；如果必须在 scratch/临时目录中运行（例如做--dry-run对比），请显式传--base <current-base>——因为 preset code 本身不编码 base。

命令速查

适用前提：以上命令与 flag 以当前仓库 skills/shadcn/cli.md 技能文档及 packages/shadcn 源码为准；@latest版本能力可能随上游发布演进，重要变更前建议先用--dry-run验证。

【免费下载链接】uiA set of beautifully-designed, accessible components and a code distribution platform. Works with your favorite frameworks. Open Source. Open Code.项目地址: https://gitcode.com/GitHub_Trending/ui/ui