2025年8月 - shadcn CLI 3.0 和 MCP 服务器

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

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

🌐 We just shipped shadcn CLI 3.0 with support for namespaced registries, advanced authentication, new commands and a completely rewritten registry engine.

有什么新东西

🌐 What's New

命名空间注册表 - 使用 @registry/name 格式安装组件。
私有注册表 - 使用高级身份验证保护你的注册表。
搜索与发现 - 在安装前查找和查看代码的新命令。
MCP 服务器 - 用于所有注册表的 MCP 服务器。
更快的一切 - 完全重写的注册表解析。
改进的错误处理 - 为用户和大型语言模型提供更好的错误信息。
升级指南 - 现有用户的迁移说明。

命名空间注册表

🌐 Namespaced Registries

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

🌐 The biggest change in 3.0 is namespaced registries. You can now install components from registries: a community registry, your company's private registry or internal registry, using the @registry/name format.

这使得在团队和项目之间分发代码更加容易。

🌐 This makes it easier to distribute code across teams and projects.

在你的 components.json 中配置注册表：

🌐 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 格式来安装组件：

🌐 Then use the @registry/name format to install components:


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

它是完全去中心化的。没有中央注册机构。创建任何你想要的命名空间，并以对你的团队有意义的方式组织组件。

🌐 It's completely decentralized. There's no central registrar. Create any namespace you want and organize components however makes sense for your team.

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"
  }
}

组件甚至可以依赖来自不同注册表的资源。一切都会从正确的来源自动解析和安装。

🌐 Components can even depend on resources from different registries. Everything gets resolved and installed automatically from the right sources.

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
  ]
}

私有注册表

🌐 Private Registries

需要保持你的组件私密吗？我们为你提供保障。使用令牌、API 密钥或自定义头配置身份验证：

🌐 Need to keep your components private? We've got you covered. Configure authentication with tokens, API keys, or custom headers:

components.json

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

你的私有组件保持私有。非常适合拥有专有 UI 库的企业团队。

🌐 Your private components stay private. Perfect for enterprise teams with proprietary UI libraries.

我们支持所有主要的身份验证方法：基本认证、承载令牌、API 密钥查询参数和自定义头。

🌐 We support all major authentication methods: basic auth, bearer token, api key query params and custom headers.

有关更多详细信息，请参见身份验证文档。

🌐 See the authentication docs for more details.

搜索与发现

🌐 Search & Discovery

三个新命令使你轻松找到所需的内容：

🌐 Three new commands make it easy to find exactly what you need:

在安装之前查看注册表中的项目


pnpm dlx shadcn view @acme/auth-system

从注册表中搜索项目


pnpm dlx shadcn search @tweakcn -q "dark"

列出注册表中的所有项


pnpm dlx shadcn list @acme

在安装组件之前预览它们。跨多个注册表搜索。提前查看代码和所有依赖。

🌐 Preview components before installing them. Search across multiple registries. See the code and all dependencies upfront.

MCP 服务器

🌐 MCP Server

早在四月份，我们推出了第一版本的MCP服务器。从那时起，我们吸取了所有经验，打造了一个更好的MCP服务器。

🌐 Back in April, we introduced the first version of the MCP server. Since then, we've taken everything we learned and built a better MCP server.

以下是新内容：

🌐 Here's what's new:

适用于所有注册表。零配置
一个命令添加到你最喜欢的MCP客户端
我们改进了基础工具
与 CLI 和注册表的更好集成
在同一项目中支持多个注册表

将 MCP 服务器添加到你的项目：

🌐 Add the MCP server to your project:


pnpm dlx shadcn@latest mcp init

有关更多详细信息，请参阅文档。

🌐 See the docs for more details.

一切更快

🌐 Faster Everything

我们从零重新编写了注册表解析引擎。它更快、更智能，甚至可以处理最棘手的依赖树。

🌐 We completely rewrote the registry resolution engine from scratch. It's faster, smarter, and handles even the trickiest dependency trees.

依赖解析速度提升至3倍
更智能的文件去重与合并
开箱即用的更好单体仓库支持
为注册表作者更新了 build 命令

改进的错误处理

🌐 Improved Error Handling

注册表开发者现在可以提供自定义错误信息，以帮助在出现问题时指导用户（和大型语言模型）。命令行接口会针对常见问题显示有帮助且可操作的错误信息：

🌐 Registry developers can now provide custom error messages to help guide users (and LLMs) when things go wrong. The CLI displays helpful, actionable errors for common issues:

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

缺少环境变量？CLI 会准确告诉你需要哪些内容：

🌐 Missing environment variables? The CLI tells you exactly what's needed:

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

注册表作者可以在他们的响应中提供自定义错误信息，以帮助用户和 AI 代理快速理解和解决问题。

🌐 Registry authors can provide custom error messages in their responses to help users and AI agents understand and fix issues quickly.

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.

升级指南

🌐 Upgrade Guide

最棒的部分是：对于用户来说没有重大更改。你现有的 components.json 完全一样地工作。你安装的所有组件也完全一样地工作。

🌐 Here's the best part: there are no breaking changes for users. Your existing components.json works exactly the same. All your installed components work exactly the same.

对于开发者，如果你直接使用编程 API，我们已经弃用了一些函数，以采用更好的函数：

🌐 For developers, if you're using the programmatic APIs directly, we've deprecated a few functions in favor of better ones:

fetchRegistry → getRegistry
resolveRegistryTree → resolveRegistryItems
模式已从 shadcn/registry 包移动到 shadcn/schema 包

- import { registryItemSchema } from "shadcn/registry"
+ import { registryItemSchema } from "shadcn/schema"

就是这样。说真的。其他一切都能正常运作。

🌐 That's it. Seriously. Everything else just works.

On This Page

有什么新东西命名空间注册表私有注册表搜索与发现 MCP 服务器一切更快改进的错误处理升级指南