Acme

维护指南

客户端配置指南

详细的客户端项目配置指南，包含完整示例和最佳实践

本文档展示如何在客户端 Next.js 项目中配置并使用私有 Registry。

前置条件

  • 已获取 Registry 访问令牌（REGISTRY_TOKEN）
  • 已安装 shadcn CLI：npm install -g shadcn@latest

步骤 1：初始化 shadcn/ui

如果是新项目，先初始化 shadcn/ui：

  pnpm dlx shadcn@latest init
  npx shadcn@latest init
  bun shadcn@latest init

选择你的配置选项（样式、主题等）。

步骤 2：配置私有 Registry

2.1 更新 components.json

在项目根目录的 components.json 中添加私有 Registry：

components.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@acme": {
      "url": "https://your-domain.com/api/registry/{name}",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  },
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

2.2 配置环境变量

创建 .env.local 文件（如果不存在）：

.env.local
# Private Registry Authentication
REGISTRY_TOKEN=your_access_token_here

确保将 .env.local 添加到 .gitignore，避免泄露令牌！

步骤 3：安装组件

3.1 从私有 Registry 安装

# 安装单个组件
npx shadcn@latest add @acme/button

# 安装多个组件
npx shadcn@latest add @acme/button @acme/card @acme/input

3.2 混合使用公共和私有 Registry

你可以同时使用公共 shadcn Registry 和私有 Registry：

components.json
{
  "registries": {
    "@shadcn": "https://ui.shadcn.com/r/{name}.json",
    "@acme": {
      "url": "https://your-domain.com/api/registry/{name}",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

安装时指定来源：

# 从公共 Registry 安装
npx shadcn@latest add @shadcn/dialog

# 从私有 Registry 安装
npx shadcn@latest add @acme/custom-form

步骤 4：使用组件

安装后，组件会被复制到你的项目中，你可以直接导入使用：

app/page.tsx
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"

export default function Home() {
  return (
    <div className="p-8">
      <Card className="p-6">
        <h1 className="text-2xl font-bold mb-4">Hello from Acme Registry</h1>
        <Button>Click me</Button>
      </Card>
    </div>
  )
}

完整配置示例

项目结构

my-app/
├── .env.local                    # 环境变量（包含 REGISTRY_TOKEN）
├── .gitignore                    # 确保包含 .env.local
├── components.json               # shadcn 配置
├── package.json
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── components/
│   └── ui/                       # 安装的组件会在这里
│       ├── button.tsx
│       └── card.tsx
└── lib/
    └── utils.ts

components.json 完整示例

components.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@shadcn": "https://ui.shadcn.com/r/{name}.json",
    "@acme": {
      "url": "https://registry.acme.com/api/registry/{name}",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    },
    "@acme-internal": {
      "url": "https://internal.acme.com/api/registry/{name}",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}",
        "X-Workspace-Id": "${WORKSPACE_ID}"
      }
    }
  },
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

.env.local 完整示例

.env.local
# Private Registry Authentication
REGISTRY_TOKEN=abc123def456...

# Internal Registry (Optional)
INTERNAL_TOKEN=xyz789...
WORKSPACE_ID=workspace_123

.gitignore 检查

确保 .gitignore 包含：

.gitignore
# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

CI/CD 配置

GitHub Actions

在 GitHub Actions 中配置环境变量：

  1. 进入仓库设置 → Secrets and variables → Actions
  2. 添加 REGISTRY_TOKEN secret
  3. 在 workflow 中使用：
.github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        env:
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: |
          npm install
          npx shadcn@latest add @acme/button --yes

      - name: Build
        run: npm run build

Vercel

在 Vercel 项目设置中：

  1. 进入 Settings → Environment Variables
  2. 添加 REGISTRY_TOKEN
  3. 选择环境（Production, Preview, Development）

常见问题

Q: 安装时提示 401 Unauthorized

原因： 令牌无效或未设置环境变量

解决方案：

# 检查环境变量
echo $REGISTRY_TOKEN

# 重新加载环境变量
source .env.local

# 或重启终端

Q: 能否在不同环境使用不同令牌？

可以！ 使用不同的环境变量文件：

# 开发环境
.env.local

# 生产环境
.env.production.local

# 测试环境
.env.test.local

Q: 团队成员如何获取令牌？

建议流程：

  1. 管理员生成令牌
  2. 通过安全渠道分享（如 1Password、LastPass）
  3. 团队成员添加到自己的 .env.local
  4. 定期轮换令牌

Q: 如何在 Monorepo 中使用？

在 monorepo 中，每个包可以有自己的 components.json：

monorepo/
├── apps/
│   ├── web/
│   │   ├── .env.local
│   │   └── components.json
│   └── admin/
│       ├── .env.local
│       └── components.json
└── packages/
    └── ui/
        └── components.json

或在根目录共享配置：

package.json
{
  "scripts": {
    "ui:add": "cd packages/ui && shadcn add"
  }
}

最佳实践

环境变量管理

✅ 推荐：

  • 使用 .env.local 存储开发令牌
  • 在 CI/CD 中加密存储生产令牌
  • 定期轮换令牌

❌ 避免：

  • 将令牌提交到 Git
  • 在代码中硬编码令牌
  • 在日志中打印令牌

组件安装

✅ 推荐：

  • 明确指定 Registry 命名空间
  • 记录安装的组件列表
  • 定期更新组件

❌ 避免：

  • 手动修改已安装组件（会在更新时丢失）
  • 混淆不同 Registry 的组件

团队协作

✅ 推荐：

  • 文档化 Registry 配置
  • 提供令牌获取流程
  • 统一团队配置

❌ 避免：

  • 在公共渠道分享令牌
  • 使用过期或无效令牌

相关资源

需要帮助？ 联系团队管理员或查看故障排查指南。

维护指南

了解如何部署、配置和维护私有组件注册表

组件预览

如何在文档中使用 ComponentPreview 和 ComponentSource 组件

On this page

前置条件步骤 1：初始化 shadcn/ui步骤 2：配置私有 Registry2.1 更新 components.json2.2 配置环境变量步骤 3：安装组件3.1 从私有 Registry 安装3.2 混合使用公共和私有 Registry步骤 4：使用组件完整配置示例项目结构components.json 完整示例.env.local 完整示例.gitignore 检查CI/CD 配置GitHub ActionsVercel常见问题Q: 安装时提示 401 UnauthorizedQ: 能否在不同环境使用不同令牌？Q: 团队成员如何获取令牌？Q: 如何在 Monorepo 中使用？最佳实践环境变量管理组件安装团队协作相关资源