企业官网建设流程全解析

本篇指南完整讲解 open-slide 仓库内嵌 Agent 技能（.agents/skills/shadcn/registry.md）所定义的 shadcn Registry 编写规范：包括 source/built 两种形态、根级registry.json、include拆分、Item 定义、registryDependencies依赖寻址、五类地址方案、GitHub Registry 的消费与构建验证流程。读完你可以独立创建一个可被npx shadcn@latest直接安装、搜索与验证的组件/区块/工具库注册表，并理解 CLI 消费注册表的底层规则。

核心心智模型：source registry 与 built registry

一个 shadcn registry 有两种形态，这是理解后续一切规则的前提：

• Source registry（源码注册表）：项目或仓库中以真实文件形式编写的registry.json，允许使用include和指向源文件的路径，是人类直接编写与维护的形态。
• Built registry（构建注册表）：由 CLI 生成、专门面向 CLI 消费方的 JSON 文件集合，通常输出到public/r目录，通过npx shadcn@latest build从源码注册表生成。

CLI 安装器（add等命令）消费的是registry item payload（条目载荷），而 source registry 的意义在于：让你从真实文件出发、以可读可维护的方式编写这些载荷，而不是手写散落的 JSON。

一个重要认知：registry 条目并不局限于 React 组件。它可以分发组件、hooks、工具函数、设计令牌（design tokens）、页面、配置文件、文档、规则、工作流、模板、MCP 文件以及其他项目文件。这意味着 registry 是一种通用的"包分发"机制，而 shadcn 只是最典型的消费场景。

根级registry.json：元数据与 items/include 二选一

根注册表文件必须定义注册表元数据，并在items与include中二选一（也可同时存在，但至少要有一个）：

{ "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "items": [ { "name": "absolute-url", "type": "registry:lib", "title": "Absolute URL", "description": "A utility to turn any path into an absolute URL.", "files": [ { "path": "lib/absolute-url.ts", "type": "registry:lib" } ] } ] }

根级规则：

• 根registry.json必须包含name与homepage；
• items是 registry item 定义的数组；
• include可用于把 source registry 拆分成多个文件；
• 被 include 的注册表文件可以省略name和homepage（它们只出现在根文件）。

注意files中每个文件条目都带有自己的type，与 item 的type可以不同，这允许一个 item 混合分发 UI 组件与 lib 工具。

用include拆分大型注册表

当注册表条目较多时，include是保持模块化的标准手段。根文件只声明元数据和拆分入口：

{ "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "include": ["registry/ui/registry.json", "registry/blocks/registry.json"] }

include 规则：

• include 路径相对声明它的registry.json解析；
• include 路径必须显式指向一个registry.json文件；
• 禁止远程 URL、绝对路径和父目录回溯（..）；
• item 文件路径相对声明该 item 的 registry 文件解析；
• 整个解析后的注册表中，item 名重复会导致失败（全局唯一约束）。

被 include 的文件示例（放在registry/ui/registry.json）：

{ "items": [ { "name": "button", "type": "registry:ui", "files": [ { "path": "button.tsx", "type": "registry:ui" } ] } ] }

路径解析规则的关键在于"相对声明处解析"：如果该文件位于registry/ui/registry.json，则button.tsx从registry/ui/button.tsx读取，而构建产物中的 item 路径以根注册表为基准重新计算后输出。这种设计让子目录可以自由组织源码，同时保证对外地址始终一致。

Item 定义：字段速查与文件规则

一个典型 item（区块级）的定义：

{ "name": "login-form", "type": "registry:block", "title": "Login Form", "description": "A login form with email and password fields.", "dependencies": ["zod"], "registryDependencies": ["button", "input", "label"], "files": [ { "path": "blocks/login-form.tsx", "type": "registry:block" } ], "cssVars": { "light": { "brand": "oklch(0.62 0.18 250)" }, "dark": { "brand": "oklch(0.72 0.16 250)" } } }

重要字段说明：

• name：可安装的条目名，不一定是文件路径；
• type：registry item 类型之一，包括registry:ui、registry:block、registry:lib、registry:hook、registry:file、registry:page、registry:theme、registry:style、registry:font、registry:item；
• files：条目复制或生成的源文件列表；
• dependencies：npm 运行时依赖；
• devDependencies：npm 开发依赖；
• registryDependencies：本条目依赖的其他 registry 条目；
• cssVars、css、tailwind、envVars、docs：可选的安装时附加内容。

文件规则：

• 文件路径相对声明它的registry.json解析；
• registry:file与registry:page类型的文件必须指定target（写入目标位置）；
• source registry 的文件路径中禁止使用远程文件 URL；
• 保持源文件"可复制粘贴"：不要包含隐藏的仅应用内可用的 import——因为安装者会把文件原样拷入自己的项目，任何依赖私有路径的 import 都会破坏可安装性。

cssVars使用 OKLCH 颜色表示（oklch(0.62 0.18 250)中的三个值是亮度 0–1、彩度、色相），这与 shadcn 主题体系一致：组件引用语义化 CSS 变量令牌，改变变量即改变所有组件。open-slide 仓库内的 customization.md 对--primary、--brand等变量的 light/dark 定义方式有完整展开。

registryDependencies：依赖是条目地址，不是文件路径

registryDependencies中的每一项都是条目地址（item address），而不是文件路径：

{ "name": "login-form", "type": "registry:block", "registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"], "files": [ { "path": "blocks/login-form.tsx", "type": "registry:block" } ] }

依赖规则：

• 裸名称（如"button"）表示shadcn 官方条目；
• 裸名称绝不表示同注册表或同仓库内的条目——想依赖自己的条目必须用带命名空间或 GitHub 形式的完整地址；
• 命名空间依赖使用@namespace/item-name；
• GitHub 依赖使用owner/repo/item-name；
• 需要固定版本时用owner/repo/item-name#ref钉住；
• ref 不会继承：如果owner/repo/foo#v2依赖同一仓库v2下的bar，必须显式写owner/repo/bar#v2，而不是裸"bar"；
• 禁止相对依赖（如"./bar"）。

这条"ref 不继承"规则是依赖解析中最容易踩坑的点：任何依赖声明都必须自带完整地址语义，解析器不做上下文推断。

地址方案：先分类，再解析

面对任意 registry item 字符串，第一步永远是判断它属于哪种地址方案。官方给出了完整的分类表：

两个关键解析规则：

• namespace 与 GitHub 地址允许带斜杠的条目名，且它们就是条目名，不是文件路径；
• 以.json结尾的地址保留文件地址优先权：因此acme/ui/data/schema.json会被当作文件路径，而不是 GitHub 条目地址。

这一点决定了地址解析器必须区分"条目名含斜杠"与"文件路径"两种形态，.json后缀是天然的消歧信号。

GitHub Registries：公共仓库即注册表

一个公共 GitHub 仓库只要拥有根级registry.json，就可以直接作为 source registry 使用，地址形式为：

owner/repo/item-name[#ref]

规则：

• 前两段路径段是 GitHub owner 与 repo；
• 其余路径段全部是 registry item 名；
• 源码入口永远是根registry.json；
• GitHub registry 是 source registry，由 CLI 直接消费，不需要shadcn build或生成的 item JSON 文件；
• include遵循与本地注册表相同的 source-registry 规则；
• 目前仅支持github.com上的公共仓库；私有仓库和 GitHub Enterprise 需要明确的产品决策（即当前 CLI 不支持）。

实现层面的关键约束（文档明确给出）：在读取源文件前，必须先把 ref 解析为 commit SHA。不能直接从raw.githubusercontent.com读取移动中的 ref（分支），因为类似分支的 ref 可能被缓存数分钟，导致同一命令在不同快照间不一致。

推荐流程：

owner/repo[#ref] -> resolve ref with git ls-remote -> commit SHA -> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json -> read includes and item files from the same SHA

这样一条命令始终工作在同一个仓库快照上：

• 完整的 40 位 commit SHA 本身已稳定，可直接使用；
• 分支、标签和短 ref 必须经过 Git（git ls-remote）先解析成 commit SHA。

构建与验证：CLI 命令全集

用 CLI 把 source registry 构建为 built registry：

npx shadcn@latest build npx shadcn@latest build registry.json --output public/r

第一条使用默认输入./registry.json、默认输出./public/r；第二条显式指定输入文件与输出目录。在 CLI 参考（.agents/skills/shadcn/cli.md）中，build还支持--output <path>与--cwd <cwd>两个参数，默认输出目录即./public/r。

用 CLI 命令检查构建结果（namespace 形式）：

npx shadcn@latest list @acme npx shadcn@latest search @acme -q "login" npx shadcn@latest view @acme/login-form npx shadcn@latest add @acme/login-form --dry-run npx shadcn@latest registry validate ./registry.json

公共 GitHub registry 可直接用 GitHub 地址消费：

npx shadcn@latest list owner/repo npx shadcn@latest search owner/repo -q "login" npx shadcn@latest view owner/repo/item npx shadcn@latest add owner/repo/item --dry-run npx shadcn@latest registry validate owner/repo

search也同时是list的别名，支持-q查询、-t按类型过滤、--json结构化输出（详见 cli.md 的search命令表）。安装前的--dry-run用于预览全部受影响文件，--diff/--view用于逐文件审阅，这与 SKILL.md 中"绝不手动从 GitHub 拉取原始文件、一律走 CLI"的更新工作流一致。

在 shadcn/ui 代码库中实现 registry 时的工程建议

文档对实现侧给出了明确约束，这些约束同样适用于任何想深度定制 CLI 的团队：

• 保持地址解析纯函数化、可测试——解析不应依赖网络、文件系统等副作用；
• 不要给 validator 增加副作用——校验器应当只读、纯判断；
• 对官方 shadcn、namespace、URL、file 四种既有方案保留既有行为，不得破坏兼容；
• 为地址解析、源码加载、依赖解析、list、search、view、add各路径补测试；
• 在出现多个真实 provider 之前，优先使用小的 source-reader 抽象，而不是插件系统——避免过早抽象。

这条建议背后的设计哲学很清晰：registry 的价值在于"一个 CLI、多种地址方案、统一消费"，因此解析与加载边界要小且稳定，扩展点推迟到确有多个 provider 时再引入。

仓库证据：open-slide 中的 shadcn 集成现状

本仓库并未内置自己的registry.json（仓库内未检索到任何registry.json文件），但它本身就是一个典型的 shadcn 消费方，可以作为理解本文规则的实物参照：

• packages/core/components.json 采用new-york风格、baseColor: neutral、cssVariables: true，CSS 指向src/app/styles.css，aliases.ui为@/components/ui——这正是 CLIadd安装组件时写入文件的目标位置；
• packages/core/src/app/components/ui/button.tsx 使用class-variance-authority的cva定义variant/size变体，并大量使用bg-foreground、bg-brand、bg-card等语义化令牌——与本文cssVars定义语义令牌、组件引用令牌的设计完全对应；
• packages/core/package.json 声明了"shadcn": "^4.12.0"依赖，说明仓库运行的是现代 shadcn CLI，本文所述命令与字段均以该版本行为为准；
• .agents/skills/shadcn/SKILL.md 中要求"Registry 必须显式指定，绝不替用户默认某个注册表"，与本文registryDependencies必须书写完整地址、裸名不代表同仓库条目的规则互为印证。

小结

从"心智模型"出发，本文完整覆盖了 shadcn registry 编写与寻址的全链路：source registry 用真实文件编写条目，built registry 用npx shadcn@latest build生成；根registry.json承载name/homepage元数据与items/include；include按相对路径模块化拆分，item 文件路径一律相对声明处解析；item 通过files、dependencies、registryDependencies、cssVars等字段定义完整安装语义；依赖地址区分 shadcn / namespace / url / file / github 五类方案，GitHub 仓库可作为免构建的 source registry 由 CLI 直接消费；最后用list/search/view/add --dry-run/registry validate完成验证闭环。

若你需要继续深入，仓库内还有两份直接相关的姊妹文档：CLI 命令与参数全集见 .agents/skills/shadcn/cli.md，主题令牌与 CSS 变量体系见 .agents/skills/shadcn/customization.md，Agent 工作流见 .agents/skills/shadcn/SKILL.md。