dart-flutter-sdk-upgrade

VGV Flutter/Dart SDK 升级 — 快速参考

每个项目一个 PR。只修改 CI 工作流和 pubspec.yaml — 不改逻辑、不升级依赖版本、不改测试。

---

核心标准

将这些标准应用于所有 SDK 升级工作：

• Flutter 和 Dart 版本不同 — Flutter 版本会随附一个 Dart SDK，其版本号与 Flutter 版本无关；pubspec 中的 sdk: 约束使用 Dart 版本号，绝不能使用 Flutter 版本号。请在发布归档页面 https://docs.flutter.dev/install/archive 中查找对应关系
• 绝不要凭记忆填写随附的 Dart 版本 — 不能凭回忆、不能根据 Flutter 版本推断，也不能照搬本文中的示例。Dart 版本必须由用户提供，或从归档页面查得，否则就询问。没有第四种来源
• Flutter CI 使用 MAJOR.MINOR.x — 不使用插入符；.x 通配符会解析为最新补丁版本
• Dart CI 使用精确补丁版本 — MAJOR.MINOR.PATCH，不使用插入符或通配符
• pubspec 固定精确补丁版本 — 使用 ^MAJOR.MINOR.PATCH，并指定具体补丁版本
• 纯 Dart 软件包 — 直接使用 Dart 版本，无需映射 Flutter 版本。CI 键在 dart_package.yml 中为 dart_sdk，而不是 flutter_package.yml 中的 flutter_version；环境块中使用 sdk:，旁边不写 flutter:
• 即使没有看到文件，也要写出 CI 块 — 可复用工作流及其版本键由软件包类型决定，因此未看到的工作流也有已知结构。请根据下方 CI 工作流部分生成 with: 块，并注明它应放在哪个文件中，而不是先询问文件
• 使用 pub get 和 analyze 验证 — 不要默默解决冲突
• 拒绝超出范围的修改，不要附加保留意见 — 如果用户还要求升级依赖、修复 lint 或修改代码，不要生成这些修改。交付 SDK 约束和 CI 修改，并将其余事项列为单独的后续工作

---

0. 确定目标版本

Flutter 会随附特定版本的 Dart，但两者的版本号无关。将 Flutter 升级到 3.35.5 并不意味着 Dart 约束应为 ^3.35.5，也无法通过任何规则从 Flutter 版本号推导出 Dart 版本号。因此，每次 SDK 升级都要先确定两个版本，而非一个：目标 Flutter 版本，以及该版本随附的 Dart 版本。

如何查找 Dart 版本：

1. 打开 https://docs.flutter.dev/install/archive
2. 找到目标 Flutter 稳定版
3. 记下与其并列列出的 Dart 版本

如果用户提供了 $ARGUMENTS，Flutter 目标版本就取自其中。如果 $ARGUMENTS 为空或仍显示字面文本 $ARGUMENTS（即宿主没有替换它），则使用同一页面上的最新 Flutter 稳定版。对于纯 Dart 软件包，无需进行版本映射：Dart 版本以 $ARGUMENTS 指定的版本为准，否则使用最新 Dart 稳定版。

无法访问归档页面时，这在没有网络连接的会话中很常见，不要凭记忆填补信息缺口。回忆出的版本对应关系经常有误，足以导致 pub get 失败，而且这种错误不会显现出来 — 差异看起来仍然合理。说明 Dart 版本必须从归档页面查得，指出该页面是信息来源，并请用户确认。如果用户已经提供了两个版本，就按其提供的版本使用，并说明哪个是哪个。

说明已确认的两个版本，并在编辑任何文件前征求确认。

---

1. CI 工作流 — .github/workflows/

VGV 软件包使用 VeryGoodOpenSource/very_good_workflows 可复用工作流。请保持 @v1 标签不变。Flutter 软件包使用 MAJOR.MINOR.x——不加插入符，使用字面量 x 作为 补丁版本通配符，让 CI 自动解析到最新补丁版本。Dart 软件包固定精确的 补丁版本。升级版本时，按需更新 MAJOR 和/或 MINOR （例如，3.41.x → 3.42.x 或 4.0.x）：

Flutter 软件包：

uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/flutter_package.yml@v1
with:
  flutter_version: "3.41.x" # ← MAJOR.MINOR.x, resolves to latest patch

纯 Dart 软件包——注意键名是 dart_sdk，而不是 flutter_version。使用 Dart 版本，而不是 Flutter 版本：

uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
with:
  dart_sdk: "3.11.0" # ← exact Dart version (not Flutter version)

如果文件使用 flutter_channel: stable，而不是固定版本， 请固定版本——VGV 始终在 CI 工作流中固定 Flutter 版本。

手头没有工作流文件时

VGV 软件包的 CI 是一个调用上述两个可复用工作流之一的单个作业，因此需要修改的代码块 完全取决于软件包类型。如果工作流位于另一个检出目录中，或者用户只是描述了工作流而未粘贴文件，请根据 上述格式编写 with: 代码块，而不是停下来等待文件。说明目标工作流和目标键——纯 Dart 软件包使用 dart_package.yml 和 dart_sdk，Flutter 软件包使用 flutter_package.yml 和 flutter_version——并将其作为要合并到现有作业中的代码块提供。

有两项内容不能以这种方式臆造。未看到文件时，不要编造周边的 name:、on: 或 jobs: 键，也不要猜测版本号。展示 with: 代码块，并注明它所属的文件。

# Pure Dart package, target Dart 3.11.0 — the block to merge into your existing job
uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
with:
  dart_sdk: "3.11.0"

---

2. pubspec.yaml 环境约束

格式为 ^MAJOR.MINOR.PATCH（插入符，精确补丁版本）。与 CI 不同，pubspec 固定特定的 补丁版本——即用户指定的版本，或升级时当前的稳定版本。

Flutter 软件包（在 dependencies 下包含 flutter:）：

environment:
  sdk: ^<dart-version> # ← the Dart version the target Flutter release ships
  flutter: ^<flutter-version> # ← the target Flutter release itself

这两个占位符是有意保留的。填写它们需要执行步骤 0 中的归档查询，而且这两个数字永远不会相同：若升级到 Flutter 3.35.5，flutter: 约束为 ^3.35.5，而 sdk: 约束应填写归档中与 3.35.5 并列列出的 Dart 版本。 把 Flutter 版本号写进 sdk: 是此类变更中最常见的错误。

纯 Dart 软件包（不依赖 Flutter SDK）：

environment:
  sdk: ^3.11.0 # ← Dart version only
  # no flutter: line

在单体仓库中，需分别更新每个软件包的 pubspec.yaml。共享 CI 工作流 只需更新一次。

---

3. 验证

在每个软件包目录中运行。如果有 Dart/Flutter MCP 工具，请使用；否则使用 Bash。

flutter pub get   # or: dart pub get  (for pure Dart packages)
flutter analyze   # or: dart analyze

如果 pub get 因依赖冲突失败，请报告冲突——不要默默通过升级软件包来解决。指出阻塞的软件包、其版本，以及与新版本冲突的 SDK 约束，然后将决定交还给用户：提升该依赖版本应作为单独的 PR 处理，不属于本次变更。如果 analyze 发现 SDK 升级引入的新错误，请报告，而不要在本次 PR 中修复。

请参阅 references/version-conflicts.md，了解如何阅读版本求解输出、冲突的三种形式、如何追踪传递依赖阻塞项，以及交还问题时使用的报告格式。

---

4. 超出范围的请求

用户经常会一口气要求升级 SDK 并顺带处理其他事项——“既然打开了 pubspec，就顺便升级这个包吧”“再修复新的 analyzer 警告，让 CI 通过”。 应当直接拒绝这些额外要求。对禁止的修改附带保留说明不算拒绝： 即使写明新依赖版本不该出现在 pubspec 中，却仍将其写入其中，最终提交的还是混杂的 PR。

因此，如果请求是“升级到新版 Flutter，提高 http 的约束版本，并修复两个 analyzer 警告”，返回的 pubspec 只修改 environment 区块，其他内容一概不动：

environment:
  sdk: ^<dart-version> # ← changed, Dart version from the archive
  flutter: ^<flutter-version> # ← changed, the target Flutter release

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0 # ← left alone, dependency bumps are a separate PR

然后明确说明你没有做哪些事，以及这些事应当在哪里处理：

• 依赖升级应放在单独的 PR 中——如果出现问题，混杂的差异无法进行二分定位
• analyzer 警告应当报告，而不是修复——列出文件、行号和规则，以便在此次变更之外处理

建议通过单独的 PR 后续处理。不要提出将其合并到当前 PR 中。

---

5. PR 范围检查

提交前，确认差异中仅包含：

• .github/workflows/*.yml
• pubspec.yaml（一个或多个）

git diff HEAD --name-only

建议的提交/PR 消息：

chore: bump Flutter to <flutter-version> / Dart to <dart-version>

- Update flutter_version in .github/workflows/ to MAJOR.MINOR.x (CI resolves latest patch)
- Update dart_sdk in .github/workflows/ to the exact Dart patch
- Update environment sdk/flutter constraints in pubspec.yaml

No logic or code changes.

主题行中应包含这两个版本号，这样审查者查看历史记录时就能知道此次升级对应的 Dart 版本。