跨平台开发 / 系统课时

配置 analysis_options 规则

配置 analysis_options 规则

analysis_options.yaml 决定一个 Dart 包采用哪些静态分析规则、哪些路径不参与分析,以及某条诊断要按什么严重级别处理。本节通过一份可直接使用的配置,把团队规范、严重级别和生成代码范围放到同一个可验证的质量入口中。

学习目标

  • 在 analysis_options.yaml 中启用 lint 规则并排除不应分析的生成文件
  • 使用 analyzer.errors 调整特定诊断的严重级别
  • 通过 dart analyze 验证配置是否按预期生效

配置文件的职责边界

analysis_options.yaml 通常放在包根目录,与 pubspec.yaml 同级。analyzer 负责分析器行为,例如排除路径和诊断严重级别;linter.rules 负责启用或关闭 lint。配置还可以通过 include 复用共享规则文件,团队自己的覆盖项则保留在当前包中更容易审查。

配置不要把“规则是否启用”和“规则有多严重”混在一起理解:linter.rules 决定某个 lint 是否参与检查,analyzer.errors 则可以调整已经产生的诊断严重级别。

建立一份最小团队规则

下面的配置不依赖额外 lint 包,可以直接放到包根目录的 analysis_options.yaml。

yaml
analyzer:
  exclude:
    - build/**
    - lib/generated/**
  errors:
    avoid_print: warning

linter:
  rules:
    avoid_print: true
    prefer_single_quotes: true

这份配置有三个效果:build 和 lib/generated 下的文件不参与分析;avoid_print 被启用并调整为 warning;prefer_single_quotes 被启用并保持其默认严重级别。

exclude 应用于工具生成且团队不维护的代码,而不是拿来隐藏普通业务目录。规则作用范围越大,越应该通过公共配置管理;只有极少数例外才使用文件级或行级忽略。

用代码验证严重级别

创建 bin/config_demo.dart:

dart
void main() {
  print("hello");
}

这里同时违反 avoid_print 和 prefer_single_quotes。执行:

bash
dart analyze bin/config_demo.dart

预期结果中应看到两个规则代码,其中 avoid_print 的严重级别是 warning,prefer_single_quotes 保持为 info。

text
avoid_print => warning
prefer_single_quotes => info

如果完全没有看到 avoid_print,先检查 analysis_options.yaml 是否位于当前包根目录、YAML 缩进是否正确,以及 linter.rules 下是否真正启用了该规则。

调整严重级别而不是随意关规则

团队可以在 analyzer.errors 中把某条诊断设置为 error、warning、info 或 ignore。例如,如果生产代码绝不允许直接 print,可以把配置改成:

yaml
analyzer:
  errors:
    avoid_print: error

linter:
  rules:
    avoid_print: true

再次执行分析:

bash
dart analyze bin/config_demo.dart

预期结果:

text
avoid_print => error

严重级别提升后,代码本身没有变化,但质量门禁会更严格。相反,ignore 会让该诊断不再报告,应只在有明确兼容性原因时使用。

控制例外范围

全局配置适合稳定、统一的团队规则;生成代码适合通过 exclude 排除;单个历史文件或特定语句确有例外时,可以使用 ignore_for_file 或 // ignore: <RULE> 做局部抑制。局部忽略应尽量附带原因,避免以后的人误以为规则已经失效。

配置完成后,应在持续集成和本地开发中执行同一套 dart analyze。这样规则变更、严重级别和排除范围都由版本库中的 analysis_options.yaml 决定,质量门禁不会依赖某个开发者 IDE 的个人设置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 analysis_options 规则

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通