LocalSend 如何升级固定版本的 Flutter：需要同步更新哪四处

LocalSend 的 Flutter 版本不是由本机全局环境决定的，而是被固定（pinned）在仓库里的四处位置。如果你要把项目切换到新的 Flutter 版本（例如文档示例中的 3.41.9），只执行 fvm use 是不够的：漏改任何一处，本地 fvm flutter 使用的版本、CI 里 setup-flutter 拉取的版本、以及作为 git submodule 锁定的版本就会不一致，导致本地能跑而 CI 挂掉（或反过来）。

前提条件：已安装 Flutter SDK 与 fvm。仓库文档明确要求使用 fvm flutter / fvm dart 而不是系统级工具链，因此升级操作的第一步就是让 fvm 指向目标版本。

版本被固定在哪四处

AGENTS.md 的 "Flutter version" 一节给出的结论是：版本以 .fvmrc 为准，同时镜像在另外三个位置，"Bumping the version means updating all four places"。当前仓库中这四处分别是：

位置	当前内容	作用
.fvmrc	{"flutter": "3.41.9"}	fvm 读取的本地版本声明
app/pubspec.yaml	environment: flutter: ^3.41.0、sdk: ^3.11.0	pub 解析时的 Flutter 约束
.github/workflows/ci.yml	FLUTTER_VERSION: "3.41.9"，经 flutter-actions/setup-flutter@v4 使用	CI 中安装和检查所用的版本
support/submodules/flutter（git submodule，见 .gitmodules）	锁定到 flutter/flutter 仓库的某个 tag	仓库内固定的 Flutter 检出

升级步骤

以下命令来自 CONTRIBUTING.md 的 "Bump Flutter" 一节，原文以升级到 3.41.9 为例（恰好也是本仓库当前固定的版本）。如果你要升级到别的版本，把命令中的 3.41.9 整体替换为你的目标版本号，其余结构不变。

1. 让 fvm 指向新版本

fvm use 3.41.9

2. 更新 Flutter submodule

在仓库根目录依次执行：

git submodule update --init
cd support/submodules/flutter
git fetch
git checkout 3.41.9
cd ../../..
git add support/submodules/flutter

git fetch 会从 .gitmodules 中声明的 https://github.com/flutter/flutter.git 拉取 tag 信息，属于网络下载操作；git checkout 3.41.9 把子模块切到对应版本 tag；最后的 git add 不可省略，它记录子模块指针的变化，否则这次升级不会进入提交。

3. 更新 CI 中的版本约束

打开 .github/workflows/ci.yml，把 FLUTTER_VERSION: "3.41.9" 改为你的目标版本。该变量被多个 job 的 flutter-actions/setup-flutter@v4 步骤引用，改这一处即可同步所有使用点。

4. 更新 pubspec 中的 Flutter 约束

打开 app/pubspec.yaml，调整 environment 下的 flutter 约束使其与目标版本匹配，当前值形如 flutter: ^3.41.0（同文件还有 sdk: ^3.11.0）。文档只说明"更新约束"，没有规定具体写法，请按你目标版本对应的约束语义修改这一行。

升级后如何验证

按 AGENTS.md 的说明，验证时一律使用带 fvm 前缀的命令。先确认工具链能解析依赖并正常构建运行：

fvm flutter pub get
fvm dart run build_runner build
fvm flutter run

再跑一遍 CI 实际执行的检查（见 AGENTS.md "Checks (what CI runs)"）：

fvm dart format --set-exit-if-changed lib test
fvm flutter analyze
fvm flutter test

两点与格式检查相关的限制需要留意：仓库的代码格式是 150 列（analysis_options.yaml 中 page_width: 150），任何把生成的 Dart 重排成 80 列的工具都会制造噪音，必要时用 fvm dart format 恢复；另外 CI 在格式检查前会先删除 lib/gen，生成代码本身不参与格式校验。

限制说明

• 四处必须一起改，文档给出的顺序是 fvm → submodule → CI/pubspec，其中 submodule 需要显式 git add，是最容易被漏掉的一步。
• 本文命令中的 3.41.9 是源文档的示例目标版本；升级其他版本时替换所有出现处，并保证 .fvmrc、FLUTTER_VERSION、submodule 的 checkout tag 三者一致。
• 根目录 pubspec.yaml 是 Dart pub workspace 声明（app、packages/localsend_isolates、packages/typed_isolates 三个成员），pub get 从任一成员目录执行即可，它不涉及 Flutter 版本声明。