dart-run-static-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyzing and Fixing Dart Code

Dart代码的分析与修复

Analysis Configuration

分析配置

Configure the Dart analyzer using the

analysis_options.yaml

file located at the package root.

Base Configuration: Always include a standard rule set (e.g.,
```
package:lints/recommended.yaml
```
or
```
package:flutter_lints/flutter.yaml
```
) using the
```
include:
```
directive.
Strict Type Checks: Enable strict type checks under the
```
analyzer: language:
```
node to prevent implicit downcasts and dynamic inferences. Set
```
strict-casts: true
```
,
```
strict-inference: true
```
, and
```
strict-raw-types: true
```
.
Linter Rules: Explicitly enable or disable specific rules under the
```
linter: rules:
```
node. Use a key-value map (
```
rule_name: true/false
```
) when overriding included rules, or a list (
```
- rule_name
```
) when defining a fresh set. Do not mix list and map syntax in the same
```
rules
```
block.
Formatter Configuration: Configure
```
dart format
```
behavior under the
```
formatter:
```
node. Set
```
page_width
```
(default 80) and
```
trailing_commas
```
(
```
automate
```
or
```
preserve
```
).
Analyzer Plugins: Enable custom diagnostics by adding plugins under the
```
analyzer: plugins:
```
node. Ensure the plugin package is added as a
```
dev_dependency
```
in
```
pubspec.yaml
```
.

使用位于包根目录下的

analysis_options.yaml

文件配置Dart分析器。

基础配置：始终通过

include:

指令引入标准规则集（例如

package:lints/recommended.yaml

或

package:flutter_lints/flutter.yaml

）。

严格类型检查：在
```
analyzer: language:
```
节点下启用严格类型检查，防止隐式向下转换和动态推断。设置
```
strict-casts: true
```
、
```
strict-inference: true
```
和
```
strict-raw-types: true
```
。
代码规范规则：在
```
linter: rules:
```
节点下显式启用或禁用特定规则。覆盖已引入规则时使用键值映射（
```
rule_name: true/false
```
），定义全新规则集时使用列表（
```
- rule_name
```
）。请勿在同一个
```
rules
```
块中混合使用列表和映射语法。
格式化配置：在
```
formatter:
```
节点下配置
```
dart format
```
的行为。设置
```
page_width
```
（默认值80）和
```
trailing_commas
```
（可选
```
automate
```
或
```
preserve
```
）。
分析器插件：在
```
analyzer: plugins:
```
节点下添加插件以启用自定义诊断功能。确保插件包已作为
```
dev_dependency
```
添加到
```
pubspec.yaml
```
中。

Diagnostic Suppression

诊断抑制

When a diagnostic (lint or warning) yields a false positive or applies to generated code, suppress it explicitly.

File-level Exclusion: Use the
```
analyzer: exclude:
```
node in
```
analysis_options.yaml
```
to exclude entire files or directories (e.g.,
```
**/*.g.dart
```
) using glob patterns.
File-level Suppression: Add
```
// ignore_for_file: <diagnostic_code>
```
at the top of a Dart file to suppress specific diagnostics for the entire file. Use
```
// ignore_for_file: type=lint
```
to suppress all linter rules.
Line-level Suppression: Add
```
// ignore: <diagnostic_code>
```
on the line directly above the offending code, or appended to the end of the offending line.

Pubspec Suppression: Add

# ignore: <diagnostic_code>

above the offending line in

pubspec.yaml

files (e.g.,

# ignore: sort_pub_dependencies

Plugin Diagnostics: Prefix the diagnostic code with the plugin name when suppressing plugin-specific issues (e.g.,
```
// ignore: some_plugin/some_code
```
).

当诊断（代码规范检查或警告）出现误报，或针对生成代码时，可显式抑制该诊断。

文件级排除：在
```
analysis_options.yaml
```
的
```
analyzer: exclude:
```
节点中，使用通配符模式排除整个文件或目录（例如
```
**/*.g.dart
```
）。
文件级抑制：在Dart文件顶部添加
```
// ignore_for_file: <diagnostic_code>
```
，以抑制整个文件中的特定诊断。使用
```
// ignore_for_file: type=lint
```
可抑制所有代码规范规则。
行级抑制：在问题代码的上一行添加
```
// ignore: <diagnostic_code>
```
，或追加到问题代码行的末尾。

Pubspec抑制：在

pubspec.yaml

的问题代码行上方添加

# ignore: <diagnostic_code>

（例如

# ignore: sort_pub_dependencies

）。

插件诊断：抑制插件特定问题时，需在诊断代码前添加插件名称前缀（例如
```
// ignore: some_plugin/some_code
```
）。

Workflow: Executing Static Analysis

工作流：执行静态分析

Use this workflow to identify type-related bugs, style violations, and potential runtime errors.

Task Progress:

1. Verify
```
analysis_options.yaml
```
exists at the project root.
2. Run the analyzer using the
```
analyze_files
```
MCP tool (if available) or the CLI command
```
dart analyze <target_directory>
```
.
3. Review the diagnostic output.
4. If info-level issues must be treated as failures, append the
```
--fatal-infos
```
flag.
5. Resolve reported errors manually or proceed to the Automated Fixes workflow.

使用此工作流识别类型相关bug、风格违规和潜在运行时错误。

任务进度：

1. 验证项目根目录下存在
```
analysis_options.yaml
```
文件。
2. 使用
```
analyze_files
```
MCP工具（若可用）或CLI命令
```
dart analyze <target_directory>
```
运行分析器。
3. 查看诊断输出结果。
4. 若需将信息级问题视为失败，追加
```
--fatal-infos
```
参数。
5. 手动解决报告的错误，或进入自动修复工作流。

Workflow: Applying Automated Fixes

工作流：应用自动修复

Use this workflow to resolve outdated API usages, apply quick fixes, and migrate code (e.g., Dart 3 migrations).

Task Progress:

1. Execute a dry run to preview proposed changes using the
```
dart_fix
```
MCP tool or CLI command
```
dart fix --dry-run
```
.
2. Review the proposed fixes to ensure they align with the intended architecture.
3. If additional fixes are required, verify that the corresponding linter rules are enabled in
```
analysis_options.yaml
```
.
4. Apply the fixes using the
```
dart_fix
```
MCP tool or CLI command
```
dart fix --apply
```
.
5. Format the modified code using the
```
dart_format
```
MCP tool or CLI command
```
dart format .
```
.
6. Run the static analysis workflow to verify all diagnostics are resolved.

使用此工作流解决过时API用法、应用快速修复和迁移代码（例如Dart 3迁移）。

任务进度：

1. 使用
```
dart_fix
```
MCP工具或CLI命令
```
dart fix --dry-run
```
执行试运行，预览拟议的变更。
2. 查看拟议的修复，确保其符合预期架构。
3. 若需要额外修复，验证对应的代码规范规则已在
```
analysis_options.yaml
```
中启用。
4. 使用
```
dart_fix
```
MCP工具或CLI命令
```
dart fix --apply
```
应用修复。
5. 使用
```
dart_format
```
MCP工具或CLI命令
```
dart format .
```
格式化修改后的代码。
6. 运行静态分析工作流，验证所有诊断已解决。

Examples

示例

Comprehensive

analysis_options.yaml

完整的

analysis_options.yaml

yaml

include: package:flutter_lints/recommended.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "lib/generated/**"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: ignore
    invalid_assignment: warning
    missing_return: error

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true
    use_super_parameters: true

formatter:
  page_width: 100
  trailing_commas: preserve

yaml

include: package:flutter_lints/recommended.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "lib/generated/**"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: ignore
    invalid_assignment: warning
    missing_return: error

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true
    use_super_parameters: true

formatter:
  page_width: 100
  trailing_commas: preserve

Inline Diagnostic Suppression

内联诊断抑制

dart

// Suppress for the entire file
// ignore_for_file: unused_local_variable, dead_code

void processData() {
  // Suppress for a specific line
  // ignore: invalid_assignment
  int x = ''; 
  
  const y = 10; // ignore: constant_identifier_names
}

dart

// 抑制整个文件的诊断
// ignore_for_file: unused_local_variable, dead_code

void processData() {
  // 抑制特定行的诊断
  // ignore: invalid_assignment
  int x = ''; 
  
  const y = 10; // ignore: constant_identifier_names
}

dart-run-static-analysis

Original

Translation

Analyzing and Fixing Dart Code

Dart代码的分析与修复

Contents

目录

Analysis Configuration

分析配置

Diagnostic Suppression

诊断抑制

Workflow: Executing Static Analysis

工作流：执行静态分析

Workflow: Applying Automated Fixes

工作流：应用自动修复

Examples

示例

Comprehensive
`analysis_options.yaml`

完整的
`analysis_options.yaml`

Inline Diagnostic Suppression

内联诊断抑制

dart-run-static-analysis

Original

Translation

Analyzing and Fixing Dart Code

Dart代码的分析与修复

Contents

目录

Analysis Configuration

分析配置

Diagnostic Suppression

诊断抑制

Workflow: Executing Static Analysis

工作流：执行静态分析

Workflow: Applying Automated Fixes

工作流：应用自动修复

Examples

示例

Comprehensive analysis_options.yaml

完整的analysis_options.yaml

Inline Diagnostic Suppression

内联诊断抑制

Comprehensive
`analysis_options.yaml`

完整的
`analysis_options.yaml`