113k
新建

2025 年 8 月 - shadcn CLI 3.0 与 MCP Server

命名空间 registry、高级认证、新命令以及完全重写的 registry 引擎。

我们刚刚发布了 shadcn CLI 3.0，支持命名空间 registry、高级认证、新命令以及完全重写的 registry 引擎。

新内容

命名空间 Registries

3.0 最大的变化是命名空间 registry。现在你可以使用 @registry/name 格式，从社区 registry、公司私有 registry 或内部 registry 安装组件。

这让跨团队和跨项目分发代码变得更容易。

Configure registries in your components.json:

components.json
{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json",
    "@internal": {
      "url": "https://registry.company.com/{name}",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

然后使用 @registry/name 格式安装组件：

pnpm dlx shadcn add @acme/button @internal/auth-system

这完全是去中心化的，没有中央注册机构。你可以创建任意命名空间，并按适合团队的方式组织组件。

components.json
{
  "registries": {
    "@design": "https://registry.company.com/create/{name}.json",
    "@engineering": "https://registry.company.com/eng/{name}.json",
    "@marketing": "https://registry.company.com/marketing/{name}.json"
  }
}

组件甚至可以依赖来自不同 registry 的资源。所有内容都会自动从正确来源解析并安装。

registry-item.json
{
  "name": "dashboard",
  "type": "registry:block",
  "registryDependencies": [
    "@shadcn/card", // From default registry
    "@v0/chart", // From v0 registry
    "@acme/data-table", // From acme registry
    "@lib/data-fetcher", // Utility library
    "@ai/analytics-prompt" // AI prompt resource
  ]
}

私有 Registries

需要让组件保持私有吗？我们已经支持。你可以使用 token、API key 或自定义请求头配置认证：

components.json
{
  "registries": {
    "@private": {
      "url": "https://registry.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

你的私有组件仍然保持私有。对于拥有专有 UI 库的企业团队来说非常合适。

我们支持所有主流认证方式：basic auth、bearer token、API key 查询参数以及自定义请求头。

更多细节请查看 认证文档。

搜索与发现

三个新命令可以帮助你轻松找到所需内容：

  1. 安装前查看 registry 中的条目
pnpm dlx shadcn view @acme/auth-system
  1. 在 registries 中搜索条目
pnpm dlx shadcn search @tweakcn -q "dark"
  1. 列出某个 registry 的所有条目
pnpm dlx shadcn list @acme

在安装前预览组件。在多个 registry 中搜索。提前查看代码和所有依赖。

MCP Server

MCP Server

早在 4 月，我们就 发布了 MCP server 的第一个版本。此后，我们吸收了所有经验，构建了一个更好的 MCP server。

新内容如下：

  • 支持所有 registries，零配置
  • 一条命令即可添加到你最喜欢的 MCP 客户端
  • 我们改进了底层工具
  • 与 CLI 和 registries 的集成更好
  • 支持在同一个项目中使用多个 registry

将 MCP server 添加到你的项目中：

pnpm dlx shadcn@latest mcp init

更多细节请查看 文档。

全方位加速

我们从头完全重写了 registry 解析引擎。它更快、更智能，甚至能处理最复杂的依赖树。

  • 依赖解析速度最高提升 3 倍
  • 更智能的文件去重和合并
  • 开箱即用的更好 monorepo 支持
  • 为 registry 作者更新了 build 命令

更好的错误处理

registry 开发者现在可以提供自定义错误信息，在出问题时帮助用户（以及 LLM）进行引导。CLI 会为常见问题展示有帮助、可执行的错误信息：

Unknown registry "@acme". Make sure it is defined in components.json as follows:
{
  "registries": {
    "@acme": "[URL_TO_REGISTRY]"
  }
}

缺少环境变量？CLI 会明确告诉你需要什么：

Registry "@private" requires the following environment variables:
  • REGISTRY_TOKEN
 
Set the required environment variables in your .env or .env.local file.

registry 作者可以在响应中提供自定义错误信息，帮助用户和 AI 代理快速理解并修复问题。

Error:
You are not authorized to access the item at http://example.com/r/component.
 
Message:
[Unauthorized] Your API key has expired. Renew it at https://example.com/api/renew-key.

升级指南

最棒的是：对用户没有破坏性变更。你现有的 components.json 仍然完全可用，所有已安装的组件也完全一样。

对于开发者，如果你在直接使用程序化 API，我们已经弃用了几个函数，并用更好的替代方案取代：

  • fetchRegistry → getRegistry
  • resolveRegistryTree → resolveRegistryItems
  • Schema moved from shadcn/registry to shadcn/schema package
# 从 "shadcn/registry" 导入 registryItemSchema
# import { registryItemSchema } from "shadcn/registry"
+ import { registryItemSchema } from "shadcn/schema"

就这些。真的。其他部分都可以正常工作。