命名空间

配置并使用支持命名空间的多个资源注册表。

命名空间注册表允许你在一个项目中配置多个资源来源。这意味着你可以从各种注册表中安装组件、库、实用程序、AI 提示、配置文件和其他资源，无论它们是公共的、第三方的还是你自己的自定义私有库。

🌐 Namespaced registries let you configure multiple resource sources in one project. This means you can install components, libraries, utilities, AI prompts, configuration files, and other resources from various registries, whether they're public, third-party, or your own custom private libraries.

概览

🌐 Overview

注册表命名空间以 @ 为前缀，提供了一种组织和引用来自不同来源资源的方式。资源可以是任何类型的内容：组件、库、工具、钩子、AI 提示、配置文件、主题等。例如：

🌐 Registry namespaces are prefixed with @ and provide a way to organize and reference resources from different sources. Resources can be any type of content: components, libraries, utilities, hooks, AI prompts, configuration files, themes, and more. For example:

@shadcn/button - 来自 shadcn 注册表的 UI 组件
@v0/dashboard - 来自 v0 注册表的仪表板组件
@ai-elements/input - 来自 AI 元素注册表的 AI 提示输入
@acme/auth-utils - 来自你公司私有注册表的身份验证工具
@ai/chatbot-rules - 来自人工智能资源注册表的 AI 提示规则
@themes/dark-mode - 来自主题注册表的主题配置

去中心化命名空间系统

🌐 Decentralized Namespace System

我们有意将命名空间系统设计为去中心化。对于开源命名空间，有一个中央开源注册索引，但你可以自由创建和使用任何你想要的命名空间。

🌐 We intentionally designed the namespace system to be decentralized. There is a central open source registry index for open source namespaces but you are free to create and use any namespace you want.

这种去中心化的方法让你可以完全灵活地按对你的组织有意义的方式组织资源。

🌐 This decentralized approach gives you complete flexibility to organize your resources however makes sense for your organization.

你可以为不同的目的创建多个注册表：

🌐 You can create multiple registries for different purposes:

components.json

{
  "registries": {
    "@acme-ui": "https://registry.acme.com/ui/{name}.json",
    "@acme-docs": "https://registry.acme.com/docs/{name}.json",
    "@acme-ai": "https://registry.acme.com/ai/{name}.json",
    "@acme-themes": "https://registry.acme.com/themes/{name}.json",
    "@acme-internal": {
      "url": "https://internal.acme.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

这允许你：

🌐 This allows you to:

按类型组织：将 UI 组件、文档、AI 资源等分开。
按团队组织：不同的团队可以维护自己的注册表
按可见性组织：公共资源与私有资源
按版本组织：稳定版与实验版注册表
没有命名冲突：由于没有中央权限，你不需要担心命名空间冲突

多注册表设置示例

🌐 Examples of Multi-Registry Setups

按资源类型

🌐 By Resource Type

components.json

{
  "@components": "https://cdn.company.com/components/{name}.json",
  "@hooks": "https://cdn.company.com/hooks/{name}.json",
  "@utils": "https://cdn.company.com/utils/{name}.json",
  "@prompts": "https://cdn.company.com/ai-prompts/{name}.json"
}

按团队或部门

🌐 By Team or Department

components.json

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

通过稳定性

🌐 By Stability

components.json

{
  "@stable": "https://registry.company.com/stable/{name}.json",
  "@latest": "https://registry.company.com/beta/{name}.json",
  "@experimental": "https://registry.company.com/experimental/{name}.json"
}

入门

🌐 Getting Started

安装资源

🌐 Installing Resources

配置完成后，你可以使用命名空间语法安装资源：

🌐 Once configured, you can install resources using the namespace syntax:


pnpm dlx shadcn@latest add @v0/dashboard

或者同时使用多个资源：

🌐 or multiple resources at once:


pnpm dlx shadcn@latest add @acme/header @lib/auth-utils @ai/chatbot-rules

快速配置

🌐 Quick Configuration

将注册表添加到你的 components.json：

🌐 Add registries to your components.json:

components.json

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/resources/{name}.json"
  }
}

然后开始安装：

🌐 Then start installing:


pnpm dlx shadcn@latest add @acme/button

注册表命名规范

🌐 Registry Naming Convention

注册表名称必须遵循以下规则：

🌐 Registry names must follow these rules:

从 @ 符号开始
仅包含字母数字字符、连字符和下划线
有效名称示例：@v0，@acme-ui，@my_company

引用资源的模式是：@namespace/resource-name

🌐 The pattern for referencing resources is: @namespace/resource-name

配置

🌐 Configuration

命名空间注册表在你的 components.json 文件的 registries 字段下配置。

🌐 Namespaced registries are configured in your components.json file under the registries field.

基本配置

🌐 Basic Configuration

配置注册表的最简单方法是使用 URL 模板字符串：

🌐 The simplest way to configure a registry is with a URL template string:

components.json

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/resources/{name}.json",
    "@lib": "https://lib.company.com/utilities/{name}",
    "@ai": "https://ai-resources.com/r/{name}.json"
  }
}

注意： URL 中的 {name} 占位符会在你运行 npx shadcn@latest add @namespace/resource-name 时自动解析并替换为资源名称。例如，@acme/button 会变成 https://registry.acme.com/resources/button.json。更多详情请参见 URL 模式系统。

高级配置

🌐 Advanced Configuration

对于需要身份验证或其他参数的注册表，请使用对象格式：

🌐 For registries that require authentication or additional parameters, use the object format:

components.json

{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}",
        "X-API-Key": "${API_KEY}"
      },
      "params": {
        "version": "latest",
        "format": "json"
      }
    }
  }
}

注意: 格式为 ${VAR_NAME} 的环境变量会自动从你的环境（process.env）中展开。这适用于 URL、请求头和参数。例如，${REGISTRY_TOKEN} 将被替换为 process.env.REGISTRY_TOKEN 的值。有关使用环境变量的更多详情，请参阅认证与安全。

URL 模式系统

🌐 URL Pattern System

注册表 URL 支持以下占位符：

🌐 Registry URLs support the following placeholders:

`{name}` 占位符（必填）

🌐 {name} Placeholder (required)

{name} 占位符将被资源名称替换：

🌐 The {name} placeholder is replaced with the resource name:

components.json

{
  "@acme": "https://registry.acme.com/{name}.json"
}

安装 @acme/button 时，URL 变为：https://registry.acme.com/button.json 安装 @acme/auth-utils 时，URL 变为：https://registry.acme.com/auth-utils.json

🌐 When installing @acme/button, the URL becomes: https://registry.acme.com/button.json When installing @acme/auth-utils, the URL becomes: https://registry.acme.com/auth-utils.json

`{style}` 占位符（可选）

🌐 {style} Placeholder (optional)

{style} 占位符将被替换为当前的样式配置：

🌐 The {style} placeholder is replaced with the current style configuration:

{
  "@themes": "https://registry.example.com/{style}/{name}.json"
}

当样式设置为 new-york 时，安装 @themes/card 会解析为：https://registry.example.com/new-york/card.json

🌐 With style set to new-york, installing @themes/card resolves to: https://registry.example.com/new-york/card.json

样式占位符是可选的。当你希望提供同一资源的不同版本时使用。例如，你可以为每种样式提供组件的不同版本。

🌐 The style placeholder is optional. Use this when you want to serve different versions of the same resource. For example, you can serve a different version of a component for each style.

认证与安全

🌐 Authentication & Security

环境变量

🌐 Environment Variables

使用环境变量安全地存储凭证：

🌐 Use environment variables to securely store credentials:

components.json

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

然后设置环境变量：

🌐 Then set the environment variable:

.env.local

REGISTRY_TOKEN=your_secret_token_here

认证方法

🌐 Authentication Methods

承载令牌 (OAuth 2.0)

🌐 Bearer Token (OAuth 2.0)

{
  "@github": {
    "url": "https://api.github.com/repos/org/registry/contents/{name}.json",
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  }
}

请求头中的 API 密钥

🌐 API Key in Headers

components.json

{
  "@private": {
    "url": "https://api.company.com/registry/{name}",
    "headers": {
      "X-API-Key": "${API_KEY}"
    }
  }
}

基本认证

🌐 Basic Authentication

components.json

{
  "@internal": {
    "url": "https://registry.company.com/{name}.json",
    "headers": {
      "Authorization": "Basic ${BASE64_CREDENTIALS}"
    }
  }
}

查询参数认证

🌐 Query Parameter Authentication

components.json

{
  "@secure": {
    "url": "https://registry.example.com/{name}.json",
    "params": {
      "api_key": "${API_KEY}",
      "client_id": "${CLIENT_ID}",
      "signature": "${REQUEST_SIGNATURE}"
    }
  }
}

多重认证方法

🌐 Multiple Authentication Methods

某些注册表需要多种身份验证方法：

🌐 Some registries require multiple authentication methods:

components.json

{
  "@enterprise": {
    "url": "https://api.enterprise.com/v2/registry/{name}",
    "headers": {
      "Authorization": "Bearer ${ACCESS_TOKEN}",
      "X-API-Key": "${API_KEY}",
      "X-Workspace-Id": "${WORKSPACE_ID}"
    },
    "params": {
      "version": "latest"
    }
  }
}

安全注意事项

🌐 Security Considerations

在处理命名空间注册表时，尤其是第三方或公共注册表，安全性至关重要。以下是我们处理安全性的方式：

🌐 When working with namespaced registries, especially third-party or public ones, security is paramount. Here's how we handle security:

资源验证

🌐 Resource Validation

从注册表获取的所有资源在安装前都会根据我们的注册表项模式进行验证。这可以确保：

🌐 All resources fetched from registries are validated against our registry item schema before installation. This ensures:

结构验证：资源必须符合预期的 JSON 模式
类型安全：资源类型已被验证（registry:ui、registry:lib 等）
不允许任意代码执行：资源是数据文件，而不是可执行脚本

环境变量安全

🌐 Environment Variable Security

用于身份验证的环境变量有：

🌐 Environment variables used for authentication are:

从不记录：CLI 从不记录或显示环境变量的值
在运行时展开：变量仅在需要时展开，而不被存储
每个注册表隔离：每个注册表维护自己的认证上下文

安全配置示例：

🌐 Example of secure configuration:

components.json

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

切勿将真实的令牌提交到版本控制中。使用 .env.local：

🌐 Never commit actual tokens to version control. Use .env.local:

.env.local

PRIVATE_REGISTRY_TOKEN=actual_token_here

强制使用 HTTPS

🌐 HTTPS Enforcement

我们强烈建议对所有注册表 URL 使用 HTTPS：

🌐 We strongly recommend using HTTPS for all registry URLs:

加密传输：防止中间人攻击
证书验证：确保你正在连接到合法的注册表
凭证保护：头信息和令牌在传输过程中被加密

components.json

{
  "registries": {
    "@secure": "https://registry.example.com/{name}.json", // ✅ Good
    "@insecure": "http://registry.example.com/{name}.json" // ❌ Avoid
  }
}

内容安全

🌐 Content Security

来自注册表的资源被视为数据，而不是代码：

🌐 Resources from registries are treated as data, not code:

仅限 JSON 解析：资源必须是有效的 JSON
模式验证：必须与注册表项模式匹配
文件路径限制：文件只能写入已配置的路径
不执行脚本：CLI 不会执行任何来自注册表资源的代码

注册表信任模型

🌐 Registry Trust Model

命名空间系统基于信任模型运行：

🌐 The namespace system operates on a trust model:

你信任你安装的内容：只将你信任的注册表添加到你的配置中
显式配置：注册表必须在 components.json 中显式配置
没有自动注册表发现：CLI 永远不会自动添加注册表
依赖透明性：所有依赖都在注册表条目中清晰列出

注册机构运营商的最佳实践

🌐 Best Practices for Registry Operators

如果你正在运行你自己的注册表：

🌐 If you're running your own registry:

始终使用 HTTPS：切勿通过 HTTP 提供注册表内容
实现身份验证：要求私有注册表使用 API 密钥或令牌
速率限制：保护你的注册表免受滥用
内容验证：在提供资源之前进行验证

示例安全注册表设置：

🌐 Example secure registry setup:

components.json

{
  "@company": {
    "url": "https://registry.company.com/v1/{name}.json",
    "headers": {
      "Authorization": "Bearer ${COMPANY_TOKEN}",
      "X-Registry-Version": "1.0"
    }
  }
}

安装前检查资源

🌐 Inspecting Resources Before Installation

CLI 提供了关于正在安装内容的透明度。你可以使用以下命令查看注册表项的有效负载：

🌐 The CLI provides transparency about what's being installed. You can see the payload of a registry item using the following command:


pnpm dlx shadcn@latest view @acme/button

这将把注册表项的有效负载输出到控制台。

🌐 This will output the payload of the registry item to the console.

依赖解析

🌐 Dependency Resolution

基本依赖解析

🌐 Basic Dependency Resolution

资源可以在不同的注册表之间存在依赖：

🌐 Resources can have dependencies across different registries:

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

CLI 会自动从各自的注册表解析并安装所有依赖。

🌐 The CLI automatically resolves and installs all dependencies from their respective registries.

高级依赖解析

🌐 Advanced Dependency Resolution

如果你正在开发注册表或需要自定义第三方资源，了解依赖在内部是如何解析的非常重要。

🌐 Understanding how dependencies are resolved internally is important if you're developing registries or need to customize third-party resources.

分辨率如何工作

🌐 How Resolution Works

当你运行 npx shadcn@latest add @namespace/resource 时，CLI 会执行以下操作：

🌐 When you run npx shadcn@latest add @namespace/resource, the CLI does the following:

清除注册表上下文以重新开始
从指定的注册表获取主要资源
从各自的注册表递归解析依赖
应用拓扑排序以确保正确的安装顺序
根据目标路径去重文件（以最后一个为准）
深度合并配置（tailwind、cssVars、css、envVars）

这意味着如果你运行以下命令：

🌐 This means that if you run the following command:


pnpm dlx shadcn@latest add @acme/auth @custom/login-form

@custom/login-form 的 login-form.ts 将覆盖 @acme/auth 的 login-form.ts，因为它最后被解析。

🌐 The login-form.ts from @custom/login-form will override the login-form.ts from @acme/auth because it's resolved last.

覆盖第三方资源

🌐 Overriding Third-Party Resources

你可以利用依赖解析过程，通过将它们添加到你在 registryDependencies 下的自定义资源中，并用你自己的自定义值覆盖，从而覆盖任何第三方资源。

🌐 You can leverage the dependency resolution process to override any third-party resource by adding them to your custom resource under registryDependencies and overriding with your own custom values.

示例：自定义第三方按钮

🌐 Example: Customizing a Third-Party Button

假设你想定制供应商注册表中的一个按钮：

🌐 Let's say you want to customize a button from a vendor registry:

1. 原始供应商按钮 (@vendor/button)：

button.json

{
  "name": "button",
  "type": "registry:ui",
  "files": [
    {
      "path": "components/ui/button.tsx",
      "type": "registry:ui",
      "content": "// Vendor's button implementation\nexport function Button() { ... }"
    }
  ],
  "cssVars": {
    "light": {
      "--button-bg": "blue"
    }
  }
}

2. 创建你的自定义覆盖 (@my-company/custom-button)

custom-button.json

{
  "name": "custom-button",
  "type": "registry:ui",
  "registryDependencies": [
    "@vendor/button" // Import original first
  ],
  "cssVars": {
    "light": {
      "--button-bg": "purple" // Override the color
    }
  }
}

3. 安装你的自定义版本：


pnpm dlx shadcn@latest add @my-company/custom-button

这会安装来自 @vendor/button 的原始按钮，然后用你自己的自定义值覆盖 cssVars。

🌐 This installs the original button from @vendor/button and then overrides the cssVars with your own custom values.

高级覆盖模式

🌐 Advanced Override Patterns

扩展而不替换

🌐 Extending Without Replacing

保留原始并添加扩展：

🌐 Keep the original and add extensions:

extended-table.json

{
  "name": "extended-table",
  "registryDependencies": ["@vendor/table"],
  "files": [
    {
      "path": "components/ui/table-extended.tsx",
      "content": "import { Table } from '@vendor/table'\n// Add your extensions\nexport function ExtendedTable() { ... }"
    }
  ]
}

这将安装来自 @vendor/table 的原始表，然后将你的扩展添加到 components/ui/table-extended.tsx。

🌐 This will install the original table from @vendor/table and then add your extensions to components/ui/table-extended.tsx.

部分覆盖（多文件资源）

🌐 Partial Override (Multi-file Resources)

仅覆盖复杂组件中的特定文件：

🌐 Override only specific files from a complex component:

custom-auth.json

{
  "name": "custom-auth",
  "registryDependencies": [
    "@vendor/auth" // Has multiple files
  ],
  "files": [
    {
      "path": "lib/auth-server.ts",
      "type": "registry:lib",
      "content": "// Your custom auth server"
    }
  ]
}

解析顺序示例

🌐 Resolution Order Example

当你安装依赖于多个资源的 @custom/dashboard 时：

🌐 When you install @custom/dashboard that depends on multiple resources:

dashboard.json

{
  "name": "dashboard",
  "registryDependencies": [
    "@shadcn/card", // 1. Resolved first
    "@vendor/chart", // 2. Resolved second
    "@custom/card" // 3. Resolved last (overrides @shadcn/card)
  ]
}

解析顺序：

🌐 Resolution order:

@shadcn/card - 安装到 components/ui/card.tsx
@vendor/chart - 安装到 components/ui/chart.tsx
@custom/card - 覆盖 components/ui/card.tsx（如果目标相同）

关键分辨率功能

🌐 Key Resolution Features

源跟踪：每个资源都知道它来自哪个注册表，从而避免命名冲突
循环依赖预防：自动检测并防止循环依赖
智能安装顺序：先安装依赖，然后安装使用这些依赖的资源

版本控制

🌐 Versioning

你可以使用查询参数为注册表资源实现版本控制。这允许用户固定特定版本或使用不同的发布渠道。

🌐 You can implement versioning for your registry resources using query parameters. This allows users to pin specific versions or use different release channels.

基础版本参数

🌐 Basic Version Parameter

components.json

{
  "@versioned": {
    "url": "https://registry.example.com/{name}",
    "params": {
      "version": "v2"
    }
  }
}

这将 @versioned/button 解析为：https://registry.example.com/button?version=v2

🌐 This resolves @versioned/button to: https://registry.example.com/button?version=v2

动态版本选择

🌐 Dynamic Version Selection

使用环境变量来控制项目中的版本：

🌐 Use environment variables to control versions across your project:

components.json

{
  "@stable": {
    "url": "https://registry.company.com/{name}",
    "params": {
      "version": "${REGISTRY_VERSION}"
    }
  }
}

这允许你：

🌐 This allows you to:

在生产环境中设置 REGISTRY_VERSION=v1.2.3
按环境（开发、预发布、生产）覆盖

语义化版本控制

🌐 Semantic Versioning

实现带范围支持的语义版本控制：

🌐 Implement semantic versioning with range support:

components.json

{
  "@npm-style": {
    "url": "https://registry.example.com/{name}",
    "params": {
      "semver": "^2.0.0",
      "prerelease": "${ALLOW_PRERELEASE}"
    }
  }
}

版本解决最佳实践

🌐 Version Resolution Best Practices

使用环境变量 来在不同环境中进行版本控制
使用 ${VAR:-default} 语法提供合理的默认值
文档版本方案 对注册用户清晰明了
支持版本固定 以实现可重现构建
实现版本发现端点（例如，/versions/{name}）
为版本化资源 使用适当的缓存头进行正确缓存

命令行接口命令

🌐 CLI Commands

shadcn CLI 提供了几个用于处理命名空间注册表的命令：

🌐 The shadcn CLI provides several commands for working with namespaced registries:

添加资源

🌐 Adding Resources

从任何已配置的注册表安装资源：

🌐 Install resources from any configured registry:

# Install from a specific registry
npx shadcn@latest add @v0/dashboard
 
# Install multiple resources
npx shadcn@latest add @acme/button @lib/utils @ai/prompt
 
# Install from URL directly
npx shadcn@latest add https://registry.example.com/button.json
 
# Install from local file
npx shadcn@latest add ./local-registry/button.json

查看资源

🌐 Viewing Resources

安装前检查注册表项：

🌐 Inspect registry items before installation:

# View a resource from a registry
npx shadcn@latest view @acme/button
 
# View multiple resources
npx shadcn@latest view @v0/dashboard @shadcn/card
 
# View from URL
npx shadcn@latest view https://registry.example.com/button.json

view 命令显示：

🌐 The view command displays:

资源元数据（名称、类型、描述）
依赖和注册表依赖
将要安装的文件内容
CSS 变量和 Tailwind 配置
所需的环境变量

搜索注册表

🌐 Searching Registries

在注册表中搜索可用资源：

🌐 Search for available resources in registries:

# Search a specific registry
npx shadcn@latest search @v0
 
# Search with query
npx shadcn@latest search @acme --query "auth"
 
# Search multiple registries
npx shadcn@latest search @v0 @acme @lib
 
# Limit results
npx shadcn@latest search @v0 --limit 10 --offset 20
 
# List all items (alias for search)
npx shadcn@latest list @acme

搜索结果包括：

🌐 Search results include:

资源名称和类型
描述
注册表来源

错误处理

🌐 Error Handling

未配置注册表

🌐 Registry Not Configured

如果你引用了未配置的注册表：

🌐 If you reference a registry that isn't configured:


pnpm dlx shadcn@latest add @non-existent/component

错误：

🌐 Error:

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

缺少环境变量

🌐 Missing Environment Variables

如果未设置所需的环境变量：

🌐 If required environment variables are not set:

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

资源未找到

🌐 Resource Not Found

404 未找到：

The item at https://registry.company.com/button.json was not found. It may not exist at the registry.

这通常意味着：

🌐 This usually means:

资源名称拼写错误
该资源在注册表中不存在
注册表 URL 模式不正确

认证失败

🌐 Authentication Failures

401 未经授权：

You are not authorized to access the item at https://api.company.com/button.json
Check your authentication credentials and environment variables.

403 禁止访问：

Access forbidden for https://api.company.com/button.json
Verify your API key has the necessary permissions.

创建你自己的注册表

🌐 Creating Your Own Registry

为了使你的注册表与命名空间系统兼容，你可以提供任何类型的资源——组件、库、工具、AI 提示、主题、配置或任何其他可共享的代码/内容：

🌐 To make your registry compatible with the namespace system, you can serve any type of resource - components, libraries, utilities, AI prompts, themes, configurations, or any other shareable code/content:

实现注册表项模式：你的注册表必须返回符合注册表项模式的 JSON。
支持 URL 模式：在 URL 模板中包含 {name}，用于插入资源名称。
定义资源类型：使用适当的 type 字段来标识你的资源（例如，registry:ui、registry:lib、registry:ai、registry:theme 等）。
处理身份验证（如有需要）：通过头信息或查询参数接受身份验证。
记录你的命名空间：为用户提供配置你的注册表的清晰说明：

components.json

{
  "registries": {
    "@your-registry": "https://your-domain.com/r/{name}.json"
  }
}

技术细节

🌐 Technical Details

解析器模式

🌐 Parser Pattern

命名空间解析器使用以下正则表达式模式：

🌐 The namespace parser uses the following regex pattern:

namespace-parser.js

/^(@[a-zA-Z0-9](?:[a-zA-Z0-9-_]*[a-zA-Z0-9])?)\/(.+)$/

这确保了有效的命名空间格式和正确的组件名称提取。

🌐 This ensures valid namespace formatting and proper component name extraction.

解决过程

🌐 Resolution Process

解析：从 @namespace/component 中提取命名空间和组件名称
查找: 查找 @namespace 的注册表配置
构建 URL：将占位符替换为实际值
设置请求头：如果已配置，则应用身份验证请求头
获取：从解析后的 URL 中检索组件
验证：确保响应与注册表项模式匹配
解决依赖：递归获取任何注册表依赖

跨注册表依赖

🌐 Cross-Registry Dependencies

当一个组件有来自不同注册表的依赖时，解析器：

🌐 When a component has dependencies from different registries, the resolver:

为每个注册表维护独立的身份验证上下文
从其各自的来源解析每个依赖
根据目标路径去重文件
合并来自所有来源的配置（tailwind、cssVars 等）

最佳实践

🌐 Best Practices

使用环境变量 存储像 API 密钥和令牌这样的敏感数据
为你的注册表命名空间，使用唯一且具有描述性的名称
文件认证要求 对用户明确
实现适当的错误响应，并提供有用的信息
尽可能缓存注册表响应以提高性能
支持样式变体 如果你的组件有多种主题

故障排除

🌐 Troubleshooting

未找到资源

🌐 Resources not found

验证注册表 URL 是否正确且可访问
检查 URL 中是否包含 {name} 占位符
确保资源在注册表中存在
确认资源类型与注册表提供的匹配

身份验证问题

🌐 Authentication issues

确认环境变量设置正确
验证 API 密钥/令牌是否有效且未过期
检查头是否以正确的格式发送

依赖冲突

🌐 Dependency conflicts

查看来自不同注册表的同名资源
使用完全限定名称（@namespace/resource）以避免歧义
检查注册表之间的循环依赖
在混合注册表时确保资源类型兼容

入门身份验证

On This Page

目录概览去中心化命名空间系统多注册表设置示例按资源类型按团队或部门通过稳定性入门安装资源快速配置注册表命名规范配置基本配置高级配置 URL 模式系统 {name} 占位符（必填）{style} 占位符（可选）认证与安全环境变量认证方法承载令牌 (OAuth 2.0)请求头中的 API 密钥基本认证查询参数认证多重认证方法安全注意事项资源验证环境变量安全强制使用 HTTPS 内容安全注册表信任模型注册机构运营商的最佳实践安装前检查资源依赖解析基本依赖解析高级依赖解析分辨率如何工作覆盖第三方资源示例：自定义第三方按钮高级覆盖模式扩展而不替换部分覆盖（多文件资源）解析顺序示例关键分辨率功能版本控制基础版本参数动态版本选择语义化版本控制版本解决最佳实践命令行接口命令添加资源查看资源搜索注册表错误处理未配置注册表缺少环境变量资源未找到认证失败创建你自己的注册表技术细节解析器模式解决过程跨注册表依赖最佳实践故障排除未找到资源身份验证问题依赖冲突

命名空间

目录

概览

去中心化命名空间系统

多注册表设置示例

按资源类型

按团队或部门

通过稳定性

入门

安装资源

快速配置

注册表命名规范

配置

基本配置

高级配置

URL 模式系统

{name} 占位符（必填）

{style} 占位符（可选）

认证与安全

环境变量

认证方法

承载令牌 (OAuth 2.0)

请求头中的 API 密钥

基本认证

查询参数认证

多重认证方法

安全注意事项

资源验证

环境变量安全

强制使用 HTTPS

内容安全

注册表信任模型

注册机构运营商的最佳实践

安装前检查资源

依赖解析

基本依赖解析

高级依赖解析

分辨率如何工作

覆盖第三方资源

示例：自定义第三方按钮

高级覆盖模式

扩展而不替换

部分覆盖（多文件资源）

解析顺序示例

关键分辨率功能

版本控制

基础版本参数

动态版本选择

语义化版本控制

版本解决最佳实践

命令行接口命令

添加资源

查看资源

搜索注册表

错误处理

未配置注册表

缺少环境变量

资源未找到

认证失败

创建你自己的注册表

技术细节

解析器模式

解决过程

跨注册表依赖

最佳实践

故障排除

未找到资源

身份验证问题

依赖冲突

`{name}` 占位符（必填）

`{style}` 占位符（可选）