# @codacy/tools-dartanalyzer-3 中文文档

规范地址：https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/

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

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

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

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

- 包体积（解压后）：389 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- 首次发布：2026-08-14T08:42:39.928Z
- 最新版本发布：2026-11-09T13:48:06.854Z
- 近 30 天下载量：11711（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

dartanalyzer 适配器 — CLI- mode Dart 分析器( 艺术分析)

## 安装

```sh
npm install @codacy/tools-dartanalyzer-3
```

也可以使用：`pnpm add @codacy/tools-dartanalyzer-3`、`yarn add @codacy/tools-dartanalyzer-3`、`bun add @codacy/tools-dartanalyzer-3`

## README

# 校对:soup

## 目录

-   [概览](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-overview)
-   [更新图案](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-updating-patterns)
-   [更新图案类型表格](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-updating-the-pattern-type-table)
-   [更新 Dart SDK 版本](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-updating-the-dart-sdk-version)
-   [发展](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-development)
-   [维护者的注释](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-notes-for-maintainers)
    -   [仓库- root 配置交换](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-the-repository-root-config-swap)
    -   [为什么生成的配置看起来半空](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-why-the-generated-config-looks-half-empty)
    -   [`--format json`没有 `--format machine`](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme---format-json-not---format-machine)
    -   [未解决的依赖关系](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-unresolved-dependencies)
    -   [部件文件](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-part-files)
    -   [已知的限制](https://npmcn.com/package/%40codacy/tools-dartanalyzer-3/#readme-known-limitations)

* * *

## 概览

`dart analyze` 是 Dart SDK 的内置静态分析器—— 与 Dart IDE 后面的同一引擎 插件 。 它报告了两种发现, 这个适配器处理两种:

-   **林特规则** (215 Codacy types)——风格与最佳做法检查. Opt-in:它们只在 a 一个 `analysis_options.yaml` 允许他们.
-   **分析器诊断** (962 Codacy types)——编译-时间错误,类型错误,死代码. 总是在,不需要配置.

| 财产 | 数值 |
| --- | --- |
| 工具标识 | `dartanalyzer` |
| 编码 UUID | `d203d615-6cf1-41f9-be5f-e2f660f7850f` |
| 战略 | CLI (中文(简体) )`spawnTool`(中文(简体) ) |
| 语文 | 达特 |
| 文件图案 | `**/*.dart` |
| 运行时间 | Dart SDK 3.x(~210 MB,自动安装) |
| 上游文件 | [https://dart.dev/tools/dart-analysis. 互联网档案馆的存檔,存档日期2013-12-21](https://dart.dev/tools/dart-analyze) |
| Codacy 包装器 | [https://github.com/codacy/codacy-dartan分析器 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/codacy/codacy-dartanalyzer) |

## 更新图案

```bash
# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# The pattern-type table is derived from patterns.json — always refresh it too
pnpm fetch-rule-types

# Commit both
git add src/patterns.json src/pattern-types.json
```

## 更新图案类型表格

`src/pattern-types.json` 将每个光标名称映射到 `lint`, (中文(简体) ), `diagnostic` 或者说 `unknown`。适配器 需要它,因为 `analysis_options.yaml` 有两个独立的部分和一个规则写错了 一个人默默无所事事.

`pnpm fetch-rule-types` 取自达特SDK自己的机器可读线条目录 (单位:千美元)`pkg/linter/tool/machine/rules.json`,具有压倒性 `DART_LINT_RULES_URL`: 名称目录 lists is a lint, 其他任何在科达西的目录 是一个诊断。 它会打印结果的计数 加上两个值得注意的差距:

-   **删除的线条** (单位:千美元)`unknown`)——仍在科达西的目录中,从SDK中走出. 写给两个 配置部分,因为分析器 既不认得它们。 明确名单生活在 `isRemovedLint()` 内 `scripts/fetch-rule-types.mjs`; prune条目Codacy 滴出.
-   **没有可调性图案的 SDK 线条** ——目前49个. 它们永远无法从科达西上被启用 在Codacy的目录被赶上之前 这个软件包是无能为力的.

科德西包装船 相当于手写的桌子 `docs/patterns_type.json`这个 取而代之的是,该快照已经是SDK背后的49行规则;两者完全一致 他们分享的1213个图案(215 + 3去除的林斯 = 包装器的218;995个诊断).

## 更新 Dart SDK 版本

1.  检查 Codacy 运行 : `.tool_version` 内 `codacy/codacy-dartanalyzer`,或 `version` 字段 从 `https://app.codacy.com/api/v3/tools`追踪,不是最新的稳定释放.
2.  更新 `preferredVersion` 内 `src/metadata.ts`。下载 URL 来源于它,所以没有 其它变化.
3.  运行 `pnpm prefetch` 财务报告和审定财务报表 `pnpm fetch-rule-types` 来拿起新的和删除的规则.
4.  运行 `pnpm test`。 。 。 .
5.  新达特 **主要** 版本指一个新的适配器包(`dartanalyzer-4/`) (中文(简体) ).

## 发展

```bash
pnpm build    # Build with tsup
pnpm test     # Run tests (SDK-dependent tests skip when no dart is installed)
```

在本地安装一个 Dart SDK, 因此集成测试运行而不是跳过 :

```bash
brew install dart                 # macOS
# or install Flutter, which bundles Dart
# or https://dart.dev/get-dart
```

`codacy-analysis analyze . --install-dependencies` 也可以工作:它下载被绑的便携式SDK 输入 `~/.codacy/tools/dartanalyzer/dart-sdk/`。 。 。 .

## 维护者的注释

### 仓库- root 配置交换

**这个是外出写字的适配器 `.codacy/`**这不是一条捷径 `dart analyze` 没有任何选择.

这里的所有其他工具都需要一个 `--config <path>`。 。 。 . `dart analyze` 无等效: dartdev 曝光 仅限 `--format`, (中文(简体) ), `--packages`, (中文(简体) ), `--cache`, (中文(简体) ), `--sdk-path` 编辑 `--fatal-*` 旗帜。 分析师发现 `analysis_options.yaml` 通过行走 **上来** 分析文件中的目录树 (单位:千美元)`ContextLocator` 内 `pkg/analyzer`因此,一个配置在 `.codacy/generated/` 从来没有见过。 科达西 Docker 包装器通过写入解决此问题 `/analysis_options.yaml` 并在 `/src` ——它拥有的父目录. 当地没有这样的目录.

这么说吧 `analyze()` 这样做,顺序如下:

1.  **回收** 如果根配置带有 `codacy-cli-generated-analysis-options` 标记, a 前一次运行被杀死 中游 : 恢复 `.codacy/generated/dartanalyzer/analysis_options.yaml.orig` 若为 当前,否则删除文件.
2.  **写入** 生成的配置为 `.codacy/generated/dartanalyzer/analysis_options.yaml` (贴在那里为 检查,将任何已有的根配置备份到 `…/analysis_options.yaml.orig`,并复制 生成文件到寄存器根.
3.  **运行** 每个 `dart analyze` 在一个配置下块.
4.  **恢复** 在一个 `finally`: 将备份放回, 或删除生成的文件—— 只有永远 删除一个带有标记的文件,所以用户创建的中程配置存活了下来.

标记使每一步都能安全地重复。 完全跳过互换的两条路径 : 正在使用项目本身的配置( i)`useLocalConfigurationFile`),当交换失败时(只读) 检查,权限)——这是警告,而不是失败,因为分析器诊断仍然有效 没有它,只有选入规则丢失.

不管运行哪条路径,结果都是通过启用的模式ID过滤后hoc的 本地配置路径也正确 .

### 为什么生成的配置看起来半空

它已启用 **线条** 而被忽视 **诊断**,没有其他的:

```yaml
analyzer:
  errors:
    unused_import: ignore # every diagnostic NOT selected
linter:
  rules:
    prefer_single_quotes: true # every lint selected
```

-   未选中的线条得到否 `false`文件没有 `include:`,所以一个没有名字的线条已经 关闭。 (击打) `include:` 还避免了 `package:flutter_lints` 解析失败 包装器用一个容器底盘在周围工作 `dart pub add`. ) (中文(简体) )
-   选定的诊断没有条目。 他们已经以默认严重性开火 `Issue.severity` 来自 `patterns.json`在这里写一个关卡意味着翻译Codacy的 `High` 改为 a 区域 `ignore|info|warning|error` - 包装纸写着 `high`,则无效.

### `--format json`没有 `--format machine`

包装器使用 `--format machine` 带有评论, JSON "在给定后返回多个对象 限制。 这在SDK 3.x 中已不再如此: `emitJsonFormat` 是一个单 `json.encode` 电话 JSON是... 乔治 更妙的是,它携带着 `range.end` (-) `endLine`编号 :`endColumn`, (中文(简体) ), `correctionMessage` (-) `Issue.suggestion`),以及 `code` ,其中机器格式大写 代码和只给出 `length` 可跨行的三角洲.

`parseDartOutput` 仍然回到逐行解析压缩文档,以防 行为永远回归.

退出代码为 `0` 干净, `1` 资讯, `2` 警告者, `3` 错误, `4` 崩溃——仅 `4` 以上为a 失败.

### 未解决的依赖关系

`dart analyze` 需求 `dart pub get` 运行;无 `.dart_tool/package_config.json`,每个 `package:` 导入无法解决, 并报告 `uri_does_not_exist` 数以百计的调查结论 花花库.

适配器 **从不运行 `pub get`** (它会写 `.dart_tool/` 财务报告和审定财务报表 `pubspec.lock` 输入 存储器,并需要网络——与 ESLint 适配器采取的立场相同 `npm install`) (中文(简体) ). 相反,它警告和压制 `uri_does_not_exist`, (中文(简体) ), `uri_has_not_been_generated` 财务报告和审定财务报表 `depend_on_referenced_packages` 只为了跑步 镇压是后胡克而不是一个配置 `ignore` 因此,它也适用于本地-配置路径,那里没有产生任何东西.

### 部件文件

达特 `part` 文件无法自行分析; 瞄准一个 `dart analyze` 报告 "是一部分,不能分析" 这是关于援引的抱怨,不是代码,所以.. 信件被丢弃( 包装过滤器会过滤相同的两个字符串) 。 载有 `part` 指令是应该分析的。 B. 诊断与非`.dart` 文档(`pubspec.yaml`, (中文(简体) ), `analysis_options.yaml`由于同样的原因而放弃.

### 已知的限制

-   **达特·莫瑞斯.** 互换只触及寄存器根. 嵌入自有的套件 `analysis_options.yaml` 击败了它,所以Codacy的图案选择被忽略了文件在此下 软件包。 已跟踪 `docs/tech-debt.md`。 。 。 .
-   **同时运行.** 两个 `codacy-analysis analyze` 在互换中进行一个寄存器竞赛.
-   **每块一个分析服务器 .** 每个 `dart analyze` 引用启动自己的分析服务器, 所以,一个文件列表 足够大, 可以被分割到 argv 块 支付启动 不止一次 .

## 常见问题

### @codacy/tools-dartanalyzer-3 是什么？

dartanalyzer 适配器 — CLI- mode Dart 分析器\( 艺术分析\)

### 如何安装 @codacy/tools-dartanalyzer-3？

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

### @codacy/tools-dartanalyzer-3 支持 TypeScript 吗？

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

### @codacy/tools-dartanalyzer-3 支持 ESM 还是 CommonJS？

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

### @codacy/tools-dartanalyzer-3 需要什么版本的 Node\.js？

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

### @codacy/tools-dartanalyzer-3 可以商用吗？

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

### @codacy/tools-dartanalyzer-3 的下载量有多少？

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

### @codacy/tools-dartanalyzer-3 还在维护吗？

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