## 该技能涵盖什么这项技能使您能够完全设置、构建和管理自定义 shadcn/ui 组件注册表 - 从搭建项目和编写组件，到构建 JSON 输出并指导用户完成托管/部署。当某些内容需要用户手动操作时（例如部署到 Vercel、推送到 GitHub），您将使用“🙋 需要用户操作”块清楚地调用它。 ** ** ## 心理模型 shadcn 注册表很简单： 1. **源组件**位于项目的 `registry/` 文件夹中 2. 列出所有项目及其元数据的 **`registry.json`** 清单 3. **构建步骤**（`npx shadcn build`），读取 `registry.json` 并将每个项目发出一个 JSON 文件到 `public/r/[name].json` 4. **静态文件服务器**（Next.js，任何静态主机）通过 HTTP 提供这些 JSON 文件 5. 用户通过以下方式安装组件：`npx shadcn@latest add https://your-domain.com/r/component-name.json` ** ** ## 步骤 1 — 项目设置 ### 选项 A：从官方模板开始（建议新注册机构使用） npx degit shadcn-ui/registry-template my-registry cd 我的注册表 npm 安装 > 此模板使用 **Next.js + Tailwind v4**。对于 Tailwind v3，请使用 `shadcn-ui/registry-template-v3`。 ### 选项 B：将注册表添加到现有项目安装 shadcn CLI： npm 安装 shadcn@latest # 或 pnpm 添加 shadcn@latest 将构建脚本添加到“package.json”： { “脚本”：{ "registry:build": "shadcn 构建" } } ** ** ## 步骤 2 — 目录结构始终遵循这个结构。样式名称（例如“default”、“new-york”）是任意的 - 选择一个并保持一致：我的注册表/ ├──registry.json ← 清单/入口点 ├── 注册表/ │ └── 默认/ ← 你的风格名称 │ ├── 我的按钮/ │ │ └── my-button.tsx │ ├── 使用计数器/ │ │ └── use-counter.ts │ └── 验证页面/ │ ├── 页.tsx │ └── 登录表单.tsx ├── 公开/ │ └── r/ ← 构建输出（自动生成，请勿编辑） │ ├── 注册表.json │ ├── my-button.json │ └── use-counter.json └── package.json **重要规则：** * 所有注册表源文件必须位于“registry/”下 * 注册表文件内的导入必须使用 `@/registry/...` 路径（构建步骤会转换这些路径） * 切勿手动编辑 `public/r/` 中的文件 - 它们是生成的 ** ** ## 步骤 3 —registry.json（清单）在项目根目录创建 `registry.json`： { "$schema": "https://ui.shadcn.com/schema/registry.json", “名称”：“极限”， "主页": "https://acme.com", “项目”：[ { “名称”：“我的按钮”， “类型”：“注册表：ui”， "title": "我的按钮", "description": "自定义品牌按钮组件。", “registryDependency”：[“按钮”]， “依赖关系”：[“类方差权威”]， “文件”：[ { "path": "registry/default/my-button/my-button.tsx", “类型”：“注册表：组件” } ] } ] } ###registry.json 顶级字段领域|必填|描述 ---|---|--- `$schema` |是的 |始终为“https://ui.shadcn.com/schema/registry.json” `名称` |是的 |您的注册表的短段（无空格） `主页` |是的 |您的注册表或站点的公共 URL `项目` |是的 |注册表项定义数组 ** ** ## 步骤 4 — 注册表项类型 ### 项目级别的`type`（这个项目是什么类型的东西？）类型 |用于 ---|--- `注册表：ui` |原始 UI 组件（按钮、输入等） `注册表：块` |组合的多文件 UI 块（表单、仪表板） `注册表：组件` |独立应用程序级组件 `注册表：挂钩` |反应钩子 `注册表：lib` |实用程序/帮助程序库 `注册表：页面` |整页组件 `注册表：主题` | CSS 变量主题定义 `注册表：样式` |完整的样式定义（扩展或替换 shadcn 默认值） `注册表：项目` |通用/与框架无关的项目（光标规则、配置文件等） `注册表：文件` |任意文件（env、config 等） ### 文件级`type`（这是什么类型的文件？）类型 |用于 ---|--- `注册表：组件` | `.tsx` / `.jsx` React 组件 `注册表：挂钩` |自定义 React 钩子 `注册表：lib` |实用功能 `注册表：页面` | Next.js / 框架页面文件 `注册表：文件` |任何其他文件（env、json、md、光标规则） ** ** ## 步骤 5 — 完整的registry-item.json 参考 `registry.json` 中的每个项目都遵循以下模式： { "$schema": "https://ui.shadcn.com/schema/registry-item.json", “名称”：“你好世界”， “类型”：“注册表：块”， “标题”：“你好世界”， "description": "带有按钮的 hello world 组件。", "author": "你的名字 ", “注册表依赖项”：[ “按钮”， “@acme/其他项目”， “https://example.com/r/remote-dep.json” ], “依赖项”：[“zod@^3.20.0”，“运动”]， “devDependency”：[“tw-animate-css”]， “文件”：[ { "path": "registry/default/hello-world/hello-world.tsx", “类型”：“注册表：组件” }, { "path": "registry/default/hello-world/use-hello-world.ts", “类型”：“注册表：钩子” }, { "path": "registry/default/hello-world/page.tsx", "type": "注册表:页面", “目标”：“应用程序/hello/page.tsx” }, { "path": "registry/default/hello-world/.env.example", “类型”：“注册表：文件”， “目标”：“~/.env.local” } ], “cssVars”：{ “主题”：{ "font-heading": "Poppins，无衬线" }, “光”：{ “品牌”：“20 14.3% 4.1%” }, “黑暗”：{ “品牌”：“20 14.3% 4.1%” } }, “环境变量”：{ "NEXT_PUBLIC_APP_URL": "http://localhost:3000", “我的秘密密钥”：“” }, “文档”：“https://example.com/docs/hello-world”， “类别”：[“表单”，“身份验证”] } **关键规则：** * `target` 仅对于 `registry:page` 和 `registry:file` 类型是必需的（告诉 CLI 在哪里放置文件） * `envVars` 添加到 `.env.local` 中。现有值不会被覆盖。仅用于开发/示例变量，切勿用于生产秘密。 * `registryDependency` 可以是：普通 shadcn 组件名称 (`"button"`)、命名空间名称 (`"@acme/component"`) 或完整 URL (`"https://example.com/r/editor.json"`) * `依赖项` 格式：`"package-name"` 或 `"package-name@version"` (例如 `"zod@^3.20.0"`) ** ** ## 步骤 6 — 编写注册表组件 ### 源文件规则 1. **使用`@/registry/...`路径导入其他注册表项：** // ✅ 正确从“@/registry/default/button/button”导入{ Button } 从“@/lib/utils”导入 { cn } // ❌错误——不要使用相对路径从“../button/button”导入{Button} 2. **使用`@/components/ui/...`导入shadcn/ui原语：** 从“@/components/ui/button”导入{Button} 3. **导出组件及其道具类型：** 导出类型 MyComponentProps = { 标签：字符串变体？：“默认”| “大纲” } 导出函数MyComponent（{标签，变体=“默认”}：MyComponentProps）{ // ... } 4. **支持深色模式** — 使用 Tailwind 的 `dark:` 变体 5. **使用 TypeScript** — 始终包含正确的类型 6. **注册前测试浅色和深色主题** ### 示例：格式良好的注册表组件 //registry/default/metric-card/metric-card.tsx 从“@/lib/utils”导入 { cn } 从“@/components/ui/card”导入{ Card、CardContent、CardHeader、CardTitle } 从“@/components/ui/badge”导入{徽章} 导出类型 MetricCardProps = { 标题：字符串值：字符串|数量趋势？：“上涨”| “向下”| “中立” 类名？：字符串 } 导出函数 MetricCard({ 标题, 值, 趋势 = "neutral", className }: MetricCardProps) { 返回（ <卡类名称={cn("w-full", className)}> <卡片标题> {title} <卡片内容>

{值} {趋势！==“中性”&&（ <徽章变体={趋势===“向上”？ “默认”：“破坏性”}> {趋势===“向上”？ “↑”：“↓”} )}

） } ** ** ## 步骤 7 — 构建注册表 npm 运行注册表：构建 # 或 npx shadcn 构建 **选项：** # 自定义输入清单 npx shadcn 构建 ./path/to/registry.json # 自定义输出目录 npx shadcn build --output ./dist/r # 构建并观察变化 npx shadcn 构建 --watch **这有什么作用：** * 读取 `registry.json` * 解析并转换每个源文件（重写导入路径） * 为每个项目发出`public/r/[name].json`，并内联文件内容 * 发出 `public/r/registry.json` （索引）构建完成后，验证输出： cat public/r/my-button.json # 应包含带有文件内容的完整 JSON ** ** ## 步骤 8 — 本地开发和测试启动开发服务器： npm 运行开发您的注册表现在可以在以下位置找到： * 索引：`http://localhost:3000/r/registry.json` * 项目：`http://localhost:3000/r/[name].json` **从另一个项目本地测试安装：** # 在已初始化 shadcn 的不同项目中 npx shadcn@latest 添加 http://localhost:3000/r/my-button.json ** ** ## 步骤 9 — 命名空间（可选但推荐）命名空间允许用户使用“@yourname/component-name”语法而不是完整的 URL 进行安装。在 **consumer 的 ** `components.json` 中配置： { “注册表”：{ “@acme”：“https://registry.acme.com/r/{name}.json” } } 然后用户可以安装： npx shadcn@latest 添加@acme/my-button npx shadcn@latest 添加 @acme/my-button @acme/metric-card “{name}”占位符会自动替换为组件名称。 ** ** ## 步骤 10 — 身份验证（私人注册表）对于私有/内部注册表，请在消费者端的“components.json”中添加身份验证配置： { “注册表”：{ “@内部”：{ "url": "https://internal.company.com/r/{name}.json", “标题”：{ "授权": "持有者 ${INTERNAL_TOKEN}", “X-API-密钥”：“${API_KEY}” } } } } `${ENV_VAR}` 语法在安装时从用户的环境变量中读取。 **支持的验证方法：** * 不记名令牌（`授权：不记名${TOKEN}`） * API 密钥 (`X-API-Key: ${KEY}`) * 基本身份验证（`授权：基本${BASE64_CREDENTIALS}`） * 查询参数（添加到URL：`https://example.com/r/{name}.json?token=${TOKEN}`） ** ** ## 步骤 11 — 托管和发布 ### 🙋 需要用户操作 — 部署代理可以搭建一切，编写所有代码并构建注册表。但是**您必须自己部署它**。该怎么做： **选项 A：部署到 Vercel（最简单，推荐）** 1. 将您的注册表项目推送到 GitHub 存储库 2. 前往 [vercel.com]() → “添加新项目” 3. 导入您的 GitHub 存储库 4. Vercel 自动检测 Next.js — 只需单击“部署” 5. 您的注册表将位于“https://your-project.vercel.app/r/[name].json” **选项 B：部署到 Netlify** 1.推送到GitHub 2. 转到 [netlify.com]() →“添加新站点”→“从 Git 导入” 3. 设置构建命令：`npm runregistry:build && npm run build` 4.设置发布目录：`out`或`.next`（对于Next.js） 5. 部署 **选项 C：GitHub Pages（仅限静态，无 Next.js SSR）** 1.本地运行`npm runregistry:build` 2. 将 `public/r/` 文件夹复制到您的 GitHub Pages 分支 3. 项目将位于 `https://username.github.io/repo-name/r/[name].json` **选项 D：任何静态主机（Cloudflare Pages、S3 等）** * 本地构建，然后上传`public/r/`目录 * 确保服务器为“.json”文件设置“Content-Type: application/json” * 如果需要，启用 CORS 标头：`Access-Control-Allow-Origin: *` ### 部署后使用您的真实生产 URL 更新 `registry.json`： { “名称”：“极限”， “主页”：“https://your-actual-domain.com” } 重建并重新部署。 ** ** ## 第 12 步 — 在官方登记索引中列出（可选） ### 🙋 需要用户操作 — 提交到 shadcn 索引要出现在“npx shadcn 搜索”结果中： 1. 在 GitHub 上分叉 [shadcn-ui/ui]() 2. 将注册表项添加到 `apps/v4/registry/directory.json` 3. 在存储库中运行 `pnpmregistry:build` 以更新 `registries.json` 4. 打开拉取请求 **验收要求：** * 注册表必须是开源的并且可公开访问 * 必须提供符合注册表架构的有效 JSON * 必须是平面注册表：项目位于“/r/[name].json”，索引位于“/r/registry.json”（或“/registry.json”） ** ** ## 常见模式 ### 模式：多文件块 { "name": "数据表", “类型”：“注册表：块”， "title": "数据表", "description": "功能齐全的可排序、可过滤的数据表。", “registryDependency”：[“表”，“按钮”，“输入”]， “依赖项”：[“@tanstack/react-table”]， “文件”：[ { "path": "registry/default/data-table/data-table.tsx", “类型”：“注册表：组件” }, { "path": "registry/default/data-table/data-table-toolbar.tsx", “类型”：“注册表：组件” }, { "path": "registry/default/data-table/use-data-table.ts", “类型”：“注册表：钩子” }, { “路径”：“注册表/默认/数据表/columns.tsx”， “类型”：“注册表：组件” } ] } ### 模式：带有路线的页面 { "name": "仪表板页面", "type": "注册表:页面", “文件”：[ { "path": "registry/default/dashboard-page/page.tsx", "type": "注册表:页面", “目标”：“应用程序/仪表板/page.tsx” }, { “路径”：“注册表/默认/仪表板页面/组件/stats.tsx”， “类型”：“注册表：组件” } ] } ### 模式：自定义主题 { "name": "品牌主题", “类型”：“注册表：主题”， “cssVars”：{ “主题”：{ "font-heading": "Cal Sans, sans-serif", “半径”：“0.375rem” }, “光”：{ “主要”：“262.1 83.3% 57.8%”， “主要前景”：“210 20% 98%” }, “黑暗”：{ “主要”：“263.4 70% 50.4%”， “主要前景”：“210 20% 98%” } } } ### 模式：通用项（与框架无关，例如游标规则） { "name": "光标规则", “类型”：“注册表：项目”， “文件”：[ { “路径”：“注册表/默认/光标规则/react.mdc”， “类型”：“注册表：文件”， “目标”：“.cursor/rules/react.mdc” } ] } ### 模式：远程依赖另一个自定义注册表 { “名称”：“我的表格”， “类型”：“注册表：块”， “注册表依赖项”：[ “按钮”， “输入”， “https://ui.other-registry.com/r/fancy-select.json” ] } ** ** ## 故障排除问题 |解决方案 ---|--- `public/r/` 输出为空 |确保 `registry.json` `items` 不为空；运行“npx shadcn build” 安装失败并显示“未找到”|验证 URL 可公开访问、返回有效的 JSON、具有正确的 CORS 标头安装后导入路径中断 |确保源文件使用“@/registry/...”而不是相对路径 `registryDependency` 未安装 |使用准确的 shadcn 组件名称（小写连字符：`"button"`、`"data-table"`） CLI 无法检测框架 |向所有文件添加明确的“目标”以使该项目通用版本冲突 |在“依赖项”中固定版本：“zod@^3.20.0” `.env` 变量已设置 | `envVars` 永远不会覆盖现有值 - 这是设计使然 ** ** ## 发布前的清单 * `registry.json` 有 `$schema`、`name` 和 `homepage` * 所有项目都有“名称”、“类型”、“标题”、“描述”和“文件” * 所有“文件”都有“路径”和“类型” * `registry:page` 和 `registry:file` 条目有 `target` * 所有 `registryDependency` 都是正确的（名称或 URL） * 列出所有 npm `依赖项` * 源文件中的导入使用`@/registry/...`路径 * `npx shadcn build` 运行没有错误 * `public/r/[name].json` 文件存在并包含 `files[].content` * 本地安装测试通过：`npx shadcn@latest add http://localhost:3000/r/[name].json` * 部署的URL可访问并返回JSON ** ** ## 官方资源 * 文档： * 开始使用： *registry.json架构： *registry-item.json架构： * 官方模板： * 示例： * 命名空间： * 身份验证：

Shadcn注册中心

包含技能