1. 为什么 Flutter 覆盖率采集总在 CI 里卡壳Flutter 代码覆盖率这件事本地跑flutter test --coverage很轻松但一旦要统计线上真实用户跑过哪些类难度就完全不一样了。单元测试覆盖率只能告诉你测试用例覆盖了多少没法回答「这个页面在线上还有没有人用」这种业务问题。真正要推动废弃业务下线、给包体瘦身找数据依据需要的是线上类级别的代码覆盖率。FlutterCodeX 解决的正是这个问题编译期通过 AspectD 做 AOP 插桩在每个类构造函数执行后打一个标记运行时聚合上报最后和构建产物里的完整类列表比对得到线上覆盖率。听起来链路很清晰但落到 CI 里就会遇到几个很烦的点插桩插件要跑build_runnerAspectD 的 kernel 变换依赖特定 Dart SDK 版本多环境dev/staging/prod的配置散落在config.toml、settings.json、CI 变量里再加上工具侧调用模型或代码生成服务时的 Key 管理混乱很容易出现「本地能插桩、CI 上产物为空」的情况。这篇就按我实际搭过的一条链路来讲从 AspectD 插桩原理到 FlutterCodeX 覆盖率上报再到用 TaoToken 把工具侧的 Key 和 API 通道统一收口。适合正在给 Flutter 工程做包体治理、准备在 CI 里落地覆盖率采集的同学。全程给可复制的配置骨架和验证命令不讲空话。2. AspectD 插桩原理与 FlutterCodeX 的落点2.1 为什么不能直接改构造函数Dart 的类初始化顺序是字段声明初始化 → initializer list → 父类构造 → 自身构造。最直觉的做法是在构造函数里插一行上报代码但 Flutter 里大量 Widget 用的是const构造函数而常量构造器要求所有成员都是final且必须在编译期确定。你没法往里面塞一个运行时调用的ReportUtil.addCallTime(A)。class A { final num x, y; const A(this.x, this.y); // 这种类无法直接注入运行时逻辑 }所以「注入代码」这条路在常量构造器面前直接堵死。剩下的选择就是 AOP在编译期对 dill 文件做变换hook 住构造函数调用点。2.2 AspectD 的 Transform 机制AspectD 是面向 Dart 的 AOP 框架核心是在 kernel 层做 dill 变换。它通过Aspect、Call、pragma(vm:entry-point)这些注解把切面代码织入目标类的构造函数。对常量构造器、无显式构造函数、ClassName.identifier命名构造这几种情况都能覆盖。Aspect() pragma(vm:entry-point) class CodeXExecute { pragma(vm:entry-point) CodeXExecute(); Call(package:flutter_codex_demo/test.dart, A, A) pragma(vm:entry-point) void _incrementA(PointCut pointcut) { pointcut.proceed(); // 构造函数执行完毕后标记类 A 已被调用 } }pointcut.proceed()先执行原始构造函数返回后再打标记这样不会影响业务逻辑。FlutterCodeX 的编译期插件就是自动生成这些CodeXExecute类用build_runner跑CodeXGenerator配合CodeAstVisitor遍历工程内所有类的 AST找出每个构造函数生成对应的切面文件同时把完整类列表写进构建产物。2.3 运行时聚合与上报运行时每个类初始化后都会调用一次addCallTime把类调用信息缓存在内存里。等用户退到后台的时机把数据压缩后上传。这里通常会按活跃用户数设采样率命中足够大的 UV 样本即可不必全量上报。最后把线上数据和构建产物里的完整类列表做差集就得到覆盖率。3. TaoToken 前置把工具侧 Key 和 API 通道收口插桩链路本身不依赖外部服务但 FlutterCodeX 在 CI 里往往还要配合代码生成、模型辅助分析、覆盖率报告解读这类工具侧调用。这些调用如果每个环境各配一套 Key很快就会乱dev 的 Key 写死在settings.jsonprod 的 Key 塞在 CI secret 里换一次 Key 要改五六个地方。我的做法是用 TaoToken 统一收口工具侧的 Key 和 API 通道。它提供兼容 OpenAI 风格的接口工具侧只要把 base_url 指向统一入口Key 从环境变量注入多环境就只剩一个变量差异。先拿到访问凭证进入控制台创建 API Key地址是https://taotoken.net/console。创建后复制出来注意它只显示一次。# 本地和 CI 都用同一个变量名避免配置分散 export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类编码工具接入文档里有对应的环境变量写法参考https://taotoken.net/doc。需要长期跑编码或 Agent 任务的可以看 Coding Planhttps://taotoken.net/coding-plan按额度走比单次调用更好控成本。注意Key 只放环境变量或 CI secret不要提交进仓库。config.toml和settings.json里只写变量引用不写明文。4. 可复制配置config.toml 与 settings.json 骨架4.1 config.toml这份配置管插桩插件和上报通道环境相关的值全部走变量引用。[codex] # 插桩开关CI 上按分支决定是否开启 enable true # 采样率按活跃用户规模调整 sample_rate 0.1 # 上报时机后台 / 退出 report_trigger background [codex.aspectd] # AspectD 变换入口指向生成的切面目录 aspect_dir lib/generated/codex_aspects # 完整类列表产物路径用于后续比对 class_list_output build/codex/class_list.json [codex.report] # 统一走 TaoToken 通道避免多环境 Key 分散 base_url ${TAOTOKEN_BASE_URL} api_key ${TAOTOKEN_API_KEY} # 上报接口路径 endpoint /v1/report/coverage timeout_ms 8000 [codex.env] # 多环境只改这一处 name ${APP_ENV}4.2 settings.json这份给 FlutterCodeX 的 build_runner 插件和工具侧读取字段和config.toml对齐。{ codex: { enable: true, sampleRate: 0.1, aspectDir: lib/generated/codex_aspects, classListOutput: build/codex/class_list.json, report: { baseUrl: ${TAOTOKEN_BASE_URL}, apiKey: ${TAOTOKEN_API_KEY}, endpoint: /v1/report/coverage, timeoutMs: 8000 }, env: ${APP_ENV} } }4.3 CI 里注入变量以 GitHub Actions 为例把 Key 放 secret环境名按分支映射。- name: Run FlutterCodeX instrumentation env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} TAOTOKEN_BASE_URL: https://taotoken.net/api APP_ENV: ${{ github.ref refs/heads/main prod || staging }} run: | flutter pub get dart run build_runner build --delete-conflicting-outputs flutter build apk --release这样 dev、staging、prod 三套环境共用同一份配置骨架差异只在APP_ENV和对应的 secretKey 管理不再分散。5. 验证请求确认插桩产物与覆盖率数据正常生成配置写完别急着上 CI先在本地跑一遍确认链路通。第一步确认插桩产物生成。# 清理旧产物后重新生成 dart run build_runner clean dart run build_runner build --delete-conflicting-outputs # 检查切面文件和类列表是否生成 ls lib/generated/codex_aspects | head cat build/codex/class_list.json | head -c 300class_list.json里应该能看到工程内所有类的全限定名切面目录里每个类对应一个CodeXExecute文件。如果切面目录为空多半是build_runner没识别到注解检查build.yaml里 generator 是否注册。第二步验证上报通道能通。用一条 curl 模拟上报确认 TaoToken 通道和 Key 正常。curl -s -o /dev/null -w %{http_code}\n \ -X POST ${TAOTOKEN_BASE_URL}/v1/report/coverage \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d {env:local,classes:[A,B],sample:1}返回 200 说明通道和 Key 都没问题。如果返回 401是 Key 没注入或写错返回 404检查endpoint路径是否和文档一致。第三步跑一次真机或模拟器触发几个页面后退出到后台看日志里有没有上报记录。flutter run --release # 触发页面跳转后按 Home 退到后台 # 观察日志中的 codex report 输出日志里出现codex report success, class count: N就说明运行时采集和上报都通了。把上报数据和class_list.json做差集就是这一轮的覆盖率。6. 本篇常见错排查6.1 插桩产物为空最常见的原因是build_runner没跑或跑失败。先看build.yaml里 generator 是否注册再确认dart run build_runner build有没有报错。AspectD 对 Dart SDK 版本敏感SDK 和 AspectD 版本不匹配时变换会静默失败产物目录是空的但不报错。锁定 SDK 版本别用太新的。6.2 常量构造器类没被插桩如果发现某些 Widget 类没进class_list.json检查CodeAstVisitor是否覆盖了ClassName.identifier形式的命名构造。早期版本只处理了默认构造命名构造会漏。升级 FlutterCodeX 插件到支持命名构造的版本。6.3 上报 401 或 404401 基本都是 Key 问题环境变量没注入、Key 复制时带了空格、或者 CI secret 名字写错。404 是路径问题确认endpoint和接入文档里写的一致。这两个错误在本地 curl 一遍就能定位别等到 CI 上才查。6.4 多环境配置串了典型表现是 staging 的数据上报到了 prod 通道。根因是APP_ENV没按分支正确映射或者config.toml里某处写死了环境名。把所有环境相关字段都改成变量引用CI 里只注入APP_ENV就不会串。6.5 覆盖率数据对不上线上上报的类数量和class_list.json差很多先确认采样率是不是太低导致样本不足再检查构建产物是不是当次 CI 生成的。如果class_list.json是上一次构建的缓存差集结果自然不对。CI 里每次构建前清掉build/codex目录。7. 继续接入与工具侧配置链路跑通后工具侧的 Key 和通道统一交给 TaoToken 管理就够了。需要新建或轮换 Key 的去 API Keys 页面操作https://taotoken.net/api-keys。接入细节和参数说明看文档https://taotoken.net/doc。想先验证模型通道是否正常可以用模型对话页面发一条测试请求https://taotoken.net/models。长期在 CI 里跑编码或 Agent 任务的走 Coding Plan 更划算https://taotoken.net/coding-plan。我踩过的坑是一开始把 Key 写进了settings.json提交到仓库后来换 Key 时发现历史提交里全是明文只能整个仓库改。从那以后所有 Key 一律走环境变量配置文件里只留${VAR}引用。你按上面的骨架搭多环境就只剩一个APP_ENV的差异插桩产物和覆盖率数据都能在本地先验证再上 CI省掉大量来回排查的时间。