本文档详细介绍了 components.json 配置文件、其模式以及它如何在添加组件到项目时控制 CLI 行为。该配置文件是 shadcn CLI 理解项目结构、依赖项和组件安装偏好的中心控制点。
有关 CLI 命令及其选项的信息，请参阅 CLI 工具。有关主题配置的特定信息，请参阅 主题和样式。
components.json 文件是 shadcn CLI 工具的主要配置机制。它定义了组件应如何安装、放置在哪里以及如何为特定项目定制。CLI 读取此配置以了解项目结构、依赖项管理和样式偏好。
配置工作流程
来源：apps/www/content/docs/components-json.mdx6-14 apps/www/content/docs/cli.mdx8-11
components.json 文件遵循定义的 JSON 模式，并包含几个控制 CLI 行为不同方面的顶级部分。
核心配置模式
来源：apps/www/content/docs/components-json.mdx24-214
配置文件包含一个 $schema 属性，该属性引用官方 JSON 模式以进行验证和 IDE 支持。
| 属性 | 值 | 目的 |
|---|---|---|
$schema | https://ui.shadcn.org.cn/schema.json | 启用 JSON 模式验证和自动完成 |
来源：apps/www/content/docs/components-json.mdx24-32
style 属性决定了组件的样式变体，在初始化后无法更改。
| 风格 | 状态 | 描述 |
|---|---|---|
new-york | 激活 | 当前推荐样式 |
默认 | 已弃用 | 旧样式，请改用 new-york |
来源：apps/www/content/docs/components-json.mdx34-44
tailwind 部分配置了 CLI 如何与项目中的 Tailwind CSS 集成。
Tailwind 配置结构
来源：apps/www/content/docs/components-json.mdx46-116
cssVariables 设置控制了主题方法，并影响组件如何生成样式代码。
| 模式 | cssVariables | CSS 输出 | 示例 |
|---|---|---|---|
| CSS 变量 | true | 使用 CSS 自定义属性 | bg-background text-foreground |
| 工具类 | false | 使用直接的 Tailwind 类 | bg-zinc-950 dark:bg-white |
来源：apps/www/content/docs/theming.mdx6-64 apps/www/content/docs/components-json.mdx88-104
aliases 部分定义了 CLI 用于将组件放置在正确项目位置的导入路径映射。
别名解析流程
来源：apps/www/content/docs/components-json.mdx142-214
| 别名 | 目的 | 示例值 | 目标用途 |
|---|---|---|---|
utils | 实用函数 | @/lib/utils | cn()，辅助验证函数 |
components | 通用组件 | @/components | 布局，自定义组件 |
ui | UI 组件 | @/app/ui | Button, Input, Dialog |
lib | 库函数 | @/lib | format-date, generate-id |
hooks | 自定义 hooks | @/hooks | use-media-query, use-toast |
来源：apps/www/content/docs/components-json.mdx153-214
rsc 属性控制 CLI 是否向客户端组件添加 use client 指令。
| 值 | 行为 |
|---|---|
true | 自动向客户端组件添加 "use client" |
false | 无 RSC 特定修改 |
来源：apps/www/content/docs/components-json.mdx118-128
tsx 属性决定了生成组件时使用的文件扩展名和语法。
| 值 | 文件扩展名 | 语言 |
|---|---|---|
true | .tsx | TypeScript |
false | .jsx | JavaScript |
来源：apps/www/content/docs/components-json.mdx130-140
CLI 在初始化和添加组件时都会执行配置验证和项目检测。
CLI 配置流程
来源：apps/www/content/docs/components-json.mdx10-14 apps/www/content/docs/cli.mdx8-11
components.json 配置的完整示例，展示了所有主要部分。
来源：apps/www/content/docs/theming.mdx16-35 apps/www/content/docs/components-json.mdx28-214