# @codacy/analysis-runner 中文文档

规范地址：https://npmcn.com/package/%40codacy/analysis-runner/

版本：0\.28\.0
npm 元数据更新时间：2026-11-09T13:46:17.249Z
中文译文更新时间：2026-11-10T05:34:04.228Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：581 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：5 个
- 首次发布：2026-03-24T13:15:53.437Z
- 最新版本发布：2026-11-09T13:46:17.069Z
- 近 30 天下载量：11963（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

Codacy 分析核心管弦引擎

## 安装

```sh
npm install @codacy/analysis-runner
```

也可以使用：`pnpm add @codacy/analysis-runner`、`yarn add @codacy/analysis-runner`、`bun add @codacy/analysis-runner`

## README

# @codacy/analysis-runner (英语)

## 目录

-   [概览](https://npmcn.com/package/%40codacy/analysis-runner/#readme-overview)
-   [快开始](https://npmcn.com/package/%40codacy/analysis-runner/#readme-quick-start)
-   [API 密码](https://npmcn.com/package/%40codacy/analysis-runner/#readme-api)
-   [管道步骤](https://npmcn.com/package/%40codacy/analysis-runner/#readme-pipeline-steps)
-   [输出格式](https://npmcn.com/package/%40codacy/analysis-runner/#readme-output-formats)
-   [执行模式](https://npmcn.com/package/%40codacy/analysis-runner/#readme-execution-modes)

* * *

## 概览

Codacy Analysis CLI的核心管弦引擎. 发现工具、检查能力、呼叫 `analyze()` ,并转换输出。 CLI和IDE的整合方案都可用.

## 快开始

工具适配器生活在一个伴机预设包中, **`@codacy/analysis-adapters`**A级 消费者安装并登记内置适配器 **一次** 运行前 任何与工具相关的工具 —— 运行器的适配器注册开始为空而无 自动人口.

```ts
import { registerBuiltinAdapters } from "@codacy/analysis-adapters";
import { analyze, createNullLogger } from "@codacy/analysis-runner";

// Register all built-in tools + cloud-only descriptors (call once at startup).
registerBuiltinAdapters();

// Run analysis. `repositoryRoot` must be a git work tree.
const result = await analyze({
  repositoryRoot: "/abs/path/to/repo",
  // files: ["src/index.ts"],   // optional: scope to specific files
  logger: createNullLogger(), // or bring your own Logger (see below)
});

// Issue paths are repo-relative; line/column are 1-based.
for (const issue of result.issues) {
  console.log(
    `${issue.filePath}:${issue.line}:${issue.column}  ${issue.patternId}  ${issue.message}`,
  );
}
```

只注册一个工具子集,导入 `builtinAdapterEntries` 从预设和 调用 `registerLazyAdapter(descriptor, load)` 为了你想要的那些.

### 创建配置

`analyze()` 读取 `.codacy/codacy.config.json`在方案上产生一个 `init*` 家庭——他们建立 `CodacyConfig` 从登记的适配器; `writeCodacyConfig` 坚持:

```ts
import {
  getRegisteredAdapters,
  initLocalConfig, // local-config detection only (offline)
  // initDefaultConfig / initAutoConfig / initRemoteConfig also available
  writeCodacyConfig,
} from "@codacy/analysis-runner";

const adapters = await getRegisteredAdapters();
const { config } = await initLocalConfig(repositoryRoot, adapters);
await writeCodacyConfig(repositoryRoot, config);
```

`initAutoConfig` 此外,还采用已登记的描述符(`getRegisteredDescriptors()`(中文(简体) ) 和预设 `loadUnsupportedPatterns` 切入门堆栈专用图案; `initRemoteConfig` 从 Codacy Cloud 取出配置( 通过 API 令牌 —— 参见下面的证书助手) .

### 自定义日志和取消

-   自己传 `Logger` (单位:千美元) `@codacy/tooling` 合同: `debug` 编号 : `info` 编号 : `warn` 编号 : `error`(中文(简体) ) 以路径进度进入您的用户界面,或 `createNullLogger()` 为了沉默。 执行 **没有** 使用情况 `createLogger()` 在嵌入器中——它写到文件/sderr. 驱动进度 UI 从 `onToolStart` 编号 : `onToolComplete` 编号 : `onToolProgress` 调用 `AnalyzeOptions`。 。 。 .
-   过 `signal: AbortSignal` 打开 `AnalyzeOptions` 取消飞行中运行; 信号荣誉 适配器返回部分结果,剩余工具被标记被取消.

## API 密码

| 导出 | 目的 |
| --- | --- |
| `analyze(options)` | 主要切入点——运行全分析管. 选项包括 `repositoryRoot`, (中文(简体) ), `tools`, (中文(简体) ), `files`, (中文(简体) ), `logger`, (中文(简体) ), `signal`,以及 `onTool*` 进度回调 |
| `registerAdapter(adapter)` 编号 : `registerLazyAdapter(descriptor, load)` | 注册工具适配器( eager/ 懒惰) |
| `clearAdapters()` | 重置适配器登记册(供测试) |
| `getRegisteredAdapters()` 编号 : `getRegisteredDescriptors()` | 列出已注册适配器/描述符 |
| `initLocalConfig()` 编号 : `initDefaultConfig()` 编号 : `initAutoConfig()` 编号 : `initRemoteConfig()` | 构建一个 `CodacyConfig` (本地,默认,堆积意识,或云源) |
| `readCodacyConfig()` 编号 : `writeCodacyConfig()` | 读取/写作 `.codacy/codacy.config.json` |
| `buildToolConfig()` | 从 CodacyConfig + 本地配置集合 Codacy ToolFig |
| `discover(path)` | 扫描回波并报告语言、框架、库和显著文件 |
| `formatOutput(result, format)` | 将分析结果转换为格式化的字符串 |
| `createLogger()` 编号 : `createNullLogger()` | 文件/stderr记录器(CLI) / no-op记录器(嵌入器) |
| `saveCredentials()` 编号 : `loadCredentials()` 编号 : `deleteCredentials()` 编号 : `resolveApiToken()` | 机器存储的 API- token 存储在 `~/.codacy/credentials` |
| `validateApiToken()` 编号 : `configureApiToken()` 编号 : `listIgnoredFiles()` | Codacy Cloud API 帮助者 |

> 适配器 **登记** 住在伴侣的预设中 `@codacy/analysis-adapters` (单位:千美元)`registerBuiltinAdapters`, (中文(简体) ), `builtinAdapterEntries`),不在这里——跑者留下 工具不可识别.

## 管道步骤

1.  发现注册的适配器(由 `options.tools` 如果设置)
2.  检查可用性 • 构建能力报告
3.  应用执行模式规则(标准/严格/自动安装/检查)
4.  通过 git 发现文件, 应用排除层, 路径到工具
5.  检查本地配置 + 构建 CodacyToolConfig 每个工具
6.  执行 `adapter.analyze()` 带有超时和货币控制
7.  分析结果汇总
8.  格式输出

## 输出格式

| 格式 | 说明 |
| --- | --- |
| `json` | 漂亮打印的分析结果( 默认) |
| `sarif` | SARIF v2.1.0 文档 |
| `container` | 每行1个JSON对象(Codacy Docker跑车) |
| `text` | 有颜色和分组的可读终端摘要 |

## 执行模式

| 模式 | 行为 |
| --- | --- |
| `standard` | 跳过无法使用的工具, 报告它们( 默认) |
| `strict` | 无法使用任何配置的工具时失败 |
| `auto-install` | 试图在分析前安装缺失的工具 |
| `inspect` | 干跑:报告能力不运行分析 |

## 常见问题

### @codacy/analysis-runner 是什么？

Codacy 分析核心管弦引擎

### 如何安装 @codacy/analysis-runner？

在项目目录运行 npm install @codacy/analysis-runner，或使用 pnpm add / yarn add / bun add。

### @codacy/analysis-runner 支持 TypeScript 吗？

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

### @codacy/analysis-runner 支持 ESM 还是 CommonJS？

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

### @codacy/analysis-runner 需要什么版本的 Node\.js？

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

### @codacy/analysis-runner 可以商用吗？

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

### @codacy/analysis-runner 的下载量有多少？

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

### @codacy/analysis-runner 还在维护吗？

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