3.47 上线才五天，社区里就出现了两个让人哭笑不得的 issue。
有意思的是，这俩坑跟那些被反复讨论的新特性都没关系——不是 Impeller，也不是 Material 分家，而是一个几乎没人会去读 changelog 的迁移：AnalysisOptionsMigration。知乎这个版本发布后第一批被坑的，不是尝鲜新功能的人，而是被一个“帮你迁移”的工具误伤的老项目。
先说这个迁移本来想干嘛。之前有人反馈（issue #187728），FlutterFire 配合 Swift Package Manager 用的时候，build/ 目录会残留一些 Dart 文件，Analysis Server 会把这些生成内容当源码扫描，报出一堆没意义的错误。默认排除 build/ 这类目录，这个需求本身没毛病，PR #187940 就把这事做了。
问题出在它挂载的位置。这个迁移没挂在某个专门的“升级项目”命令里，而是直接接进了 FlutterProject.ensureReadyForPlatformSpecificTooling()——flutter pub get、flutter analyze、flutter run、flutter build 都会走的底层准备流程。知乎只要你在 3.47 上，日常每跑一次这些命令，它都会顺手“帮你改一下” analysis_options.yaml。
3.47 这版的迁移其实不止这一个：Material 分家配了专门的 dart fix --apply --code=migrate_design_widgets，官方连过渡桥都准备好了。小红书但那个迁移是你主动执行才跑的，而 AnalysisOptionsMigration 藏在日常命令里，改仓库文件之前不打任何招呼。
第一版实现有两个洞。
第一个洞：看不懂 include:（issue #191056）。很多团队——尤其是 monorepo——习惯把 lint 规则集中放在 company_lints 这类包里，每个项目的 analysis_options.yaml 只写一行 include:。Dart Analyzer 自己能正确处理，但 3.47 的迁移不解析 include，它只看当前文件里没有字面的 exclude，就判定“还没迁移”，硬塞一份重复的排除配置进去。知乎最恶心的是这事会反复发生：手动删掉，下次 flutter pub get 又给你加回来。git diff 被这个文件反复弄脏，CI 里要是有“工作区必须干净”的检查，直接红给你看。
第二个洞：不管你实际开了哪些平台（issue #191131）。第一版排除列表是固定的，只建了 Android 和 iOS 的项目，也会出现 web/、windows/、macos/、linux/。普通项目顶多难看，但对 Dart Web 开发者是真坑：dart create -t web 建的项目，源码就放在 web/ 目录。这个目录一旦被排除出分析，lint 静默失效，错误不再上报，而且没有任何提示。静态分析不报错，比报错可怕。
官方的修复来得很快：#191082 让迁移能递归解析 include:，相对路径、package: URI 都能解析到真实文件，还加了防互相 include 死循环的保护；#191151 更进一步，先判断这个包是不是依赖 Flutter——纯 Dart 包直接跳过，同时把固定七目录改成按项目实际存在的平台动态生成，顺带修了 flutter create 模板。知乎不过要提醒一句：目前能确认的是两个修复 PR 都已合并，是否已随 stable 通道的补丁版本推送，还没看到确切信息。动手之前先看一眼 flutter --version，以官方发布说明为准。
自查三件事：
已经升到 3.47 的，git diff 看一眼 analysis_options.yaml：出现重复的 exclude 块、从没开过的平台目录，就是中招了。
团队用 include: 集中管理配置、删了又复活的，是 #191056，手动删治标不治本，等修复版本落地，期间可以考虑锁 SDK 版本。
纯 Dart 或 Dart Web 项目，检查 analyzer.exclude 里有没有 web/。有，说明源码已被排除出静态分析——三条里最要紧的一条。
还没升级的不用慌，但这确实是多一个缓一缓的理由。3.47 本身有干货：Material 和 Cupertino 正式拆成独立包、Impeller 桌面三端全部默认，方向都是对的。知乎只是 Material 旧导入的弃用定在今年 11 月，时间还早，没必要抢着给回归问题当第一批用户。知乎
最后说句题外话。这次的事暴露的不只是一个 bug：迁移机制挂在日常命令上，“修改用户仓库文件”的门槛太低。11 月的 Material 弃用、12 月 CocoaPods Registry 转只读，后面迁移只会越来越多。以后每个新版本落地，先把 analysis_options.yaml 和 pubspec.yaml 的 diff 扫一遍，不亏。
你被工具“好心”改过配置文件吗？评论区聊聊。
