# @code-pushup/ci 中文文档

规范地址：https://npmcn.com/package/%40code-pushup/ci/

版本：0\.126\.4
npm 元数据更新时间：2026-09-11T10:13:41.417Z
中文译文更新时间：2026-11-10T06:00:18.242Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：166 kB，101 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2024-10-16T08:59:43.922Z
- 最新版本发布：2026-09-11T10:13:41.065Z
- 近 30 天下载量：8797（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：119（近 12 个月 62 个）

## 中文简介

代码 PushUp 的 CI 自动化逻辑( 提供者- 不可识别)

## 安装

```sh
npm install @code-pushup/ci
```

也可以使用：`pnpm add @code-pushup/ci`、`yarn add @code-pushup/ci`、`bun add @code-pushup/ci`

## README

# @ code- pushup/ ci (英语)

[![npm](https://img.shields.io/npm/v/%40code-pushup%2Fci.svg)](https://www.npmjs.com/package/@code-pushup/ci) [![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Fcli)](https://npmtrends.com/@code-pushup/ci) [![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/ci)](https://www.npmjs.com/package/@code-pushup/ci?activeTab=dependencies)

🔎🔬 **您的软件项目的质量衡量标准 .** 📉🔍

1.  ⚙️ **配置您想要使用您最喜欢的工具来跟踪的东西 .**
2.  🤖 **把它融入你的线人.**
3.  🌈 **在漂亮的仪表板上看到报告.**

* * *

此套件导出 **在 CI 管道中运行代码 PushUp 的提供者不可知核心逻辑**它作为下列供应商一体化的基础:

|  |  |
| :-- | :-- |
| GitHub 动作 | [`code-pushup/github-action`](https://github.com/marketplace/actions/code-pushup) |
| GitLab CI/光盘 | [`code-pushup/gitlab-pipelines-template`](https://gitlab.com/code-pushup/gitlab-pipelines-template) |

## 设置

```sh
npm install @code-pushup/ci
```

```sh
yarn add @code-pushup/ci
```

```sh
pnpm add @code-pushup/ci
```

## 使用量

这个 `runInCI` 函数执行完整的 CI 流 :

```ts
import { runInCI } from '@code-pushup/ci';

const result = await runInCI(
  {
    /* Git refs */
  },
  {
    /* Provider API client */
  },
  {
    /* Options */
  },
);
```

## 参数

### 基调

对于每次CI跑步,你都必须通过承诺SHA和Git ref(例如:. `main`被推开的东西. 这些值可以从 CI 环境中检测出,细节取决于使用哪个提供者.

如果 `head` 提供,然后代码 PushUp 将收集新报告,并可选地将其上传到门户网站(取决于您的代码 PushUp 配置). 如果被拉动请求所触发,请指定 `base` 报告也一样. 这将进一步比较来源和目标部门的报告,并向公关发布评论.

| 财产 | 需求 | 类型 | 说明 |
| :-- | :-- | :-- | :-- |
| `head` | 对 | `string | { ref: string, sha: string }` | 当前分支/承诺 |
| `base` | 没有 | `string | { ref: string, sha: string }` | 公关目标部门 |

### API 客户端

PR流量需要与 Git 提供者的 API 互动发布比较注释. 将这些请求包成函数,并作为配置提供者的对象传送.

| 财产 | 需求 | 类型 | 说明 |
| :-- | :-- | :-- | :-- |
| `createComment` | 对 | `(body: string) => Promise<Comment>` | 向 PR 发布新评论 |
| `updateComment` | 对 | `(id: number, body: string) => Promise<Comment>` | 更新已有的 PR 注释 |
| `listComments` | 对 | `() => Promise<Comment[]>` | 从 PR 获取全部批注 |
| `maxCommentChars` | 对 | `number` | 注释机构的字符限制 |
| `downloadReportArtifact` | 没有 | `(project?: string) => Promise<string | null>` | 获取上一个( 根/ 项目) `report.json` 用于基分支和返回路径,用作缓存以加快比较 |

A 类 `Comment` 对象具有下列所需的属性:

| 财产 | 类型 | 说明 |
| :-- | :-- | :-- |
| `id` | `number` | 注释编号 |
| `body` | `string` | 作为 Markdown 字符串的评论内容 |
| `url` | `string` | 在 PR 中注释的网页链接 |

### 选项

可选的,您可以覆盖默认选项以进一步定制 :

| 财产 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| `monorepo` | `boolean | MonorepoTool` | `false` | 启用 [单相模式](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode) |
| `parallel` | `boolean | number` | `false` | 启用并行执行 [单相模式](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode) |
| `projects` | `string[] | null` | `null` | 自定义工程配置 [单相模式](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode) |
| `task` | `string` | `'code-pushup'` | 每个工程运行代码的指令名称 [单相模式](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode) |
| `nxProjectsFilter` | `string | string[]` | `'--with-target={task}'` | 传递到 [`nx show projects`](https://nx.dev/nx-api/nx/documents/show#projects)中,仅与 Nx 相关 [单相模式](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode) \[^2\] |
| `directory` | `string` | `process.cwd()` | 代码 PushUp CLI 运行目录 |
| `config` | `string | null` | `null` \[^1\] | 配置文件的路径( E)`--config` 选项) |
| `silent` | `boolean` | `false` | 从 CLI 命令中隐藏日志( 错误将被打印) |
| `bin` | `string` | `'npx --no-install code-pushup'` | 执行代码 PushUp CLI 的命令 |
| `detectNewIssues` | `boolean` | `true` | 如果发现新问题并返回到 `newIssues` 属性 |
| `skipComment` | `boolean` | `false` | 如果将比较注释发布到 PR 中, 则切换 |
| `configPatterns` | `ConfigPatterns | null` | `null` | 启用的其他配置 [更快的 CI 运行](https://npmcn.com/package/%40code-pushup/ci/#readme-faster-ci-runs-with-configpatterns) |
| `searchCommits` | `boolean | number` | `false` | 如果基地分支在门户中没有缓存报告, [将搜索扩展至最近100项](https://npmcn.com/package/%40code-pushup/ci/#readme-search-latest-commits-for-previous-report) |
| `jobId` | `string | number | null` | `null` | 区别 PR 注释( 如果多个任务运行代码 PushUp ) |

\[^1\]:默认 `code-pushup.config` 文件已自动检测到, 如描述的那样 [`@code-pushup/cli` 文档](https://npmcn.com/package/%40code-pushup/cli/README.md#configuration)。 。 。 .

\[^2\]: `{task}` 模式替换为 `task` 值,所以默认行为是使用 `npx nx show projects --with-target=code-pushup --json`编辑 `nxProjectsFilter` 选项使Nx用户能够灵活地以Nx CLI支持的替代方式过滤项目(例如. `--affected`, (中文(简体) ), `--projects`, (中文(简体) ), `--exclude`, (中文(简体) ), `--type`\- 参考 [nx 文档中的选项](https://nx.dev/nx-api/nx/documents/show#options) 详细情况.

## 独立模式

默认情况下,假设代码PushUp的设置是为了在全repo上运行一个命令(_独立模式_) (中文(简体) ). 如果您要在多个工程上单独运行代码 PushUp, 您应该启用 [_单相模式_](https://npmcn.com/package/%40code-pushup/ci/#readme-monorepo-mode)。 。 。 .

### 独立结果

在独立模式下,解析对象会包括报告文件的路径(JSON和Markdown格式),以及diff文件,注释ID和公关比较时的新问题.

```ts
const result = await runInCI(refs, api);

if (result.mode === 'standalone') {
  const {
    // output files, can be uploaded as job artifact
    files: { current, comparison },
    // ID of created/updated PR comment
    commentId,
    // array of source code issues, can be used to annotate changed files in PR
    newIssues,
  } = result;
}
```

## Monorepo 模式

对于单重置设置,可以收集并比较代码 PushUp 报告 每个项目。 将所有项目比较合并为 单公关评论.

使用 `monorepo` 选项以激活单曲模式 :

```ts
await runInCI(refs, api, {
  monorepo: true,
});
```

这个 `runInCI` 函数将尝试从文件系统中检测您正在使用的哪一个单列波工具 . 框外支持以下工具:

-   [无](https://nx.dev/)
-   [涡轮](https://turbo.build/)
-   [Yarn 工作空间](https://classic.yarnpkg.com/lang/en/docs/workspaces/)
-   [pnpm 工作空间](https://pnpm.io/workspaces)
-   [npm 工作空间](https://docs.npmjs.com/cli/using-npm/workspaces)

如果使用其中一个工具,也可以通过设置跳过自动检测 `monorepo` 选项到 `'nx'`, (中文(简体) ), `'turbo'`, (中文(简体) ), `'yarn'`, (中文(简体) ), `'pnpm'` 或者说 `'npm'`。 。 。 .

如果没有检测到这些工具,那么后退就是运行代码 PushUp in 包含所有文件夹 `package.json` 文档。 如果这不是你想要的,那么 您也可以使用 `projects` 选项( 支持 globs ):

```ts
await runInCI(refs, api, {
  monorepo: true,
  projects: ['frontend', 'backend/*'],
});
```

基于使用 monrepo 工具, 代码 PushUp CLI 命令将被执行 使用一个 `package.json` 脚本、 Nx 目标、 Turbo 任务或二进制可执行文件( 如 倒计时). 默认情况下,它们将被调用 `code-pushup`不过你 能够使用 `task` 选项 :

```ts
await runInCI(refs, api, {
  monorepo: 'nx',
  task: 'analyze', // custom Nx target
});
```

### 并行任务

默认情况下,单列波中每个项目的任务按顺序运行. 这个 `parallel` 选项允许支持它的工具(Nx、Turborepo、PNPM、Yarn 2+)并行执行.

```ts
await runInCI(refs, api, {
  monorepo: true,
  parallel: true,
});
```

最多同时进行的任务数可以通过一个数字而不是布尔来设定 :

```ts
await runInCI(refs, api, {
  monorepo: true,
  parallel: 3,
});
```

### 单收结果

在单雷波模式下,已解析对象包括顶层被合并的diff,以及项目列表. 每个项目都有自己的报告文件和问题.

```ts
const result = await runInCI(refs, api);

if (result.mode === 'monorepo') {
  const {
    // array of objects with result for each project
    projects,
    // ID of created/updated PR comment
    commentId,
    // merged report-diff.md used in PR comment, can also be uploaded as job artifact
    files: { comparison },
  } = result;

  for (const project of projects) {
    const {
      // detected project name (from package.json, project.json or folder name)
      name,
      // output files, can be uploaded as job artifacts
      files: { current, comparison },
      // array of source code issues, can be used to annotate changed files in PR
      newIssues,
    } = project;
  }
}
```

## 高级用途

### 更快的 CI 运行方式 `configPatterns`

默认情况下 `print-config` 命令按顺序运行,以可靠地检测 `code-pushup` 配置 - 具体地说, 从何处读取输出文件( e)`persist` 配置)以及门户是否可以用作缓存(`upload` conf. 这样可以让每个项目都以自己的方式配置,而不会打破任何东西,但是可以让大块单放这些额外的 `code-pushup print-config` 处决可以累积并大大地减缓CI程序.

作为一个更可扩展的替代品, `configPatterns` 可以提供。 用户提前声明每个工程的配置方式, 允许 `print-config` 被跳过。 用户有责任确保每个项目都持有这种配置(不会被检查). 这个 `configPatterns` 支持字符串插入, 替换 `{projectName}` 与每个项目的(已粘结)名称相连接。 除此之外,每个项目 `code-pushup.config` 一定是完全一样 `persist` 财务报告和审定财务报表 `upload` 配置.

```ts
await runInCI(refs, api, {
  monorepo: true,
  configPatterns: {
    persist: {
      outputDir: '.code-pushup/{projectName}',
      filename: 'report',
      format: ['json', 'md'],
    },
    // optional: will use portal as cache when comparing reports in PRs
    upload: {
      server: 'https://api.code-pushup.example.com/graphql',
      apiKey: 'cp_...',
      organization: 'example',
      project: '{projectName}',
    },
  },
});
```

### 上份报告的最新搜索承诺

在比较报告时,可以缓存基础分支的报告. 如果一个项目有一个 `upload` 配置,然后询问端口 API 是否匹配此承诺的报告 。 如果未上载此类报告,则在CI文物中查阅该报告(由 `downloadReportArtifact` 内 [`ProviderApiClient`](https://npmcn.com/package/%40code-pushup/ci/#readme-provider-api-client)) (中文(简体) ). 如无报告可查,则取出基分所并收取上报.

在某些情况下,可能没有关于主要部门最新承诺的报告,但最近其他一些承诺可能有一个有用的报告,例如如果 `nxProjectsFilter` 用于 `--affected` 旗帜。 在这种情况下 `searchCommits` 选项可以启用。 然后将检查主要分支最近承付的有限数目.

```ts
await runInCI(refs, api, {
  monorepo: 'nx',
  nxProjectsFilter: '--with-target=code-pushup --affected',
  // checks 10 most recent commits by default
  searchCommits: true,
  // optionally, number of searched commits may be extended up to 100
  // searchCommits: 30
});
```

## 常见问题

### @code-pushup/ci 是什么？

代码 PushUp 的 CI 自动化逻辑\( 提供者- 不可识别\)

### 如何安装 @code-pushup/ci？

在项目目录运行 npm install @code-pushup/ci，或使用 pnpm add / yarn add / bun add。

### @code-pushup/ci 支持 TypeScript 吗？

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

### @code-pushup/ci 支持 ESM 还是 CommonJS？

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

### @code-pushup/ci 可以商用吗？

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

### @code-pushup/ci 的下载量有多少？

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

### @code-pushup/ci 还在维护吗？

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