# @deltabox/toolchain 中文文档

规范地址：https://npmcn.com/package/%40deltabox/toolchain/

版本：2\.6\.1
npm 元数据更新时间：2026-11-06T05:48:08.072Z
中文译文更新时间：2026-11-11T21:54:28.566Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：3.4 MB，352 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.5\.0
- 运行依赖：11 个
- peer 依赖：eslint \>=9，prettier \>=3，vite-plus \>=1，@dprint/types \>=0\.4
- 首次发布：2026-10-15T21:39:19.857Z
- 最新版本发布：2026-11-06T05:48:07.769Z
- 近 30 天下载量：6078（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

全一开发工具链,让您脚手架项目,生成和管理配置,tsconfigs,自定义模板,同步,更改日志,CI,Vite+,迁移等等.

## 安装

```sh
npm install @deltabox/toolchain
```

也可以使用：`pnpm add @deltabox/toolchain`、`yarn add @deltabox/toolchain`、`bun add @deltabox/toolchain`

## README

![](https://npmcn.com/package/%40deltabox/toolchain/apps/docs/public/logo/logo.svg)

# 三角盒工具链

[![license: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://npmcn.com/package/%40deltabox/toolchain/package.json) [![tests](https://img.shields.io/github/actions/workflow/status/deltabox-studio/toolchain/ci.yml?label=tests&logo=github)](https://github.com/deltabox-studio/toolchain/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@deltabox/toolchain.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/@deltabox/toolchain)

全一开发工具链,让您脚手架项目,生成和管理配置,tsconfigs,自定义模板,同步,更改日志,CI,Vite+,迁移等等.

-   **保存和使用模板(本地/远程)** 所以,你不用脚手架 相同的项目一遍又一遍.
-   **生成** 配置类型, env变量, cli 旗帜, markdown 和 JSON schemas, 所以您的代码库保持一致性, 验证和有详细记录 .
-   **扩展或设置** 您的更改日志、 发布、 问题等的CI .
-   **同步** 您的整个项目,所以工作空间,文档和CI总是最新的.
-   **插入 Vite / Vite+** 并精简您当前 Vite 设置的 DX .

见 [特征清单](https://npmcn.com/package/%40deltabox/toolchain/#readme-features)。 。 。 .

见 [变动情况](https://npmcn.com/CHANGELOG.md) 用于更新.

文件、指南和实例 [工具链.deltabox.studio](https://toolchain.deltabox.studio/guide)。 。 。 .

下面的视频和截图是VS代码扩展. 更多关于它的 [工具链.deltabox.studio/指针/vscode](https://toolchain.deltabox.studio/guide/vscode)。 。 。 .

[https://github.com/user-attachments/assets/a4f1ad75-fedd-40ee-b84d-3365f7025a3e 互联网档案馆的存檔,存档日期2013-12-2](https://github.com/user-attachments/assets/a4f1ad75-fedd-40ee-b84d-3365f7025a3e)

![](https://npmcn.com/package/%40deltabox/toolchain/apps/docs/public/vscode-screenshot.png)

## 目录

-   [三角盒工具链](https://npmcn.com/package/%40deltabox/toolchain/#readme-deltabox-toolchain)
    -   [目录](https://npmcn.com/package/%40deltabox/toolchain/#readme-table-of-contents)
    -   [特征](https://npmcn.com/package/%40deltabox/toolchain/#readme-features)
    -   [安装](https://npmcn.com/package/%40deltabox/toolchain/#readme-install)
    -   [快速启动](https://npmcn.com/package/%40deltabox/toolchain/#readme-quickstart)
    -   [配置生成器](https://npmcn.com/package/%40deltabox/toolchain/#readme-config-generator)
    -   [Vite / Vite+ 插件](https://npmcn.com/package/%40deltabox/toolchain/#readme-vite--vite-plugin)
    -   [国 际](https://npmcn.com/package/%40deltabox/toolchain/#readme-cli)
    -   [程序化 API](https://npmcn.com/package/%40deltabox/toolchain/#readme-programmatic-api)
    -   [VS 代码扩展](https://npmcn.com/package/%40deltabox/toolchain/#readme-vs-code-extension)
    -   [发展](https://npmcn.com/package/%40deltabox/toolchain/#readme-development)
    -   [文档](https://npmcn.com/package/%40deltabox/toolchain/#readme-docs)
    -   [许可证](https://npmcn.com/package/%40deltabox/toolchain/#readme-license)

## 特征

-   **配置驱动**
-   **配置生成器**
-   **Vite / Vite+ 插件**
-   **更改日志发布( L)**
-   **tsconfig 生成**
-   **供应商**
-   **模板**
-   **移徙**
-   **先编辑**
-   **摩诺雷波意识到**
-   **自动同步**

详见 [工具链.deltabox.studio](https://toolchain.deltabox.studio/)。 。 。 .

## 安装

```sh
# as a dev dependency in the project you want to manage
yarn add -D @deltabox/toolchain

# or for global usage
npm install -g @deltabox/toolchain
```

包裹暴露了一个二进制, `dbx`数字 :

```sh
yarn dbx --help
```

## 快速启动

```sh
# 1. Write a dbx.config.ts for the current project
dbx project:config

# 2. Generate / refresh every managed file (adds .dbx/toolchain/manifest.json)
dbx sync

# 3. Verify in CI — fails when files are out of date
dbx sync --check
```

最小配置 :

```ts
import { defineConfig } from '@deltabox/toolchain';

export default defineConfig({
    toolchain: {
        project: { type: 'monorepo-root', name: 'acme', scope: '@acme' },
        changelog: { workflows: { ci: true, release: true } },
        tsconfig: { refs: true },
        biome: true,
        vite: { fmt: { semi: true, singleQuote: true } },
    },
});
```

这个 `@deltabox/toolchain` 设置在 `toolchain` 键。 每个区 还有 **通过存在选择进入**数字 : `section: true` 以便它以缺省的形式出现, `section: false` 关闭它,并 `section: { ... }` 配置它. 见 [配置参考](https://toolchain.deltabox.studio/config/reference)。 。 。 .

## 配置生成器

同样的"Zod-First"(Zod-First approach)赋予了独立配置引擎的权力. 说说你的 配置一次并生成 `.env.example`一个JSON Schema,一个打分参考,TS 类型和来自它的CLI旗帜——没有手持可漂移的文件:

```ts
import { z } from 'zod';

import { createConfigEngine } from '@deltabox/toolchain/config';

export const engine = createConfigEngine({
    scopes: {
        server: {
            zodSchema: z.object({
                port: z.number().default(3000).meta({ env: 'MYAPP_PORT' }),
            }),
        },
    },
    envPrefix: 'MYAPP_',
    baseGroup: 'base',
    root: process.cwd(),
});

await engine.writeJsonSchema({ output: 'config.schema.json' });
engine.writeEnvFile({ output: '.env.example' });
engine.writeMarkdown({ outDir: 'docs/reference/configuration' });
```

它还生成 TypeScript 类型——与 jsdoc 从 `.describe()`,其中结合物和嵌入物保持名称而不是 内嵌 :

```ts
engine.writeConfigTypes({ outputDir: 'types' });
```

```ts
// types/server.ts
export interface ServerConfig {
    /** HTTP port. */
    port?: number;
}
```

在运行时间,同一个包装回—— `parseEnvTree` 折叠 `PREFIX_*` 变量输入一棵树,输入的存取器读取它(schema验证只是 (单位:千美元) `.parse()` 离开:

```ts
import { envInt, envString, parseEnvTree } from '@deltabox/toolchain/config';

const tree = parseEnvTree(process.env, 'MYAPP_');
const port = envInt(tree, 'port', 3000);
const host = envString(tree, 'host', '0.0.0.0');
```

见 [配置生成器 指南](https://toolchain.deltabox.studio/guide/config-generator) 装入, 超越并验证配置 .

工具链以这种方式生成自己的配置类型——见 `packages/shared/src/config-types.ts` 编辑 [配置生成器 指南](https://toolchain.deltabox.studio/guide/config-generator#generated-outputs)。 。 。 .

`configCommands({ engine })` 也暴露了与 `config:*` 命令您自己的 CLI。 见 [配置生成器 指南](https://toolchain.deltabox.studio/guide/config-generator)。 。 。 .

## Vite / Vite+ 插件

`@deltabox/toolchain` 船载 Vite 插件, 因此 Vite( 或 Vite+) 项目可以运行 dbx 作为其管道的一部分——没有单独的 `dbx sync` 步骤 :

```ts
// vite.config.ts
import { defineConfig } from 'vite'; // or 'vite-plus'

import { dbx, DBX_TASKS } from '@deltabox/toolchain/vite';

export default defineConfig({
    plugins: [dbx()],
    run: { tasks: { ...DBX_TASKS } },
    // your usual Vite / Vite+ config
});
```

-   这个 `dbx()` 插件运行 `dbx sync` 在 dev 服务器/ 构建之前, 或 `dbx sync --check` 在 CI 中( 当生成文件退出时, 构建失败) 日期),当 a `dbx.config.*` 编号 : `tsconfig.*.json` 输入变化.
-   `run: { tasks: { ...DBX_TASKS } }` 额外暴露 `vp run dbx:sync` 编号 : `vp run dbx:check` (视频+读取) `run.tasks` 从静态配置中 插件无法添加). 放下枪 `run` 如果您不想完成这些任务, 则屏蔽 .

见 [提供者指南](https://toolchain.deltabox.studio/guide/providers)。 。 。 .

## 国 际

访问 [CLI 文档](https://toolchain.deltabox.studio/guide/cli) 学习更多.

注意: 与工程相撞并装入其命令 `dbx.config.ts` 首先,这样 除非在命令行上被推翻,否则将适用由配置产生的默认值.

## 程序化 API

```ts
import { defineConfig, loadToolchainConfig, runSync, defaultSyncTasks } from '@deltabox/toolchain';

const { config, tokens, projectType } = await loadToolchainConfig(process.cwd());
await runSync({ tasks: defaultSyncTasks(), cwd: process.cwd(), config, tokens, projectType });
```

## VS 代码扩展

下载自 [视觉工作室代码市场](https://marketplace.visualstudio.com/items?itemName=deltabox.toolchain-vscode)。 。 。 .

或通过国家行动倡议:

```sh
code --install-extension deltabox.toolchain-vscode
```

见 [软件包/vscode/README.md](https://npmcn.com/package/%40deltabox/toolchain/packages/vscode/README.md) 学习更多如何运作.

## 发展

这个Repo是Yarn 4工作空间. 维特+ (`vp`) 驱动格式、线程、测试和 从根中执行任务 `vite.config.ts`生成的him被狗吃掉了 与 `vite.shim: 'static'`这样 `vp` 在没有已建软件包的情况下装入; Vite 和 通过 Vitest 解析工作空间导入 `resolve.tsconfigPaths`。 。 。 .

```sh
yarn install        # fresh checkout
yarn dev            # run the CLI from src/ via tsx
yarn typecheck      # packages + root
yarn check          # Oxfmt + Oxlint check (no writes)
yarn check:fix      # same, auto-fixing every workspace + the root
yarn format         # `vp fmt`
yarn lint           # `vp lint --fix`
yarn build          # packages via `vp run` + root tsdown
yarn test           # builds, then package + root tests
yarn test:clean     # remove leftover emulation temp workspaces
```

> `vp` 只在还原根中解决,所以从根中运行这些。 满 `yarn build` 仅供出版时使用 `dist`/VSIX: 类型检查, `vp run`编号 :`fmt`编号 :`lint`编号 :`test`, (中文(简体) ), `yarn dev` 维特从源头逃出 这个 模拟套接字生成已建 `dist/cli/index.js` 因此,需要建立一个 建设.

VS码扩展的单元测试与root Vitest套件一起运行. 内容 集成套件启动一个真正的扩展主机 (单位:千美元)`yarn workspace toolchain-vscode test:integration`); CI 在 Xvfb 下运行 页:1 `vscode-integration` 任务之后 `ci`。在 Windows 上,它无法在 VS 代码时运行 稳定是开放的.

医生住在这里 `apps/docs` (视频): `yarn docs build`。 。 。 .

## 文档

完整文档、指南和实例 [工具链.deltabox.studio](https://toolchain.deltabox.studio/guide)。 。 。 .

源页面在 `apps/docs`。 。 。 .

## 许可证

[MPL - 2.0 导弹](https://npmcn.com/package/%40deltabox/toolchain/LICENSE) 三角形框

![](https://npmcn.com/package/%40deltabox/toolchain/apps/docs/public/logo/outline_colored.svg)

## 常见问题

### @deltabox/toolchain 是什么？

全一开发工具链,让您脚手架项目,生成和管理配置,tsconfigs,自定义模板,同步,更改日志,CI,Vite\+,迁移等等\.

### 如何安装 @deltabox/toolchain？

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

### @deltabox/toolchain 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/deltabox\_\_toolchain 是否存在。

### @deltabox/toolchain 支持 ESM 还是 CommonJS？

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

### @deltabox/toolchain 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.5\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deltabox/toolchain 可以商用吗？

@deltabox/toolchain 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @deltabox/toolchain 的下载量有多少？

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

### @deltabox/toolchain 还在维护吗？

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