# @buildpad/cli 中文文档

规范地址：https://npmcn.com/package/%40buildpad/cli/

版本：3\.7\.0
npm 元数据更新时间：2026-11-06T09:05:07.362Z
中文译文更新时间：2026-11-09T00:39:03.968Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buildpad/cli
原文对照：https://npmcn.com/package/%40buildpad/cli/?lang=original
项目主页：https://github.com/buildpad-ai/ui#readme
源码仓库：https://github.com/buildpad-ai/ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，119 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-02-27T08:45:01.970Z
- 最新版本发布：2026-11-06T09:05:07.172Z
- 近 30 天下载量：1901（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

用于在您的工程中添加 Buildpad 组件的 CLI 工具 - 如 shadcn/ ui

## 安装

```sh
npm install @buildpad/cli
```

也可以使用：`pnpm add @buildpad/cli`、`yarn add @buildpad/cli`、`bun add @buildpad/cli`

## README

# @ buildpad/ cli (中文(简体) )

在您的工程中添加 Buildpad 组件的 CLI .

[![npm version](https://img.shields.io/npm/v/@buildpad/cli)](https://www.npmjs.com/package/@buildpad/cli)

## 使用量

使用 `init` 命令来设置新工程和 `add` 命令以添加组件.

```bash
npx @buildpad/cli init
npx @buildpad/cli add input select-dropdown
```

## 输入

使用 `init` 命令以初始化新工程的配置和依赖.

这个 `init` 命令创建一个 `buildpad.json` 文件,设置目录结构,并检查所需的依赖性.

```bash
npx @buildpad/cli init
```

### 选项

```
Usage: buildpad init [options]

initialize your project and install dependencies

Options:
  -y, --yes       skip confirmation prompt (default: false)
  -c, --cwd <cwd> the working directory (defaults to current directory)
  -h, --help      display help for command
```

## 添加

使用 `add` 命令将添加组件到您的工程中.

```bash
npx @buildpad/cli add [component]
```

### 选项

```
Usage: buildpad add [options] [components...]

add components to your project

Arguments:
  components         name of components to add

Options:
  -a, --all          add all available components (default: false)
  --with-api         also add API routes and Supabase auth templates
  --category <name>  add all components from a category
  -o, --overwrite    overwrite existing files (default: false)
  -n, --dry-run      preview changes without modifying files
  --cwd <cwd>        the working directory (defaults to current directory)
  -h, --help         display help for command
```

### 实例

```bash
# Add specific components
npx @buildpad/cli add input
npx @buildpad/cli add input select-dropdown datetime

# Add collection-form (includes VForm + all 32 interface components)
npx @buildpad/cli add collection-form

# Add all components from a category
npx @buildpad/cli add --category selection

# Add all components
npx @buildpad/cli add --all
```

## 列表

使用 `list` 命令以查看所有可用的组件.

```bash
npx @buildpad/cli list
```

### 选项

```
Usage: buildpad list [options]

list available components

Options:
  --category <name>  filter by category
  --json             output as JSON
  -h, --help         display help for command
```

## 拖带

使用 `bootstrap` 命令用于在单一的非交互命令中设置完整的项目。 建议使用AI剂和CI/CD管道.

```bash
npx @buildpad/cli bootstrap
```

### 选项

```
Usage: buildpad bootstrap [options]

Full project setup: init + add --all + install deps + validate (single command for AI agents)

Options:
  --cwd <cwd>          the working directory (defaults to current directory)
  --skip-deps          skip npm dependency installation
  --skip-validate      skip post-install validation
  --locales <codes>    locales for app/[lang], comma-separated (e.g. en,id); default: en
  --default-locale <code>  default locale (must be in --locales); default: the first one
  -h, --help           display help for command
```

### 诱饵会做什么

1.  创建 `buildpad.json` 和项目骨架(package.json、tsconfig、 `app/[lang]` root 版式和主页、 设计符号、 语言路由 `lib/i18n/`(中文(简体) )
2.  复制全部 40+ UI 组件到 `components/ui/`
3.  复制类型、服务、钩子 `lib/buildpad/`
4.  复制 API 代理路由( 域、 项、 关系、 文件)
5.  复制认证代理路由( 登录、 登录、 用户、 回调) + 登录页面
6.  副本 Supabase auth 公用事业和中间软件
7.  运行 `pnpm install` 解决所有依赖关系
8.  验证安装

**Auth 路由已安装 :**

| 路线 | 方法 | 目的 |
| --- | --- | --- |
| `/api/auth/login` | 邮政 | 通过 Supabase Auth 登录(服务器侧,无 CORS) |
| `/api/auth/logout` | 邮政 | 签名并清除会话 cookie |
| `/api/auth/user` | 获取 | 获取当前用户配置 |
| `/api/auth/callback` | 获取 | 处理 OAuth/电子邮件确认方向 |
| `/app/[lang]/login/page.tsx` | —— 说 | 使用代理模式( 本地前缀) 登录页面 |

## 验证

使用 `validate` 命令来检查您的 Buildpad 安装是否用于常见问题.

```bash
npx @buildpad/cli validate
```

### 选项

```
Usage: buildpad validate [options]

validate Buildpad installation (check imports, missing files, SSR issues)

Options:
  --json           output as JSON for CI/CD
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

### 它检查什么

-   **未转换进口** - 说吧 `@buildpad/*` 未转换到本地路径的导入
-   **缺少 lib 文件** - 所需通用模块没有(类型、服务、钩子、提款机)
-   **缺少 CSS 文件** - 丰富的文本编辑器所需的CSS(RichTextHTML.cs,IntentBlock编辑器.cs)
-   **安全部门改革问题** - 诸如InvolutBlock编辑器等组件,在没有SSR安全包装器的情况下导出
-   **API 路由缺失** - 田地、物品、许可的DaaS集成路线

### 示例输出

```
✗ Found 2 error(s):

  ✗ src/components/ui/input.tsx:5
    Untransformed import: import { Field } from '@buildpad/types';

  ✗ lib/buildpad/interface-registry.ts
    Missing required file for utils module

⚠ Found 1 warning(s):

  ⚠ components/ui/index.ts
    InputBlockEditor exported directly may cause SSR errors. Use input-block-editor-wrapper instead.

💡 Suggestions:

  1. Fix 2 untransformed import(s) by running: pnpm cli add --all --overwrite --cwd .
  2. Update components/ui/index.ts to export InputBlockEditor from './input-block-editor-wrapper'
```

## 微调

使用 `diff` 命令在添加组件之前预览更改.

```bash
npx @buildpad/cli diff [component]
```

### 选项

```
Usage: buildpad diff [options] <component>

preview changes before adding a component

Options:
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

## 状态

使用 `status` 命令以查看所有已安装的 Buildpad 组件及其来源.

```bash
npx @buildpad/cli status
```

### 选项

```
Usage: buildpad status [options]

show installed Buildpad components and their origins

Options:
  --json           output as JSON
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

### 示例输出

```
📦 Buildpad Status

Config file: buildpad.json
Lib modules: types, hooks, services
Components:  input, select-dropdown, list-m2m

Installed Files:

  @buildpad/ui-interfaces/input
    └─ src/components/ui/input.tsx
       v1.0.0 (2026-01-12)

  @buildpad/lib/hooks
    └─ src/lib/buildpad/hooks/useRelationM2M.ts
       v1.0.0 (2026-01-12)

Total: 15 files from Buildpad
```

## buildpad.json (英语)

这个 `buildpad.json` 文件持有您的工程配置 。 我们用它来理解您的项目是如何设置的,以及如何为您的项目定制组件.

您可以创建 `buildpad.json` 通过运行 `init` 命令.

```json
{
  "$schema": "https://buildpad.dev/schema.json",
  "model": "copy-own",
  "tsx": true,
  "srcDir": true,
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/buildpad"
  },
  "installedLib": [],
  "installedComponents": []
}
```

### tx

在 TypeScript 或 JavaScript 组件中选择 .

设置此选项为 `false` 允许以 JavaScript 添加组件 `.jsx` 文件扩展名.

```json
{
  "tsx": true | false
}
```

### 曲线

您的项目是否使用 `src/` 目录结构.

```json
{
  "srcDir": true | false
}
```

### 别名

CLI使用这些值将生成的组件放入正确的位置.

```json
{
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/buildpad"
  }
}
```

您必须设置路径别名 `tsconfig.json` 或者说 `jsconfig.json` 文件 :

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

### 安装了Lib和安装了组件

这些阵列跟踪已安装的东西 。 CLI使用它们来避免重置依赖关系.

## 获得什么复制

当添加组件时, CLI :

1.  **复制组件来源** 转到您的组件目录
2.  **需要复制的 lib 模块** (类型、服务、钩子)
3.  **转变进口** 从 `@buildpad/*` 转到本地路径
4.  **缺少依赖关系的报告** 需要安装的

### 示例:添加 `list-m2m`

```bash
npx @buildpad/cli add list-m2m
```

此副本:

-   `components/ui/list-m2m.tsx` - 构成部分
-   `lib/buildpad/types/` - 类型定义
-   `lib/buildpad/services/` - CRUD服务
-   `lib/buildpad/hooks/` - 反应钩

### 导入转换

原件(来源):

```tsx
import { useRelationM2M } from '@buildpad/hooks';
import type { M2MItem } from '@buildpad/types';
```

已转换( 在您的工程中) :

```tsx
import { useRelationM2M } from '@/lib/buildpad/hooks';
import type { M2MItem } from '@/lib/buildpad/types';
```

## 构成部分类别

| 类别 | 构成部分 |
| --- | --- |
| `input` | 输入、 文本区域、 输入代码、 输入锁定编辑器、 标记 |
| `selection` | 选择Dropdown、SecretRadio、SectoMultipleCheckbox、SectoIcon、自动完成API、收集项目Dropdown |
| `datetime` | 日期时间 |
| `boolean` | 布尔, 切换 |
| `media` | 文件界面、 文件图像、 文件、 上传、 颜色 |
| `relational` | 列表M2M, 列表M2O, 列表O2M, 列表M2A |
| `layout` | 分割器、 通知、 分类 |
| `rich-text` | RichTextHtml, RichTextMarkdown 软件 |
| `collection` | VForm, 收藏工具, 收藏列表 |

### VForm 和收藏工具

添加时 `collection-form`,自动包括:

-   **表格** - 使任何字段类型的动态形式组件
-   **32个接口组件** - 所有外地类型(输入、选择、日期、M2M、M2O等)
-   **幻灯片模块** - 类型、服务、接线和外地接口公用事业

这是因为 `collection-form` 已经 `registryDependencies: ["vform"]` vForm 对所有接口组件都有依赖性.

## 同伴依赖关系

部件需要这些外部包:

**核心(随时需要):**

```bash
pnpm add @mantine/core @mantine/hooks react react-dom
```

**具体构成部分:**

```bash
# DateTime component
pnpm add @mantine/dates dayjs

# Icon components
pnpm add @tabler/icons-react

# File upload
pnpm add @mantine/dropzone

# CollectionForm notifications
pnpm add @mantine/notifications

# Rich text editor
pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-link
```

**Utils( 可选的, 对于 cn () 帮助 ):**

```bash
pnpm add clsx tailwind-merge
```

## 安装后的项目结构

```
your-project/
├── app/
│   ├── api/
│   │   ├── auth/                        # Auth proxy routes
│   │   │   ├── login/route.ts           # POST - Supabase login
│   │   │   ├── logout/route.ts          # POST - Sign out
│   │   │   ├── user/route.ts            # GET - Current user info
│   │   │   └── callback/route.ts        # GET - OAuth callback
│   │   ├── fields/[collection]/route.ts # Fields proxy
│   │   ├── items/[collection]/route.ts  # Items proxy
│   │   └── ...
│   └── login/page.tsx                   # Login page template
├── src/
│   ├── components/
│   │   └── ui/
│   │       ├── input.tsx
│   │       ├── select-dropdown.tsx
│   │       └── datetime.tsx
│   └── lib/
│       ├── buildpad/
│       │   ├── utils.ts
│       │   ├── types/
│       │   │   ├── index.ts
│       │   │   ├── core.ts
│       │   │   ├── file.ts
│       │   │   └── relations.ts
│       │   ├── services/
│       │   │   ├── index.ts
│       │   │   ├── api-request.ts
│       │   │   ├── items.ts
│       │   │   ├── fields.ts
│       │   │   └── collections.ts
│       │   └── hooks/
│       │       ├── index.ts
│       │       ├── useRelationM2M.ts
│       │       ├── useRelationM2O.ts
│       │       └── ...
│       ├── api/auth-headers.ts          # Auth header utilities
│       └── supabase/                    # Supabase client utilities
│           ├── server.ts
│           └── client.ts
├── middleware.ts                         # Auth middleware
├── buildpad.json
└── package.json
```

## CLI 命令参考

```bash
# Initialize project
buildpad init [--yes] [--cwd <path>] [--locales en,id] [--default-locale en]

# Bootstrap full project (init + add all + deps + validate)
buildpad bootstrap [--cwd <path>] [--skip-deps] [--skip-validate] [--locales en,id] [--default-locale en]

# Move an app scaffolded before 2.3 onto locale-prefixed app/[lang] routing
buildpad migrate i18n [--cwd <path>] [--locales en,id] [--dry-run]

# Add components
buildpad add [components...] [--all] [--category <name>] [--overwrite] [--cwd <path>]

# List components
buildpad list [--category <name>] [--json]

# Preview changes
buildpad diff <component> [--cwd <path>]

# Validate installation
buildpad validate [--json] [--cwd <path>]

# Check installed components
buildpad status [--json] [--cwd <path>]

# Component info and dependency tree
buildpad info <component> [--json]
buildpad tree <component> [--json] [--depth <n>]

# Auto-fix common issues
buildpad fix [--dry-run] [--yes] [--cwd <path>]

# Check for component updates
buildpad outdated [--json] [--cwd <path>]
```

## 解决问题

### 找不到注册文件

确定您正在运行 Buildpad 工作空间中的 CLI , 或者对注册进行适当的配置 .

### "没有找到buildpad.json"

运行 `npx @buildpad/cli init` 首先初始化您的项目 .

### 添加组件后导入出错

保证您 `tsconfig.json` 有正确的路径别名 :

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

## 发展

构建 CLI :

```bash
cd packages/cli
pnpm build
```

开发中运行 :

```bash
pnpm dev
```

本地测试 :

```bash
node dist/index.js init
node dist/index.js add input
```

## 许可证

麻省理工学院

## 常见问题

### @buildpad/cli 是什么？

用于在您的工程中添加 Buildpad 组件的 CLI 工具 - 如 shadcn/ ui

### 如何安装 @buildpad/cli？

在项目目录运行 npm install @buildpad/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 buildpad，可以用 npx buildpad 直接运行。

### @buildpad/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buildpad/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @buildpad/cli 可以商用吗？

@buildpad/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buildpad/cli 的下载量有多少？

根据 npm 官方下载统计，@buildpad/cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,901 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buildpad/cli 还在维护吗？

最新版本 3\.7\.0 发布于 2026/11/06（3 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/02/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。