# @dotcom-tool-kit/circleci 中文文档

规范地址：https://npmcn.com/package/%40dotcom-tool-kit/circleci/

版本：9\.3\.1
npm 元数据更新时间：2026-10-30T14:47:09.977Z
中文译文更新时间：2026-11-13T05:39:10.553Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcom-tool-kit/circleci
原文对照：https://npmcn.com/package/%40dotcom-tool-kit/circleci/?lang=original
项目主页：https://github.com/financial-times/dotcom-tool-kit/tree/main/plugins/circleci
源码仓库：https://github.com/financial-times/dotcom-tool-kit

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

- 包体积（解压后）：141 kB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.x
- 运行依赖：10 个
- peer 依赖：zod ^3\.24\.4，dotcom-tool-kit 5\.x
- 首次发布：2021-07-01T09:38:13.746Z
- 最新版本发布：2026-10-30T14:47:09.332Z
- 近 30 天下载量：2189（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：223（近 12 个月 40 个）

## 中文简介

此插件通过工具箱管理 CircleCI 工作流程运行的工具包命令 [`Hook`](https://npmcn.com/package/%40dotcom-tool-kit/circleci/#description-hooks) 自动管理 `.circleci/config.yml`。它也会从 CircleCI 环境中暴露状态,供其他插件通用地消费.

## 安装

```sh
npm install @dotcom-tool-kit/circleci
```

也可以使用：`pnpm add @dotcom-tool-kit/circleci`、`yarn add @dotcom-tool-kit/circleci`、`bun add @dotcom-tool-kit/circleci`

## README

# @dotcom-tool-kit/循环

此插件通过工具箱管理 CircleCI 工作流程运行的工具包命令 [`Hook`](https://npmcn.com/package/%40dotcom-tool-kit/circleci/#readme-hooks) 自动管理 `.circleci/config.yml`。它也会从 CircleCI 环境中暴露状态,供其他插件通用地消费.

此插件将安装为 [集装箱资产](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/containerised-app-with-assets), (中文(简体) ), [集装箱应用](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/containerised-app), (中文(简体) ), [组件](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/component), (中文(简体) ), [循环部署](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/circleci-deploy),以及 [圆心-npm](https://github.com/Financial-Times/dotcom-tool-kit/tree/main/plugins/circleci-npm) 插件, 所以如果您正在使用其中的任何插件, 您不需要单独安装 .

## 安装

安装 `@dotcom-tool-kit/circleci` 作为 `devDependency` 在您的应用程序中:

```sh
npm install --save-dev @dotcom-tool-kit/circleci
```

将插件添加到您的 [工具箱配置](https://github.com/financial-times/dotcom-tool-kit/blob/main/readme.md#configuring-tool-kit)数字 :

```yaml
plugins:
    - '@dotcom-tool-kit/circleci'
```

并安装此插件的钩:

```sh
npx dotcom-tool-kit --install
```

## 钩子

### `CircleCi`

此钩子自动管理 `.circleci/config.yml` 在您的 Repo 为 CircleCI 工作流程提供配置,以运行工具箱命令和任务.

在您的仓库中提供的选项 `.toolkitrc.yml` 用于此钩子与任何同时为钩子提供选项的工具套件插件合并.

除非它们有冲突, 否则您的选项会被附加到插件的选项中, 允许您定义您寄存器中自定义的 CircleCI 任务和工作流程, 这些任务和工作流程与插件中的工作同步 .

#### 钩子选项

| 财产 | 说明 | 类型 |
| :-- | :-- | :-- |
| `executors` | 在生成的配置中输出额外的 CircleCI 执行器. | _对象矩阵 :_  
-   `name`数字 : `string`
-   `image`数字 : `string`

 |
| `jobs` | 在生成的配置中输出额外的 CircleCI 任务。 用于运行工具箱命令。 用于运行任意 shell 命令, 使用 `custom`。 。 。 . | _对象矩阵 :_  

-   `name`数字 : `string`
-   `command`数字 : `string`
-   `workspace`数字 : _带有属性的对象 :_
    -   `persist`数字 : `boolean`
    -   `attach`数字 : `boolean`
-   `steps`数字 : _带有属性的对象 :_
    -   `pre`数字 : `Array<string _or_ _Object with dynamic keys of type_ string _and values of type_ _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_)>`
    -   `post`数字 : `Array<string _or_ _Object with dynamic keys of type_ string _and values of type_ _Object with dynamic keys of type_ string _and values of type_ unknown (_optional & nullable_)>`
-   `splitIntoMatrix`数字 : `boolean`
-   `environment`数字 : `Record<string, string>`
-   `custom`数字 : _带有类型动态密钥的对象_ `string` _和类型值_ `unknown` (单位:千美元)_可选无效( u)_(中文(简体) )

 |
| `workflows` | 在生成的配置中输出额外的 CircleCI 工作流程。 这些参考工作定义如下: `jobs` 选项. | _对象矩阵 :_  

-   `name`数字 : `string`
-   `jobs`数字 : _对象矩阵 :_  
    -   `name`数字 : `string`
    -   `requires`数字 : `Array<string | Record<string, 'success' | 'failed' | 'canceled' | 'unauthorized' | 'not_run' | 'terminal' | Array<'success' | 'failed' | 'canceled' | 'unauthorized' | 'not_run' | 'terminal'>>>`
    -   `splitIntoMatrix`数字 : `boolean`
    -   `runOnRelease`数字 : `boolean`
    -   `custom`数字 : _带有类型动态密钥的对象_ `string` _和类型值_ `unknown` (单位:千美元)_可选无效( u)_(中文(简体) )
-   `runOnRelease`数字 : `boolean`
-   `custom`数字 : _带有类型动态密钥的对象_ `string` _和类型值_ `unknown` (单位:千美元)_可选无效( u)_(中文(简体) )

 |
| `custom` | 任意添加 CircleCI 配置,将合并到工具箱生成的配置中. | _带有类型动态密钥的对象_ `string` _和类型值_ `unknown` (单位:千美元)_可选无效( u)_(中文(简体) ) |
| `disableBaseConfig` | 设置为 `true` 以省去工具箱 CircleCI锅炉板。 应同时使用 `custom` 提供自己的锅炉板. | `boolean` |

_所有属性都是可选的._

## 全插件选项

### `@dotcom-tool-kit/circleci`

| 财产 | 说明 | 类型 | 默认 |
| :-- | :-- | :-- | :-- |
| `cimgNodeVersions` | 圆 CI 列表 [节点.js 图像版本](https://circleci.com/developer/images/image/cimg/node) 用来使用。 如果提供不止一种,a [矩阵构建](https://circleci.com/docs/using-matrix-jobs/) 将在您的 CircleCI 配置中生成. | `Array<string>` | `["20.19-browsers"]` |
| `tagFilter` | 用于匹配标签的工作的正则表达式。 默认情况下, 匹配的标签看起来像 `v1.2.3`; 如果您的发布使用不同的标签格式, 请更改此选项以匹配您的标签 。 设置为 `false` 来防止在标签上运行工作流程,例如如果您的 repo 不执行版本发布. | `string | false` | `'/^v\d+\.\d+\.\d+(-.+)?/'` |
| `checkoutMethod` | 是否检查完整的 git 寄存器或 blobless (没有与主任务无关的文件 。 ) blobless 取出是默认的, 并且更快, 尽管一些项目如果依赖于在 git 历史中检查文件, 可能会遇到问题 。 如果你看见日志像 `The authenticity of host 'github.com (140.82.113.4)' can't be established.` 您应该尝试启用全程报到. | `'full' | 'blobless'` |  |
| `orbDevVersion` | 设置此选项以使用 [开发版本](https://circleci.com/docs/orbs/author/orb-concepts/#development-orbs) 在生成的配置中设置工具箱 CircleCI 键 | `string` (单位:千美元)_正则 : `/^dev:/`_(中文(简体) ) |  |
| `useCloudsmithNpmRegistry` | 已删除: 请使用 npmCloudsmith Services Account 选项, 此选项在设定时启用 Cloudsmith | `boolean` |  |
| `npmCloudsmithServiceAccount` | 云匠服务账户。 这可能是您的团队名称, 然后是权限访问, 例如, cp 平台- read-write 。 这必须设定为从我们的私人安装或发布软件包 [云匠npm 注册](https://tech.in.ft.com/tech-topics/development-tools/package-management/cloudsmith). (注意这是和我们的多克云史密斯注册表分开的,可以配置出云史密斯插件!) | `string` |  |

_所有属性都是可选的._

## 常见问题

### @dotcom-tool-kit/circleci 是什么？

此插件通过工具箱管理 CircleCI 工作流程运行的工具包命令 Hook 自动管理 \.circleci/config\.yml。它也会从 CircleCI 环境中暴露状态,供其他插件通用地消费\.

### 如何安装 @dotcom-tool-kit/circleci？

在项目目录运行 npm install @dotcom-tool-kit/circleci，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3\.24\.4）、dotcom-tool-kit（5\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dotcom-tool-kit/circleci 支持 TypeScript 吗？

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

### @dotcom-tool-kit/circleci 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dotcom-tool-kit/circleci 需要什么版本的 Node\.js？

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

### @dotcom-tool-kit/circleci 可以商用吗？

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

### @dotcom-tool-kit/circleci 的下载量有多少？

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

### @dotcom-tool-kit/circleci 还在维护吗？

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