# @code-pushup/cli 中文文档

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

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

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

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

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

- 包体积（解压后）：119 kB，120 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- 首次发布：2023-12-01T08:35:30.406Z
- 最新版本发布：2026-09-11T10:13:22.372Z
- 近 30 天下载量：6320（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：256（近 12 个月 62 个）

## 中文简介

运行各种代码质量测量的 CLI 使您的团队符合公司目标

## 安装

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

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

## README

# @ code- pushup/ cli (英语)

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

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

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

* * *

| 开始 | 门户网站整合 | QQ CI 自动化 |
| --- | :-: | --- |
| **[如何设置](https://npmcn.com/package/%40code-pushup/cli/#readme-getting-started)** 基本项目 | 排序, 过滤器 **[目标](https://npmcn.com/package/%40code-pushup/cli/#readme-portal-integration)** | 更新 **[每个公关](https://npmcn.com/package/%40code-pushup/cli/#readme--ci-automation)** |
| [![Getting started cover image](https://npmcn.com/package/%40code-pushup/cli/docs/images/getting-started-cover.png "Getting started with code-pushup")](https://npmcn.com/package/%40code-pushup/cli/#readme-getting-started) | [![Portal integration cover image](https://npmcn.com/package/%40code-pushup/cli/docs/images/portal-cover.png "Inetegrate code-pushup portal")](https://npmcn.com/package/%40code-pushup/cli/#readme-portal-integration) | [![CI Automation cover](https://npmcn.com/package/%40code-pushup/cli/docs/images/cli-cover.png "CI automation guide")](https://npmcn.com/package/%40code-pushup/cli/#readme--ci-automation) |

* * *

代码PushUp CLI服务于 **收集审计结果**,可选择 **上传报表** 到代码PushUp门户.

它可以在您的存储器中局部使用, 或者在您的 CI 环境中集成 .

_如果你在寻找程序用途,那么请参考基础 [@ code- pushup/ core (中文(简体) )](https://npmcn.com/package/%40code-pushup/core/README.md) 软件包._

## 开始

1.  用您的软件包管理器安装为 dev 依赖 :
    
    用于安装命令 `npm`, (中文(简体) ), `yarn` 财务报告和审定财务报表 `pnpm`
    
    ```sh
    npm install --save-dev @code-pushup/cli
    ```
    
    ```sh
    yarn add --dev @code-pushup/cli
    ```
    
    ```sh
    pnpm add --save-dev @code-pushup/cli
    ```
    
2.  创建一个 `code-pushup.config.ts` 配置文件( e)`.js` 或者说 `.mjs` 扩展也得到支持).
    
    ```ts
    import type { CoreConfig } from '@code-pushup/models';
    
    const config: CoreConfig = {
      plugins: [
        // ...
      ],
    };
    
    export default config;
    ```
    
3.  根据您的项目需要添加插件( 例如) . [@ code- pushup/ eslint- plugin](https://npmcn.com/package/%40code-pushup/plugin-eslint/README.md) 或者说 [@ code- pushup/ coverage- plugin (英语)](https://npmcn.com/package/%40code-pushup/plugin-coverage/README.md)) (中文(简体) ).
    
    ```sh
    npm install --save-dev @code-pushup/eslint-plugin
    ```
    
    ```ts
    import eslintPlugin from '@code-pushup/eslint-plugin';
    import type { CoreConfig } from '@code-pushup/models';
    
    const config: CoreConfig = {
      // ...
      plugins: [
        // ...
        await eslintPlugin({ eslintrc: '.eslintrc.js', patterns: ['src/**/*.js'] }),
      ],
    };
    
    export default config;
    ```
    
4.  用 CLI 运行 CLI `npx code-pushup` (见 `--help` 页:1.
    
5.  查看输出目录中的报告文件( 由 `persist.outputDir` 配置).  
    此文件夹应在您的 `.gitignore`。 。 。 .
    

### 设置分类( 可选)

1.  定义您的自定义类别 .
    
    ```ts
    const config: CoreConfig = {
      // ...
      categories: [
        {
          slug: 'performance',
          title: 'Performance',
          refs: [
            // reference to an existing audit or group from plugins
            {
              type: 'audit',
              plugin: 'eslint',
              slug: 'react-jsx-key',
              weight: 1,
            },
            // ...
          ],
        },
        // ...
      ],
    };
    ```
    
2.  用 CLI 运行 CLI `npx code-pushup`。 。 。 .
    
3.  查看报告文件,包括输出目录中的类别部分.
    

## 门户一体化

如果您可以访问代码 PushUp 门户, 您可以安装上传报告 `@code-pushup/portal-client` 软件包.

用于安装命令 `npm`, (中文(简体) ), `yarn` 财务报告和审定财务报表 `pnpm`

```sh
npm install --save-dev @code-pushup/portal-client
```

```sh
yarn add --dev @code-pushup/portal-client
```

```sh
pnpm add --save-dev @code-pushup/portal-client
```

软件包安装后, 更新您的配置文件以包含您的门户证书 :

```ts
const config: CoreConfig = {
  // ...
  upload: {
    server: 'https://ip-or-domain/path/to/portal/api/graphql',
    apiKey: process.env.PORTAL_API_KEY,
    organization: 'my-org',
    project: 'my-project',
  },
};
```

## CI 自动化

GitHub 动作示例

```yml
name: Code PushUp

on: push

jobs:
  collect-and-upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx code-pushup autorun --upload.apiKey=${{ secrets.PORTAL_API_KEY }}
```

## 配置

关于配置文件中所有选项的综合清单,请参见: [`CoreConfig` 文档](https://npmcn.com/package/%40code-pushup/models/docs/models-reference.md#coreconfig)。 。 。 .

配置文件的默认位置是 `code-pushup.config.ts`, (中文(简体) ), `code-pushup.config.mjs` 或者说 `code-pushup.config.js`其他地点需要使用 `--config=<path>` CLI选项.

如果您的配置文件依赖于一些自定义的 TypeScript 项目配置 - 例如通过导入别名 [编译器选项.paths](https://www.typescriptlang.org/tsconfig#paths) (常见于Nx) - 您可以使用 `--tsconfig=<path>` CLI选项.

## 自定义插件

我们提供了有关 [如何创建自定义插件](https://npmcn.com/package/%40code-pushup/cli/docs/custom-plugins.md)。 。 。 .

该寄存器还维护了一组插件实例来显示不同的情景.  
每个实例都经过充分测试,以展示插件测试的最佳做法.

**自定义插件示例 :**

-   📏 [文件大小](https://npmcn.com/package/examples/plugins/src/file-size) - 基本执行人的例子
-   📦 [Json软件包](https://npmcn.com/package/examples/plugins/src/package-json) - 审计和团体的例子
-   🔥 [灯塔](https://npmcn.com/package/examples/plugins/src/lighthouse) (正式执行) [这里](https://npmcn.com/packages/plugin-lighthouse)) - 一个基本命令执行器的例子

## CLI 命令和选项

### 全球选项

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--verbose`** | `boolean` | `process.env['CP_VERBOSE']` 如果设置, 否则 `false` | 切换是否打印调试日志 . |
| **`--config`** | `string` | 寻找 `code-pushup.config.{ts|mjs|js}` | 配置文件路径 . |
| **`--tsconfig`** | `string` | 无 | 用于装入配置文件的 TypeScript 配置路径 . |

> \[注\]  
> 默认情况下, CLI 负载 `code-pushup.config.(ts|mjs|js)` 如果没有提供配置路径 `--config`。 。 。 .

### 常见命令选项

#### 全球选项

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--onlyPlugins`** | `string[]` | `[]` | 只运行指定的插件 。 适用于所有命令,但 `upload`。 。 。 . |
| **`--skipPlugins`** | `string[]` | `[]` | 跳过指定的插件 。 适用于所有命令,但 `upload`。 。 。 . |
| **`--onlyCategories`** | `string[]` | `[]` | 只运行指定的类别 。 适用于所有命令,但 `upload`。 。 。 . |
| **`--skipCategories`** | `string[]` | `[]` | 跳过指定的类别 。 适用于所有命令,但 `upload`。 。 。 . |

#### 缓存选项

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--cache`** | `boolean` | `false` | 缓存运行输出( 读取和写入) . |
| **`--cache.read`** | `boolean` | `false` | 如果插件审计产出应从文件系统缓存中读取. |
| **`--cache.write`** | `boolean` | `false` | 如果插件审计输出应当写入文件系统缓存. |

#### 持久性选项

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--persist.outputDir`** | `string` | 无 | 编制报告目录. |
| **`--persist.filename`** | `string` | `report` | 没有扩展的生成报告的文件名 . |
| **`--persist.format`** | `('json' | 'md')[]` | `json` | 报表文件的格式. |
| **`--persist.skipReports`** | `boolean` | `false` | 跳过生成报告文件 。 (有用与缓冲结合) |

#### 上传选项

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--upload.organization`** | `string` | 无 | 传送门的卫星. |
| **`--upload.project`** | `string` | 无 | 传送门的子弹. |
| **`--upload.server`** | `string` | 无 | URL 到您的门户服务器 . |
| **`--upload.apiKey`** | `string` | 无 | 门户网站服务器的 API 密钥 . |

> \[注\]  
> 所有常见选项,但 `--onlyPlugins` 财务报告和审定财务报表 `--skipPlugins`,也可以在配置文件中指定. CLI 参数优先于配置文件选项.

> \[注\]  
> 这个 `--upload.*` 选项组适用于所有命令,但 `collect`。 。 。 .

### 图标

#### `collect` 命令

![example of code-pushup terminal output](https://npmcn.com/package/%40code-pushup/cli/docs/images/cli-run-stdout-example.png)

用法 : `code-pushup collect [options]`

说明 : 命令初始化并执行必要的插件并收集结果. 报告根据结果编写了一份综合报告.

参见 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options) 的选项.

#### `upload` 命令

用法 : `code-pushup upload [options]`

说明 : 上传报告到代码PushUp门户网站.

参见 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options) 的选项.

#### `autorun` 命令

用法 : `code-pushup autorun [options]`

说明 : 运行插件,收集结果并上传报告到代码PushUp门户网站.

参见 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options) 的选项.

#### `history` 命令

用法 : `code-pushup history`

说明 : 运行插件, 收集结果并上传报告到代码 PushUp 门户, 用于指定数量的承诺 .

参见 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options) 的选项.

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--targetBranch`** | `string` | 关键 | 分行来爬行历史. |
| **`--forceCleanStatus`** | `boolean` | `false` | 如果我们把状态重新设置为 干净的基特历史 强或不是. |
| **`--maxCount`** | `number` | 页:1 | 承诺数量. |
| **`--skipUploads`** | `boolean` | `false` | 上传创建的报告 |
| **`--from`** | `string` | 无 | 历史的开始 |
| **`--to`** | `string` | 无 | 历史结束 |

#### `compare` 命令

用法 : `code-pushup compare --before SOURCE_PATH --after TARGET_PATH [options]`

说明 : 比较2份报告并生成报告 diff 文件 .

计外 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options),以下选项得到 `compare` 命令 :

| 选项 | 类型 | 默认 | 说明 |
| --- | :-: | --- | --- |
| **`--before`** | `string` | `.code-pushup/report-before.json` \[^1\] | 来源路径 `report.json`。 。 。 . |
| **`--after`** | `string` | `.code-pushup/report-after.json` \[^1\] | 目标路径 `report.json`。 。 。 . |
| **`--label`** | `string` | 不详 \[^2\] | Diff的标签(例如项目名称). |

\[^1\]:用途 `persist` 配置以决定报告路径, 因此默认文件路径实际上是 `${persist.outputDir}/${persist.filename}-before.json` 财务报告和审定财务报表 `${persist.outputDir}/${persist.filename}-after.json`。 。 。 .

\[^2\]:用途 `label` 从输入中 `report.json` 文件是两者具有相同的价值.

#### `print-config` 命令

用法 : `code-pushup print-config [options]`

说明 : 打印解析配置 .

计外 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options),以下选项得到 `print-config` 命令 :

| 选项 | 需求 | 类型 | 说明 |
| --- | :-: | --- | --- |
| **`--output`** | 对 | `string` | 输出文件打印配置的路径 . |

#### `merge-diffs` 命令

用法 : `code-pushup merge-diffs --files PATH_1 PATH_2 ... [options]`

说明 : 将多个报表 diff 合并为单个 `report-diff.md`。 。 。 .

计外 [常见命令选项](https://npmcn.com/package/%40code-pushup/cli/#readme-common-command-options),以下选项得到 `merge-diffs` 命令 :

| 选项 | 需求 | 类型 | 说明 |
| --- | :-: | --- | --- |
| **`--files`** | 对 | `string[]` | 清单 `report-diff.json` 路径. |

## 缓存

CLI支持缓存以加速后续运行,并与Nx和Turborepo兼容.

根据策略,您可以缓存生成的报告文件或插件跑车输出. 对于精细的缓存,我们建议缓存插件跑跑器输出.

详细实例 [Nx 缓存](https://npmcn.com/package/%40code-pushup/cli/docs/nx-caching.md) 财务报告和审定财务报表 [涡轮缓冲](https://npmcn.com/package/%40code-pushup/cli/docs/turbo-caching.md) 可在文档中查阅.

## 常见问题

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

运行各种代码质量测量的 CLI 使您的团队符合公司目标

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

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

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

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

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

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

### @code-pushup/cli 需要什么版本的 Node\.js？

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

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

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

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

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

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

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