# @brickkit/cli 中文文档

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

版本：0\.13\.1
npm 元数据更新时间：2026-11-07T11:51:44.981Z
中文译文更新时间：2026-11-08T15:05:46.509Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brickkit/cli
原文对照：https://npmcn.com/package/%40brickkit/cli/?lang=original
项目主页：https://brickkit.dev/
源码仓库：https://github.com/get-brickkit/brick

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

- 包体积（解压后）：14.5 MB，133 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：vite ^8\.0\.0，eslint \>=9\.0\.0，oxlint \>=1\.88\.0，@mdx-js/mdx ^3\.0\.0，tailwindcss ^4\.0\.0，fumadocs-core ^16\.0\.0
- 首次发布：2026-10-07T17:38:24.986Z
- 最新版本发布：2026-11-07T11:51:44.642Z
- 近 30 天下载量：4417（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

Brick-TS 的 CLI 和服务器引擎

## 安装

```sh
npm install @brickkit/cli
```

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

## README

# @brickkit/ cli (英语)

Brick-TS框架的CLI和服务器引擎. 登山服务, 动作,以及资源作为带有 OpenAPI 3.1 的 HTTP API (Elysia) 键入, Scalar/Swagger 文档,请求伐木,和 MCP 路径.

晚点要买一分钱.

```sh
bun add @brickkit/cli @brickkit/core
```

```ts
import { brick } from "@brickkit/core";

const app = brick({ title: "Pages API", version: "1.0.0" });
app.listen(3333);
```

## 图标

每一个命令除了 `dev` 财务报告和审定财务报表 `start` 需要一个 `<entry>`: 模块 默认导出为 `BrickApp` 不调用 `.listen()`。 。 。 .

```sh
brick dev [entry] [--port 4000] [--dashboard-port 9400] [--history-days 90] [--no-dashboard]
brick start [entry] [--port 4000]
brick build <entry> [--outdir dist/brick] [--port <number>] [--no-aot]
brick worker <entry>
brick gen openapi <entry> [--output openapi.json]
brick gen client <entry> [--output _brick/contract.ts]
brick info <entry>
```

直接从注册服务构建后端 :

```ts
import { brick } from "@brickkit/core";
import { pagesService, billingService } from "./services";

const app = brick({ services: [pagesService, billingService] });
```

键入的 HTTP 客户端可以从 `@brickkit/core/client`见 [已键入客户端指南](https://brickkit.dev/docs/typed-client) 用于路由和 处理错误 .

这个 `brick` 本包中的二进制舰只,用于本地的dev和检查. `dev` 财务报告和审定财务报表 `start` 接受可选条目并解析端口 `--port`,则 `PORT`,然后4,000:

```sh
brick dev --port 4000
brick dev src/app.ts --port 4000
brick gen openapi src/app.ts --output openapi.json
brick gen client src/app.ts
brick info src/app.ts
```

资料来源: [https://github.com/get-brickkit/brick 页面存档备份,存于互联网档案馆](https://github.com/get-brickkit/brick)。 。 。 .

## 本地仪表板

`brick dev` 设有条目,也可在 `http://127.0.0.1:9400`它列出了运行中的请求,显示瀑布有: 每个请求的动作和远程呼叫跨度, 收集失败和重装, 包括启动崩溃。 直播视图在同一会话内重新启动.

请求只来自选择加入的应用程序 `telemetry: true`。 。 。 . `brick dev` 当仪表板打开时警告,但条目没有设置:

```ts
const app = brick({ services: [pagesService], telemetry: true });
```

```sh
brick dev src/app.ts                          # dashboard on 9400
brick dev src/app.ts --dashboard-port 9500    # another port
brick dev src/app.ts --history-days 30        # keep a month of requests
brick dev src/app.ts --history-days 0         # live requests only, nothing on disk
brick dev src/app.ts --no-dashboard           # API only
```

仪表盘是反应应用程序 `packages/cli/dashboard`,以 Tailwind 为样式 和阴影组件. `bun run --filter @brickkit/cli build` 把它捆起来 `dashboard-dist`, 包装( 大约 2 MB, 大部分是 API) 引用,仅在 APIs 标签打开时加载). 见 `packages/cli/dashboard/README.md`。 。 。 .

Overview 标签将应用绘制为客户端、服务和数据库的图表, 包含每个服务的动作和工具以及每个数据库的名称、引擎和 图表。 电话、时间和保健都来自最近的请求。 下边是 每一个 HTTP 路径及其动作和最近的请求和失败计数 利用它们的数据库和资源提供服务。 SQL 语句显示为子 横跨在运行它们的动作下,声明文本被悬浮。 西班牙语 按类型排列:请求、动作、服务呼叫和SQL.

APIs 选项卡将应用程序的 OpenAPI 文档与 Fumadocs OpenAPI 在 仪表板的颜色,所以应用程序没有提供自己的参考页面. 侧边栏 以标签方式列出每个文档的操作, 并带有过滤器; 打开的则显示其 参数、响应和实例请求,默认为 JavaScript `fetch`。尝试在 Playground 中通过仪表盘向应用程序发送调用 app是另一个来源),所以此调用也出现在请求标签中,并且 反应随应用程序的追踪而来(当 `telemetry` ——错误,当错误发生时,其堆栈跟踪 应用程序扔出一个, 和跨度。 仪表板只向显示的应用程序转发. 第一个文件是应用程序的,在什么时候被排除在外 `docs` 实值 `false`· ; `reference.documents` 添加更多, 每个标题和一个 OpenAPI 文档或函数返回一个(例如更好的 Auth ) `auth.api.generateOpenAPISchema()`) (中文(简体) ). 丢出的文件被跳过 警告 警告他们. `reference` 仅服务 Scalar 页 `true` 或带有 `path`。 。 。 .

Docs 标签显示应用程序的开发者文档: 由 `.md`编号 :`.mdx` fumadocs 版式中的页面( 前题, `meta.json`,文件夹组),设置为 `documentation` 打开 `brick()`它只出现在设定它的应用上 .

```ts
// src/app.ts, with the docs in docs/ at the project root
const app = brick({
  services: [pagesService],
  documentation: "../docs", // or { dir: "../docs", components: "../docs/components.tsx" }
});
```

相对路径从应用程序条目的文件夹开始, 因为他们在文件中读到: 设置它们. `fumadocs-core` 构建页面树并搜索,以及 `@mdx-js/mdx` 汇编 页面。 两者都是可选的对等方,只有在 `documentation` 设置;没有 标签上写着要安装什么(`bun add -d fumadocs-core @mdx-js/mdx`) (中文(简体) ). 保存文件更新标签 。 页面可以不用 Fumadocs 组件 导入它们( Callout、 Cards、 Tabs、 Steps、 Annions、 文件、 TypeTable、, 内置TOC, Banner),以及 `components` 命名您自己的反应组件的模块 添加,该仪表盘捆绑。 页面与本地图像之间的链接是 他们做一个文件网站。 见 `packages/cli/dashboard/README.md`。 。 。 .

对于有工作流程收听器的应用程序, Workflows 标签会显示 Workflow SDK 的 与CLI一起来的探长 因为这个应用在世界上运行 应用软件服务于一个 其自己的回转端口和仪表板在 `/workflows`。 。 。 . 它可以取消运行,所以只有 `brick dev` 只有仪表板自己的 页面可能会通过它改变任何东西.

日志标签列出哪些动作、工具和端点的日志 `ctx.logger`,以及 他们用什么印刷 `console.log`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`,以及 `debug`,最新数据 先说 下 `brick dev` 在追踪请求运行为跨度时写入行 因此,它显示在此处和请求的细节中,而不是 已打印过. `brick start` 只在应用程序设置时才做同样的 `dashboard` 选项(见下文);否则将不记录或更改任何内容,同时将两者打印为 常规。 请求外的行仍然打印。 这需要 `telemetry` 继续 线条是 截取了4000个字符 长度保持了第一个100个字符.

为了找到一条线:必须全部出现的话, `"an exact phrase"`, (中文(简体) ), `-word` 改为 留下线条,和 `level:`, (中文(简体) ), `route:`, (中文(简体) ), `action:`, (中文(简体) ), `method:`,以及 `trace:` 页:1 线条的一部份( 任何部分都可以用 `-`) (中文(简体) ). 匹配被标记, 级别 按钮计算匹配的种类, 5m / 15m / 1h 限制返回的距离, 暂停 保持名单不变。 指向一行复制,只显示其请求,或者 打开它.

请求标签是应用程序所服务的请求的日志 。 选择现场 用于本次运行,或从1小时到90天不等的回想,或自定义命名 一个开始和第二个结束(或今天,昨天,最后15分钟)。 四个 显示牌 请求的计数、出错率、中位持续时间和列表中最慢的5% 显示,所以它们会跟随范围和过滤器。 下方的时间表显示音量 左边的过滤器显示一个数 除每个值(结果、服务、方法、路线和速度 ),和搜索框匹配路线、路径、动作, 和失败信息。 每行显示时间、方法和状态、路线、长度 和处理它的行动 或它为什么失败。 打开一行看 列表外的请求 : 当它开始时, 它运行时, 它是如何结束的, 错误 并堆积追踪,如果它失败, 和它的跨度的瀑布。 导出保存 过滤请求为 CSV .

完成的请求默认保存在运行间90天的磁盘上, 以 `.brick/telemetry.sqlite` 在项目文件夹中. `.brick/` 无视自己,所以它 从来没有承诺。 历史用途 `bun:sqlite` 包和下 `node:sqlite` 下级 节点(22.5或更后);没有任何节点,仪表板只使用活数据运行 这么说的 以重启方式中断的请求无法保存 。 最多10万个 请求,放弃最老的第一。 存储请求包括期限,其中 携带 SQL 语句文本、 错误消息和堆放痕迹, 所以处理 `.brick/` 作为 你会的日志。 使用 `--history-days 0` 不留任何东西,或者 删除 `.brick/` 重新开始.

发送W3C的请求 `traceparent` 信头加入呼叫者的追踪器 仪表盘显示他们在追踪的识别码下.

### 生产监测仪表板

`brick start` 提供运行中的应用程序的只读仪表板, 从条目中默认导出,设置 `dashboard` 选项 :

```ts
export default brick({
  services,
  dashboard: {
    port: 9400, // its own port, apart from the app's
    host: "0.0.0.0", // 127.0.0.1 unless set
    auth: { token: process.env.DASHBOARD_TOKEN, authorize },
    historyDays: 0, // finished requests kept on disk, in .brick/
  },
});
```

它在自己的港口听, 所以它可以保持私人或安装在另一个港口 地址,它会回答,而应用程序的路径则不会。 它显示请求,日志, 错误、 概览和再加载; 没有重新启动、 API 代理、 API 、 Docs 或 Workflows, 以及 未提供 OpenAPI 文档 。 转弯 `telemetry` 从那时起 `ctx.logger` 财务报告和审定财务报表 `console` 请求时所写的行前往仪表板 而不是到容器的操纵台.

除了回放之外,还需要控制出入,以及 `brick start` 不运行 仪表板没有它. `auth.token` 是秘密(或数个,要旋转),至少 16个字符:浏览器在其登录的提示(任何用户名 ,并发送监视器 `Authorization: Bearer <secret>`。 。 。 . `auth.authorize(request)` 是你自己的支票,因为应用程序的认证已经 (Better Auth, Clark, a header from a 代理服务器):它得到了一个标准 `Request` 无 尸体和返回 `true`, (中文(简体) ), `false`,或一个 `Response` 例如重定向到登录 页面; 以503拒绝请求的投出或5秒无答. A 类 请求带有有效符号或当 `authorize` 允许它.

`GET /_health` 在仪表板端口上不需要签入:200,而应用程序回答 其本身 `/_health`,503 当它没有, 用于时间显示器。 答复是: `no-store`,带有严格的内容-安全政策和 `X-Frame-Options: DENY`· ; 把它交给HTTPS 失败的登录不限制速率, 因此使用长随机 标志 仪表板在应用的流程中运行: 它能活过处理者的错误, 而不是过程死去. `brick dev` 拥有自己的仪表板 并忽略选项.

仪表盘绑起 `127.0.0.1` 并拒绝其下列请求: `Host` 页眉是 不是当地人 它不记录请求的尸体或信头。 错误消息, 堆栈 痕迹,SQL语句文本可以被任何能够打开仪表板的人所看到.

## 行动路线

每个动作都暴露出一条路线: `method` 默认为 POST,以及 `path` 默认为 `/api/{service}/{action}` (或您配置的前缀). 明确 方法无论动作名称如何都会被尊重. 习惯 `path` 包含 它自己的前缀并替换默认路径。 OpenAPI 描述的相同 方法和路径,包括路径参数.

要曝光读取的动作,请声明 `method: "GET"`开始动作名称 与 `get`, (中文(简体) ), `list`, (中文(简体) ), `find`,或 `read` 不再添加获取的别名。 自定义路径无 更长的显示默认动作别名或一种附加方法。 资源 CRUD 路由保持他们的REST方法.

## 编译器

服务器为所有资源 CRUD 编译专门的 JavaScript 处理器 启动时的自定义动作、 预发文档以及缓存 OpenAPI 和 架构 JSON 有定义/端点无效。 保持生命健康 时间和时间戳。 构建一个 默认导出为 a `BrickApp` 输入一个可运行的 Bun 服务器, 使用 :

```sh
brick build src/app.ts --outdir dist/brick
bun dist/brick/server.js
```

使用相同的应用程序条目 `brick gen client`。该建筑保留其选定的 服务,前缀,docs设置,端点,和爱丽西亚钩. 保留 `.listen()` 在一个单独的服务器靴子.

这个β树枝会把爱丽西亚接上 `2.0.0-beta.29`。 。 。 . `brick build` 也预编译 Elysia 的 HTTP 处理器及其 Bun AOT 插件并删除运行时间 HTTP 编译器. 使用 `brick build src/app.ts --no-aot` 一个普通的捆绑. 发展与直接 `brick()` 调用仍然使用运行时间 HTTP 编译; 两种模式都共享相同的服务,并共享砖处理器.

## 自动输入 Vite 客户端

添加 `brickClient` 在框架插件之前。 它的条目可以是任何模块 默认导出为 `BrickApp`; 不调用构建应用程序 `.listen()` 这里:

```ts
// src/api/app.ts
import { brick } from "@brickkit/core";
import { pagesService } from "./services";

export default brick({ prefix: "/v2", services: [pagesService] });
```

```ts
// vite.config.ts
import { brickClient } from "@brickkit/cli/vite";

export default defineConfig({
  plugins: [
    brickClient({ entry: "./src/api/app.ts" }),
    // TanStack Start, React, or other framework plugins
  ],
});
```

虚拟创建 `_brick/contract.ts` 装入前端和前端 生产建设。 前缀和所选服务来自应用程序. 后端 编辑重生成文件;未修改的元数据不重写. 没有 单独生成命令或手动维护的动作列表.

```ts
// src/client.ts
import { createBrickClient } from "@brickkit/core/client";
import { contract } from "../_brick/contract";

export const api = createBrickClient({
  baseUrl: "http://localhost:8085",
  contract,
});
```

生成的文件包含传输类型和路由元数据, 没有运行时间 进口或后端处理器。 HTTP 动作按服务名称分组; 点 动作名称成为嵌入式命名空间。 资源使用他们的名字 以及他们正常的REST路线. 不包括只使用MCP的工具。 添加 `_brick/` 改为 `.gitignore`; 自定义其位置 `output` 在插件选项中.

给谭斯塔克 启动或另一个嵌入式服务器,从 `virtual:brick-app` 在服务器代码和转发请求中 `app.fetch(request)`。 。 。 . Vite 跟踪条目及其后端热重装的依赖性 。 浏览器 拒绝导入此服务器模块。 添加 `/// <reference types="@brickkit/cli/vite/client" />` 到您的虚拟环境 声明。 见 `examples/pages` (原始内容存档于2018-03-26). Fart Introduction.

期间 `vite dev` 该插件还服务于本地仪表板 `http://127.0.0.1:9400`。通过 `dashboard: { port }` 移动它或 `dashboard: false` 把它关掉. `dashboard: { historyDays }` 设定天数 将请求保留在 `.brick/` (默认 90; 0 for no). 应用程序必须保持 通过 `telemetry: true` 改为 `brick()`. TanStack Start等Dev服务器与Nitro一起运行应用程序 因此插件导入一个记者 `virtual:brick-app` 发送 工人的跨度通过回回回式HTTP到仪表板. 历史留在 维特过程和生存 工人重启。 如果采取端口, Vite 开始 没有仪表板和记录一个警告。 仪表板无法重新启动应用程序 在此模式下,它会隐藏按钮.

生成评价应用程序条目,所以它需要构建的配置 应用程序必须在开发时和建设时提供。 保留启动任务 在请求处理器或服务器中打开初始化 靴子,在应用程序定义模块之外 投入/产出类型 来自JSON运输计划; 缺少计划生产 `unknown`未解决 schema 引用和非 JSON 运输类型 故障生成明确. 此集成需要 Vite 8; 普通服务器入口没有 Vite 运行时间依赖. `generateClientContract(app)` 曝光源生成器 用于非虚拟工具.

## 生成没有 Vite 的输入客户端

使用带有默认导出为 a 的任何模块的独立 Bun CLI `BrickApp`数字 :

```sh
brick gen client src/app.ts
brick gen client src/app.ts --output frontend/src/contract.ts
```

默认输出为 `_brick/contract.ts`,相对于工作目录. 该应用程序的选定服务和前缀决定其内容,就像 维特插件. 命令在不调用的情况下评估条目 `.listen()`; 保留 在单独的服务器靴子上的听众。 不需要或装入 Vite .

重复运输类型的碎片按共享方式排放 `BrickSchema_*` 别名 当声明缩小源大小时。 名称来源于所排放的 形状,所以像字符串长度约束这样的只运行时约束不能防止 共享。 Scalars 保持内线,参考目标保留文档范围 别名; 单独文档中的等同递归图仍然分开. 这既适用于独立一代,也适用于维特一代.

在您前端的开发服务器前运行生成、 构建和类型检查, 并修改后端定义后重新运行。 您可以添加软件包脚本 :

```json
{
  "scripts": {
    "gen:client": "brick gen client src/app.ts"
  }
}
```

导入生成 `contract` 与 `createBrickClient({ baseUrl, contract })` 如上所示。 命令创建父目录并留下一个不变的 合同文件未更改。 将生成的输出添加到 `.gitignore`。 。 。 .

## 协调后端和前端开发

对于单独的前端工具,请在其编译器开始前生成合同:

```sh
brick dev src/app.ts --client frontend/src/contract.ts --frontend 'bun run --cwd frontend dev'
```

应用程序条目必须默认导出 BrickApp 而不调用 `.listen()`。 。 。 . Brick生成初始合同,启动前端命令一次 在编辑时重新启动后端。 输入条目外的本地依赖性 目录也被监视。 重新启动前更改组合; 每次重新启动评价 应用程序在新流程中,并在启动服务器前生成合同. 世代失败保留了以前的合同并打印出错误. 下一个 有效的编辑重试。 停止中 `brick dev` 停止它的后端和前端的孩子. 当你停下来 `brick dev` 随着Ctrl-C或它重新装入,后端首先完成在飞行中事件交付(最多为3秒);一次第二个Ctrl-C出站. 在Windows上,停止或重新加载后端会强制终止它,因此飞行中的事件交付可能会被中断. `--client` 也工作没有 `--frontend` 如果另一个进程拥有前端.

对于Pages等嵌入式Vite应用程序,请继续使用 `brickClient` 内 `vite.config.ts`。 。 。 . Vite拥有后端加载和前端启动在那个设置中. 它会生成之前 启动和生产编译,重新加载应用程序定义图,包括导入的服务例,并通过其终端和浏览器覆盖报告生成错误. 错误发生后有效的编辑重生合同 。 两者结合在解剖学上都是 替换已更改的合同并保存未更改的文件,因此只执行 编辑不会触发前端合同更新. 生成的文件不包括在 复生触发.

用于非Vite生产建筑和类型检查,运行 `brick gen client` 作为第一个 命令。 它使用相同的发电机和原子 作家作为发展。 在应用程序定义之外保留启动的工作和听众, 因为所有世代的路径都评价这个条目.

## 常见问题

### @brickkit/cli 是什么？

Brick-TS 的 CLI 和服务器引擎

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

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

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

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

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

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

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

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

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

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

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

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