跨平台开发 / 系统课时
配置 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。
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:
void main() {
print("hello");
}这里同时违反 avoid_print 和 prefer_single_quotes。执行:
dart analyze bin/config_demo.dart预期结果中应看到两个规则代码,其中 avoid_print 的严重级别是 warning,prefer_single_quotes 保持为 info。
avoid_print => warning
prefer_single_quotes => info如果完全没有看到 avoid_print,先检查 analysis_options.yaml 是否位于当前包根目录、YAML 缩进是否正确,以及 linter.rules 下是否真正启用了该规则。
调整严重级别而不是随意关规则
团队可以在 analyzer.errors 中把某条诊断设置为 error、warning、info 或 ignore。例如,如果生产代码绝不允许直接 print,可以把配置改成:
analyzer:
errors:
avoid_print: error
linter:
rules:
avoid_print: true再次执行分析:
dart analyze bin/config_demo.dart预期结果:
avoid_print => error严重级别提升后,代码本身没有变化,但质量门禁会更严格。相反,ignore 会让该诊断不再报告,应只在有明确兼容性原因时使用。
控制例外范围
全局配置适合稳定、统一的团队规则;生成代码适合通过 exclude 排除;单个历史文件或特定语句确有例外时,可以使用 ignore_for_file 或 // ignore: <RULE> 做局部抑制。局部忽略应尽量附带原因,避免以后的人误以为规则已经失效。
配置完成后,应在持续集成和本地开发中执行同一套 dart analyze。这样规则变更、严重级别和排除范围都由版本库中的 analysis_options.yaml 决定,质量门禁不会依赖某个开发者 IDE 的个人设置。