本文档涵盖了 shadcn/ui 系统本身的贡献者开发工作流程，重点介绍了 CLI 如何检测和管理不同的项目类型、处理依赖安装以及在开发和分发过程中处理组件文件。
有关作为最终用户使用 CLI 工具的信息，请参阅 CLI 工具。有关构建和发布系统的详细信息，请参阅 构建和发布。
shadcn/ui CLI 包含复杂的项目检测功能，可自动识别框架类型、项目结构和配置设置。这使得 CLI 能够提供适当的默认值并处理特定于框架的要求。
项目检测系统会分析目标目录以确定框架和项目特性。
来源：packages/shadcn/src/utils/get-project-info.ts42-151 packages/shadcn/src/utils/frameworks.ts1-85
getProjectInfo 函数收集有关目标项目的全面信息。
| 属性 | 检测方法 | 目的 |
|---|---|---|
框架 | 配置文件模式和依赖项 | 特定于框架的文件处理 |
isSrcDir | fs.pathExists("src") | 目录结构检测 |
isRSC | App 目录存在（Next.js） | React Server Components 支持 |
isTsx | isTypeScriptProject() | TypeScript 与 JavaScript 的处理 |
tailwindConfigFile | fg.glob("tailwind.config.*") | Tailwind 配置位置 |
tailwindCssFile | CSS 文件内容扫描 | Tailwind 导入检测 |
tailwindVersion | 包版本分析 | v3 与 v4 的兼容性 |
aliasPrefix | TypeScript 配置解析 | 导入别名配置 |
来源：packages/shadcn/src/utils/get-project-info.ts15-26 packages/shadcn/src/utils/get-project-info.ts42-68
系统检测 Tailwind CSS 版本以处理兼容性差异。
来源：packages/shadcn/src/utils/get-project-info.ts153-184
依赖管理系统处理包安装，并特别考虑 React 19 的兼容性以及不同的包管理器。
updateDependencies 函数负责完整的依赖安装工作流程。
来源：packages/shadcn/src/utils/updaters/update-dependencies.ts10-99
系统为 React 19 对等依赖冲突提供了特殊处理。
| 包管理器 | React 19 行为 | flag 处理 |
|---|---|---|
npm | 显示 ERESOLVE 错误 | 提示使用 --force 或 --legacy-peer-deps |
pnpm | 仅显示警告 | 无需 flag |
bun | 仅显示警告 | 无需 flag |
yarn | 仅显示警告 | 无需 flag |
deno | 使用 npm: 前缀 | 无需 flag |
React 19 检测使用正则表达式对 package.json 依赖进行匹配。
来源：packages/shadcn/src/utils/updaters/update-dependencies.ts101-109 apps/www/content/docs/react-19.mdx19-175
文件处理系统处理组件安装、导入解析和代码转换，以匹配项目配置。
来源：packages/shadcn/src/utils/updaters/update-files.ts23-235
导入转换系统处理别名解析和注册表导入。
来源：packages/shadcn/src/utils/transformers/transform-import.ts4-104
resolveFilePath 函数根据注册表类型和项目结构确定文件安装位置。
| 注册表类型 | 目标目录解析 |
|---|---|
registry:ui | config.resolvedPaths.ui |
registry:lib | config.resolvedPaths.lib |
registry:component | config.resolvedPaths.components |
registry:block | config.resolvedPaths.components |
registry:hook | config.resolvedPaths.hooks |
registry:page | 特定于框架的页面目录 |
来源：packages/shadcn/src/utils/updaters/update-files.ts237-292
系统为不同的项目类型和页面路由模式提供了特定于框架的处理。
对于 registry:page 类型，系统会根据目标框架转换路径。
路径转换示例
| 框架 | 输入路径 | 输出路径 |
|---|---|---|
next-app | app/login/page.tsx | app/login/page.tsx |
next-pages | app/login/page.tsx | pages/login.tsx |
react-router | app/login/page.tsx | app/routes/login.tsx |
laravel | app/login/page.tsx | resources/js/pages/login.tsx |
来源：packages/shadcn/src/utils/updaters/update-files.ts357-391
getProjectConfig 函数根据检测到的项目特性生成适当的配置。
来源：packages/shadcn/src/utils/get-project-info.ts316-336
开发工作流程包括对文件操作、依赖管理和导入解析进行全面测试。
| 测试套件 | 重点领域 | 关键测试用例 |
|---|---|---|
update-files.test.ts | 文件路径解析 | 目标解析、框架处理、嵌套路径 |
update-dependencies.test.ts | 依赖安装 | 包管理器检测、React 19 flag、去重 |
| 项目 fixture | 框架检测 | 各种项目类型和配置 |
测试 fixture 包括不同包管理器和 React 版本的示例。
project-npm/ - 标准 npm 项目project-npm-react19/ - 带有 React 19 的 npm，用于测试对等依赖处理project-deno/ - Deno 项目配置project-bun/ - Bun 包管理器project-pnpm/ - pnpm 工作区来源：packages/shadcn/test/utils/updaters/update-files.test.ts1-1112 packages/shadcn/test/utils/updaters/update-dependencies.test.ts1-139
resolveModuleByProbablePath 函数包含对导入解析边缘情况的广泛测试。
来源：packages/shadcn/test/utils/updaters/update-files.test.ts816-916 packages/shadcn/src/utils/updaters/update-files.ts493-563