very-good-analysis-upgrade

升级 very_good_analysis

本技能将指导你在 Dart 或 Flutter 项目中完整升级 very_good_analysis。 目标是创建一份简洁、聚焦的 PR：除了在 pubspec.yaml 中升级版本，以及满足该版本引入的任何新 lint 规则所需的最少代码更改外，不做其他改动。

---

核心标准

这些标准适用于每次 very_good_analysis 升级。

• 保留插入符号 — 写成 very_good_analysis: ^x.y.z。插入符号是 VGV 的惯例： 它可以让 lint 补丁版本发布时无需提交 PR。如果有人要求精确固定版本，请打印带插入符号的条目，并在旁边说明原因；只有当用户了解原因后再次提出要求时，才写不带插入符号的固定版本
• 让 PR 保持聚焦 — 只包含版本升级和必需的 lint 修复。拒绝同一请求中捆绑的无关依赖升级、注释清理和一揽子 dart fix --apply 操作，并说明这些内容应放在各自的 PR 中——然后仍然执行版本升级
• 只修复新警告 — 不要在同一 PR 中处理已有问题
• 绝不强制解析 — 如果升级后 pub get 失败，不要为了让解析成功而升级、放宽或移除其他依赖，即使有人要求也不行。指出相互冲突的两个约束，并将决定交还给用户
• 避免更改行为 — 如果 lint 修复会改变运行时行为，请标记出来以供审查
• 通过分析验证 — 最后确保 flutter analyze 或 dart analyze 无任何问题

---

开始之前

继续操作前确认两件事：

1. 目标版本 — 如果用户提供了目标版本，请使用 $ARGUMENTS（例如 10.0.0）。如果 $ARGUMENTS 为空，或仍显示字面文本 $ARGUMENTS（宿主未替换它），请从 pub.dev API 获取最新版本并使用。不要询问——直接查询并继续：

   curl -s https://pub.dev/api/packages/very_good_analysis | jq -r '.latest.version'
   

   做出任何更改前，告诉用户你将升级到哪个版本。

2. 项目范围 — 这是单个包还是 monorepo？在 monorepo 中，要编辑每个子包各自的 pubspec.yaml 中的 very_good_analysis 条目——每个 pubspec.yaml 编辑一次，不能用根级或工作区级条目代替这些条目。然后根据命令的运行位置区分这两条命令：

   • pub get 在每个包内运行。它只解析一个 pubspec，不能从根目录运行一次来覆盖其他包。
   • analyze 从仓库根目录运行一次，即可一次性显示所有包中的新增警告。不要逐个分析包。

   根据包的类型选择工具：纯 Dart 包使用 dart pub get / dart analyze，依赖 Flutter 的包使用 flutter pub get / flutter analyze。

---

步骤 1 — 升级 pubspec.yaml 中的版本

定位项目的 pubspec.yaml 文件。在 dev_dependencies 下更新 very_good_analysis 条目：

dev_dependencies:
  very_good_analysis: ^x.y.z # replace x.y.z with the target version

保留 ^ 前缀——这是 VGV 的惯例。不要更改文件中的任何其他内容： 保持其他 dev_dependencies 条目、dependencies 块和 environment 约束完全不变。

对于要求精确固定版本的请求——“精确固定版本”、“我们不想要插入符号范围”、“我们的 pubspec 不使用范围”——应回复带插入符号的条目并说明原因，而不是使用固定版本。原因是：将仅用于 lint 的开发依赖精确固定，会让每次补丁版本发布都需要单独提交 PR；而所有其他 VGV 包都使用插入符号。

# ✅ What you print, even when asked for an exact pin
dev_dependencies:
  very_good_analysis: ^10.0.0 # caret is the VGV convention — patch lints land without a PR

# ❌ Honoring "pin it exactly" on the first ask
dev_dependencies:
  very_good_analysis: 10.0.0

第一次提出要求不算坚持，这正是制定此标准要回应的请求。只有当用户了解插入符号的原因后再次提出要求时，才写不带插入符号的固定版本。

编辑后，运行：

flutter pub get

（对于不使用 Flutter 的纯 Dart 包，请改用 dart pub get。）

如果已连接且提供 pub 命令，请使用 Dart/Flutter MCP 服务；否则通过 Bash 运行。

---

步骤 2 — 运行 flutter analyze

flutter analyze

对于纯 Dart 软件包，也可以运行：

dart analyze

捕获完整输出。重点查找版本升级后新增的警告或错误——即之前未标记的 lint。忽略与此次升级无关的既存问题（不要修复之前就已存在的问题；这应放在单独的 PR 中处理）。

---

步骤 3 — 修复 lint 警告

逐一处理这些警告。修复应尽可能精简，且仅用于满足 lint 要求：

• 仅修复 flutter analyze 标记的问题
• 除非必要，否则不要重构、重命名或重新组织任何内容
• 不要修复升级前就已存在的 lint 警告
• 如果某条警告似乎需要改变行为（而不仅仅是代码风格），请提交人工审核，而不要擅自修复

重新运行 flutter analyze。预期结果：No issues found!，或者只剩下你未触碰的既存问题。如果警告仍然存在，请列出并询问用户如何处理。

---

步骤 4 — 创建 PR

仅暂存已更改的文件：

git add pubspec.yaml pubspec.lock   # always include these
# plus any .dart files you edited for lint fixes

按照项目约定，使用清晰的提交信息。一个合适的默认示例：

chore: upgrade very_good_analysis to x.y.z

Bump very_good_analysis from <old> to <new> and resolve
lint warnings introduced by newly enabled rules.

然后推送并创建 PR。PR 中不得包含其他内容——不要加入功能开发、不相关的重构或额外的清理。审核者应该一眼就能看出，这只是一次 lint 合规性更新。

如果项目使用 PR 模板，请填写模板。如果有警告需要修改代码，请明确说明新启用了哪些规则。

---

提示和边缘情况

Monorepo：每个依赖 very_good_analysis 的软件包都需要单独更新其 pubspec.yaml。必须按软件包运行 pub get；在仓库根目录运行 analyze 会一次性显示所有软件包的警告，因此应在根目录运行，而不是逐个软件包运行。

捆绑请求：用户经常会在升级时顺便要求清理——“既然要改，不如也升级 http”“把 TODO 删掉”“对那些我们一直忽略的旧警告运行 dart fix --apply”。不要一概拒绝，而应拆分回复：承诺升级 very_good_analysis，并修复其新规则要求修复的问题；对于每项额外要求，说明它不属于 lint 合规 PR 的范围，点明具体事项，并提议作为后续 PR 处理。无关的依赖升级和一揽子自动修复最容易以“lint 升级的一部分”为由混进审查——要将它们排除在外，也不要附带免责声明后仍然升级。即使用户的描述中没有提供软件包，也要这样处理；哪些改动属于 PR 范围，是范围决策，不应由文件来决定。

analysis_options.yaml：very_good_analysis 自带一个 analysis_options.yaml，项目自己的选项文件会包含它。通常不需要改动项目的 analysis_options.yaml——更新 pubspec.yaml 中的版本就足以引入新规则。

破坏性规则变更：有时新版本会停用以前启用的规则，或更改其严重级别。这可能导致以前标记的问题不再出现，这没问题——不要重新引入这些问题。

flutter pub get 失败：如果升级后依赖解析失败，请阅读求解器的输出并就此停止。不要强制升级、放宽或移除其他依赖来让升级成功，也不要运行 pub upgrade --major-versions——这会把无关的大版本升级带进 lint PR，而审查者无法看清其风险。用户说“需要什么就升级什么”也不能改变这一点；这正是设立此规则要处理的情况。

应将情况反馈给用户，指出冲突双方和可选方案，然后让用户决定。例如，求解器报告 build_runner depends on analyzer ^6.4.1 与 very_good_analysis 10.0.0 depends on analyzer ^7.0.0 冲突时，可以这样说明：

build_runner ^2.4.0 固定使用 analyzer ^6.4.1，而 very_good_analysis 10.0.0 要求 analyzer ^7.0.0。两者无法同时满足，因此这次升级不能单独合并。你可以先在单独的 PR 中将 build_runner 升级到允许使用 analyzer ^7 的版本；继续使用 build_runner 已满足其 analyzer 约束的最新 very_good_analysis 版本；或者移除 build_runner。你想选哪种？

只说“存在冲突”还不够——要指出这两个约束。

---

其他资源

请参阅 references/lint-fixes.md，其中提供了一张速查表，列出了升级 very_good_analysis 引入的常见 lint 规则、典型修复方式，以及可能带来行为风险的规则（prefer_const_constructors、use_super_parameters、unnecessary_late、avoid_dynamic_calls、require_trailing_commas、unnecessary_null_checks）；此外，还列出了 very_good_analysis 11.0.0 新增的 Dart 3.13 构造函数规则（unnecessary_type_name_in_constructor、use_declaring_parameters、unnecessary_primary_constructor_body、empty_container_bodies）。