发布自己的 shadcn-vue 扩展组件，并支持 CLI 安装

shadcn-vue 支持自定义 Registry。我们可以把自己的组件、组合式函数或其他文件构建成 Registry Item，再通过 CLI 安装到其他项目中，使用体验与安装官方组件基本一致。

它可以让 CLI 下载组件源码及相关依赖，并写入使用者的项目。下面以发布一个名为 copy 的组件为例，走完配置、构建、发布和安装的完整流程。

本文介绍的是 Vue 版的 shadcn-vue，所有 Schema 和命令均以 shadcn-vue 官方文档 为准，不要与 React 版的 shadcn CLI 混用。
完整字段说明可以查看 shadcn-vue 官方的 Registry 文档 和 registry.json Schema。目前 Registry 仍属于实验性功能，升级 CLI 后建议重新构建并验证一次。

创建 registry.json

在项目根目录创建 registry.json：

{
  "$schema": "https://shadcn-vue.com/schema/registry.json",
  "name": "prop-show-kit",
  "homepage": "https://kit.prop.show",
  "items": [
    {
      "name": "copy",
      "type": "registry:component",
      "title": "Copy",
      "description": "A copy component with tooltip feedback.",
      "dependencies": [
        "@vueuse/core"
      ],
      "registryDependencies": [
        "button",
        "tooltip"
      ],
      "files": [
        {
          "path": "app/components/prop-ui/copy/Copy.vue",
          "type": "registry:component"
        },
        {
          "path": "app/components/prop-ui/copy/index.ts",
          "type": "registry:component"
        }
      ]
    }
  ]
}

这里有几个容易混淆的字段：

• name 是 Registry 的名称，主要用于元数据，不会决定生成文件的目录或访问地址。
• homepage 是 Registry 的主页地址，同样不会自动配置路由。最终的访问地址由构建输出目录和部署平台决定。
• items 用来声明所有可安装项。示例中的 copy 是一个简单组件，因此使用 registry:component；包含页面或多个模块的复杂组件可以使用 registry:block。
• files[].path 是源文件相对于项目根目录的路径。构建时找不到对应文件会直接失败。

声明依赖

组件依赖分为两类：

• dependencies：npm 依赖，例如 @vueuse/core。需要限制版本时，使用 包名@版本 的格式，例如 @vueuse/core@^14.0.0。
• registryDependencies：其他 Registry Item。shadcn-vue 官方组件可以直接写名称，例如 button、tooltip；其他自定义 Registry 中的组件需要填写完整地址，例如 https://example.com/r/editor.json。

依赖要声明完整，否则使用者虽然能拿到组件源码，安装后仍可能遇到缺少包或导入文件不存在的问题。

构建 Registry

先把 shadcn-vue CLI 安装为开发依赖：

pnpm add -D shadcn-vue@latest

然后在 package.json 中添加构建脚本：

{
  "scripts": {
    "registry:build": "shadcn-vue build"
  }
}

运行脚本：

pnpm registry:build

CLI 默认读取项目根目录下的 registry.json，并把每个 Registry Item 构建到 public/r。上面的配置会生成：

public/r/copy.json

如果需要修改输出目录，可以使用 --output：

pnpm exec shadcn-vue build --output ./public/registry

registry.json 是构建配置，真正提供给 CLI 安装的是构建后的单项 JSON，例如 copy.json。不要把 https://kit.prop.show/r/registry.json 当成组件安装地址。

本地验证

启动项目后，先确认浏览器可以访问：

http://localhost:3000/r/copy.json

再到另一个已经初始化 shadcn-vue 的 Vue 或 Nuxt 项目中测试安装：

pnpm dlx shadcn-vue@latest add http://localhost:3000/r/copy.json

检查 CLI 是否安装了 npm 依赖、Registry 依赖和组件文件，同时确认生成的导入路径符合目标项目的 components.json 配置。

发布与安装

部署项目时，需要确保 public/r 中的文件会作为静态资源发布。部署完成后，先直接访问线上 JSON 地址，确认没有 404 或重定向到 HTML 页面。

以本文的域名为例，其他项目可以这样安装组件：

pnpm dlx shadcn-vue@latest add https://kit.prop.show/r/copy.json

至此，一个可以通过 shadcn-vue CLI 安装的自定义组件就发布完成了。

常见问题

构建后找不到 JSON 文件

确认命令是在包含 registry.json 的项目根目录运行，并检查 files[].path 是否真实存在。默认输出目录是 public/r，自定义过 --output 时则以实际配置为准。

JSON 解析失败

registry.json 必须是严格 JSON，不能包含注释，也不能在数组或对象的最后一项后保留逗号。可以先让编辑器根据 $schema 检查格式，再运行构建命令。

本地可以访问，部署后却是 404

homepage 不会帮你配置静态资源路由。检查部署产物中是否包含 public/r 下的文件，以及部署平台是否为站点配置了额外的基础路径。

安装成功后出现依赖或导入错误

检查 npm 包是否都写入 dependencies，shadcn-vue 组件或其他自定义组件是否都写入 registryDependencies。组件源码也不应依赖只存在于 Registry 项目内部、却没有一并发布的文件。