上个月在迁一套 Flutter 大型工程到鸿蒙环境时我几乎被依赖关系整懵了模块越拆越多flutter analyze不报错一跑构建就提示循环依赖定位问题全靠肉眼扫import。后来翻了半天工具链发现 layerlens 这个项目能直接分析 Dart 包的依赖关系、自动生成 Mermaid 图甚至可以把循环依赖单独摘出来。但它默认只认纯 Flutter 工程结构放到鸿蒙工程里根本跑不动。折腾了一周我把这条鸿蒙化适配路线完整跑通了这篇文章就把整个过程、脚本逻辑和踩过的坑一次性讲清楚。先说结论layerlens 本身不复杂真正的难点在于“鸿蒙工程的 Flutter 模块往往被 DevEco Studio 包了一层pubspec.yaml 位置、Dart 缓存路径、文件扫描范围全都变了”。只要把这几处适配掉你就能在鸿蒙工程里持续得到可视化依赖图大工程的循环依赖基本可以做到“从图上一眼揪出来”。1. layerlens 的价值先搞清楚它到底能解决鸿蒙工程里的什么问题1.1 layerlens 是什么把 Flutter 代码架构变成一张能自动生成的 Mermaid 依赖图layerlens 是 Flutter 生态里的一个依赖分析工具核心功能很纯粹扫描工程里的pubspec.yaml和 Dart 源码的import关系然后输出结构化的依赖数据。它能干三件实际的事生成 package 级别的依赖图也就是“哪个 package 依赖了哪个 package”。生成文件级别的依赖图精确到lib/目录下每一个 Dart 文件之间的引用关系。专门标记出循环依赖的链路并且用 Mermaid 语法输出可渲染的依赖图文本。举一个最简单的例子你的工程里有app、core、feature_login三个模块core是整个底层基础库。layerlens 扫完之后输出 Mermaid 格式的flowchart文本放到支持 Mermaid 的编辑器或者 git 平台的 Markdown 预览里立刻就能看到一张结构图。为什么这对鸿蒙工程特别重要因为鸿蒙侧的 Flutter 应用往往不是单个 package而是由一个原生壳工程加一个 Flutter 业务模块构成的。业务模块内部如果再拆成多个本地 package依赖关系就会迅速膨胀。人工维护架构图根本没有可行性layerlens 这类工具的价值在于“让架构透明化”而且是自动化、随时可再生的透明化。1.2 鸿蒙大工程的循环依赖痛点为什么必须做适配做鸿蒙开发的人都知道现阶段鸿蒙工程和传统 Flutter 工程在目录组织上有一些明显的差别。最常见的工程布局长这样HarmonyOSProject/ ├── AppScope/ ├── entry/ ├── hvigor/ ├── oh-package.json5 └── flutter_module/ ├── pubspec.yaml ├── lib/ └── ...Flutter 业务代码被放在一个独立的模块目录里pubspec.yaml不在工程根目录而在flutter_module子目录下。layerlens 默认从当前目录向上找pubspec.yaml如果你在鸿蒙工程根目录直接执行flutter pub run layerlens它要么找不到入口要么扫出来的依赖范围完全不对。更要命的是循环依赖。鸿蒙 Flutter 工程因为模块化起步较晚很多团队习惯性地把公共组件、网络层、工具类塞进一个shared包结果业务模块和shared互相引用箭头绕了一圈又回到起点。这类循环依赖在日常开发里并不容易暴露因为 Dart 语言允许你 import 循环引用的文件只要不出现顶层初始化互斥编译期不一定会报错。但一旦工程规模变大、并行编译开启简单的循环依赖就可能导致构建失败或者热重载时出现诡异状态。layerlens 的强大之处在于它会把所有绕圈子的路径找出来。根据我的使用经验它对“A 依赖 B、B 依赖 A”这种直接环以及“A 依赖 B、B 依赖 C、C 依赖 A”这种间接环都识别得比较准。把这个能力搬到鸿蒙工程里等于给架构治理装上了一台 X 光机。2. 鸿蒙化适配前的准备环境差异与适配思路2.1 环境差异对照表鸿蒙工程和原生 Flutter 工程的结构差异在动手之前我先把两种工程环境的差异做成了一张对照表后面所有适配工作都是围绕这张表展开的维度原生 Flutter 工程鸿蒙工程含 Flutter 模块pubspec.yaml 位置工程根目录通常在flutter_module或类似子目录原生依赖管理pubspec.yaml 直接管理同时存在 oh-package.json5两者可互不影响Dart 缓存路径~/.pub-cache或全局 PUB_CACHE与原生一致但鸿蒙 IDE 可能自定义 SDK 路径构建系统flutter buildhvigor 驱动Flutter 模块仍由 flutter 工具链构建lib 目录根目录 lib/在 Flutter 模块内的 lib/常用 IDEAndroid Studio / VS CodeDevEco Studio这个对照表的意义在于layerlens 需要读的两个核心输入一个是pubspec.yaml所在的模块根目录另一个就是要扫描的lib目录路径。只要把这两条路径指对其他都是体力活。另外一点容易被忽略的是PUB_CACHE环境变量。在鸿蒙开发机上尤其是一些统一配置了 CI 环境的团队PUB_CACHE 通常不是默认位置。layerlens 在解析依赖时需要定位真实缓存的包内容如果缓存路径不对分析结果可能缺包少包。适配脚本里必须显式处理。2.2 适配方案选型为什么我选择脚本包装而不是改源码刚开始我考虑过两条路线一是 fork layerlens 源码在它的解析逻辑里硬编码鸿蒙路径二是写一套包装脚本在鸿蒙工程下临时构造一个“类 Flutter 工程视图”让 layerlens 误以为自己在原生 Flutter 工程里运行。最终我选了第二种方案。原因有三个layerlens 本身更新频率不高但如果 fork 源码以后上游升级合并会很痛苦维护成本全部转移到自己身上。鸿蒙工程里 Flutter 模块的目录结构其实是固定的包装脚本只需要做几件事定位pubspec.yaml、指定lib目录、设置正确的输出路径。包装脚本是纯 Dart 或 Shell 实现的不依赖鸿蒙 IDE 的内部 API即使鸿蒙 IDE 升级脚本也能继续用。简单说方案选型的原则是“能不碰源码就不碰源码”。工具是别人的适配逻辑是自己的分离得越干净后续越省心。3. 实操过程把 layerlens 跑在鸿蒙 Flutter 模块上3.1 第一步确认 Flutter 模块位置与依赖注入方式先看你的鸿蒙工程里的 Flutter 模块到底叫什么名字。有的工程叫flutter_module有的叫flutter还有的干脆叫app。不管叫什么你只要找到那个同时包含pubspec.yaml和lib/的目录就是切入点。我建议直接在模块目录下打开终端先跑一次常规命令验证基本环境cd flutter_module flutter --version flutter pub getflutter pub get很重要它会保证依赖解析结果写入pubspec.locklayerlens 分析依赖时以实际解析结果为准。如果这一步就报错先解决网络源或者镜像配置的问题再继续。接下来把 layerlens 加入dev_dependencies。注意它只需要在开发环境使用不要加到dependencies里dev_dependencies: layerlens: ^0.2.1然后再次执行flutter pub get这一步会拉取 layerlens 及其依赖的下游包。如果公司内部有 pub 镜像这个动作会在镜像库完成。3.2 第二步理解 layerlens 的三种输出模式layerlens 常见的启动方式是flutter pub run layerlens具体子命令可以在 package 文档里查。我实际用下来最常用的是三个输出能力输出类型命令 / 入口实际用途package 依赖图layerlens graph显示各 package 之间的依赖关系文件依赖图layerlens graph --lib显示 lib 目录内文件的 import 关系循环依赖报告layerlens cycles单独列出构成环的节点和链路段需要说明的是我在实际操作中使用了dart run作为替代启动方式。在较新的 Flutter SDK 里flutter pub run和dart run都可以但是dart run对参数传递更友好。当然不同版本的 layerlens 子命令命名可能不同能跑通为准。真正要花心思的是参数传入。在鸿蒙工程里因为当前目录下pubspec.yaml位于子模块layerlens 的默认入口会找不到根。包装脚本的核心逻辑在这里统一处理。3.3 第三步写适配脚本解决路径识别和缓存定位我写了一个 Dart 入口脚本放在鸿蒙工程根目录下的tool/文件夹里不污染 Flutter 模块。它的核心工作分四个步骤。第一步定位模块目录import dart:io; String findFlutterModule(String workingDir) { final candidates [flutter_module, flutter, app]; for (final name in candidates) { final abs Directory($workingDir/$name); if (abs.existsSync() File($workingDir/$name/pubspec.yaml).existsSync()) { return abs.path; } } return workingDir; // 找不到就回退到当前目录 }第二步设置PUB_CACHE。这一步是为 CI 环境准备的。鸿蒙工程的流水机上可能设置了独立的缓存目录我们读出环境变量找不到再回落默认值String resolvePubCache() { final envValue Platform.environment[PUB_CACHE]; if (envValue ! null envValue.isNotEmpty) { return envValue; } if (Platform.isWindows) { return ${Platform.environment[LOCALAPPDATA]}\\Pub\\Cache; } return $home/.pub-cache; }第三步拼接 layerlens 命令行参数。ProcessResult runLayerlens(String modulePath, ListString args) { return Process.runSync( flutter, [pub, run, layerlens, ...args], workingDirectory: modulePath, environment: { PUB_CACHE: resolvePubCache(), PUB_HOSTED_URL: Platform.environment[PUB_HOSTED_URL] ?? , }, ); }第四步把输出重定向到鸿蒙工程根目录的docs/dependency-graph/下。这样生成物不会散落在 Flutter 模块里也不会被 DevEco Studio 误当作工程资源。void saveOutput(String content, String fileName) { final outDir Directory(docs/dependency-graph); if (!outDir.existsSync()) { outDir.createSync(recursive: true); } File(${outDir.path}/$fileName).writeAsStringSync(content); }这套脚本实际跑一次之后核心价值就体现出来了你不再需要记忆复杂的 layerlens 参数只要在鸿蒙工程根目录执行一个命令就能拿到最新的依赖图。3.4 第四步生成依赖图并确认关键链路脚本写完我在一个测试模块上跑了一次。生成出来的文件内容大致长这样flowchart TD app -- core app -- feature_login feature_login -- core feature_login -- shared shared -- core core -- shared }注意看core -- shared和shared -- core这条双向边这就是典型的循环依赖。layerlens 的循环报告也会用文字形式列出来core - shared - core把这份文本放到任意支持 Mermaid 的编辑器里渲染出来的图会把绕圈子的那两条线显示得很清楚。然后把这份文本提交到 git 仓库每次代码变更后重新生成团队成员在 Review MR 的时候就能直接看到依赖关系变化。这一步对鸿蒙大工程的架构收敛至关重要。4. 循环依赖治理实战从图到架构整改4.1 从 Mermaid 依赖图定位循环依赖的三个步骤图生成之后如果只拿来“看看”就浪费了。我整理了一套实用的读图方法第一步先看双向箭头。依赖图里如果有两个节点互相指向对方这就是最低级的循环依赖也是最应该最先消灭的。第二步沿着叶子节点反向推。从没有出边的包开始反向梳理依赖观察哪些路径绕了一圈回到起点。这类间接环比直接环隐蔽得多。第三步对照 cycles 报告的文本链路段逐段确认依赖方向。有时候一个环可能跨四五个模块比如feature_a依赖feature_bfeature_b依赖sharedshared又依赖feature_a。这种链路在图上很清晰但在代码里很难一眼发现。来看一个我实际处理过的案例。原工程里存在这样一段环依赖路径造成原因feature_a - feature_bfeature_a 需要调用 feature_b 的某个列表页组件feature_b - sharedfeature_b 使用了 shared 里的统一网络库shared - feature_ashared 里的某个工具类引用了 feature_a 的类型定义这种环的荒谬之处在于shared本来应该是被所有业务模块依赖的底层包结果反向依赖了业务模块。定位到具体代码后发现只是shared里的一个常量文件引用了feature_a的枚举类型。解决办法是把那个枚举挪到shared或者单独抽一个core_enum包。4.2 治理策略依赖倒置、Provider 解耦、抽公共模块清理循环依赖不是单纯地把 import 删掉而是要用正确的架构手段把环切断。我实际操作下来最有效的三种策略分别是依赖倒置、状态提升和模块下沉。依赖倒置的典型做法如果shared包需要某种回调能力但回调类型定义在业务包那么不要让shared直接依赖业务包而是在shared里定义一个抽象接口业务包去实现它。放一段简单的示例说明// shared 包里的定义 abstract class UserInfoProvider { String get displayName; } // feature_a 包里的实现 class FeatureAUserInfoProvider implements UserInfoProvider { override String get displayName 来自 feature_a 的用户; }业务包实现底层包的接口依赖方向就变成了feature_a - shared环被直接切断。这种做法在鸿蒙的 Flutter 工程里尤其重要因为鸿蒙侧经常通过 native 通道获取用户信息这类回调用不好就会把底层包和服务层绑死。第二种思路是状态提升。很多循环依赖其实是因为两个模块共享了某个运行时状态比如登录状态、主题配置。与其让两个模块互相依赖不如把状态放到更上层的模块由更上层统一管理。这也正好契合 Flutter 社区常用的 Provider 模式业务组件不需要互相 import只需要从共同的 Provider 获取状态。下面是一个用 Provider 切断循环依赖的例子。原本feature_a直接 import 了feature_b的某个状态类导致两者绑定改完之后状态定义被提升到core包feature_a和feature_b各自通过 Provider 读取互不 import// core 包 class SessionState extends ChangeNotifier { bool isLoggedIn false; } // feature_a 里不再 import feature_b 的任何文件 final session context.watchSessionState();这种做法的收益在鸿蒙工程里会被放大因为鸿蒙原生侧的状态回传往往是一个全局事件业务模块本来就需要跨模块共享同一份状态用 Provider 做解耦比互相引用的方式干净得多。第三种策略是模块下沉。如果feature_a和feature_b都依赖一个公共类型而这个类型目前恰好定义在其中一个模块里那就把它下沉到shared或core。下沉之后依赖关系从互相引用变成了单向依赖环自然消失。实际操作中我建议每一次重构都重新跑一遍 layerlens对比图里环的数量。如果环减少了说明治理有效如果新增了环也能第一时间发现。把依赖图分析纳入日常开发节奏比一个月后统一治理要轻松得多。5. 常见问题与排查实录跑不起来、图形错乱、漏检全在这5.1 常见问题排查速查表适配过程中我整理了下面这张速查表按“现象 - 原因 - 处置”的思路直接照着查现象常见原因处置方式在鸿蒙工程根目录运行 layerlens 提示找不到 pubspec.yaml模块目录没被识别检查脚本里候选目录名改成实际模块名依赖图缺少部分本地包pubspec.yaml用了path依赖但路径解析失败确认 path 路径是相对模块目录还是相对工程根目录生成的文件在 Mermaid 渲染时报语法错误节点名包含特殊字符或中文路径在 Mermaid 节点文本外层加引号或做转义cycles 报告为空但实际存在环扫描范围没有包含lib/src等自定义目录手动加参数指定额外扫描目录flutter pub run 找不到 layerlens 命令dev_dependencies 写错位置或没有 pub get检查 pubspec.yaml 缩进重新 pub get在 DevEco Studio 里执行脚本输出目录被 IDE 缓存生成物写入了 Flutter 模块非标准目录重定向到工程根目录 docs/dependency-graph分析结果和 CI 环境不一致PUB_CACHE 路径不一致脚本里显式设置环境变量最容易被忽视的就是 pubspec.yaml 里的path依赖。原生 Flutter 工程通常会写成../shared而鸿蒙工程里因为 Flutter 模块本身已经处于子目录这个相对路径很可能跑偏。layerlens 扫描的时候用的是模块根目录作为基准路径不对就会漏包。5.2 我踩过的三个坑细说卡脖子细节第一个坑是 DevEco Studio 的终端环境和系统终端的差异。DevEco Studio 内置终端默认会加载一些额外的环境变量包括可能被设置过的PUB_CACHE。如果我用系统终端跑脚本能出图换到 IDE 内置终端就跑不动十有八九是环境变量被改了。解决方式很简单在脚本里强制设置PUB_CACHE不依赖外部传入。第二个坑是 Mermaid 节点名里的点号。Dart 包名和路径里经常出现点号比如shared.network.model直接放进 Mermaid 文本会被当成类名的一部分某些渲染器会报错。处理方式是给节点名加方括号或者统一做一层名称映射。layerlens 本身的设计是做了处理的但适配脚本如果二次加工了文本就必须再处理一次。第三个坑是鸿蒙工程里同时存在多个 Flutter 模块。有些大型工程会把业务拆成多个 Flutter 模块嵌在同一个鸿蒙壳里每个模块都有自己的pubspec.yaml。layerlens 一次只能分析一个模块如果只跑一次就以为看到了全局那是误判。我的做法是写一个循环把每个 Flutter 模块都跑一遍把多个 Mermaid 文件合并进同一份报告。合并的时候注意节点重名问题建议给每个模块的节点加前缀。5.3 独门技巧把 layerlens 接进 CI让架构图自动留在主仓库适配脚本跑通之后我用它做了最后一件事接入 CI。鸿蒙工程的 CI 里可以挂一个阶段在每次 MR 合入主干前自动执行依赖图生成脚本并把产物提交到docs/dependency-graph目录。如果检测到新增循环依赖脚本直接以非零状态退出阻断合入。大致的伪代码流程是这样的flutter pub get dart run tool/gen_dependency_graph.dart dart run tool/check_cycles.dartcheck_cycles.dart里的核心逻辑很简单解析 layerlens 的 cycles 输出统计环的数量超过阈值就抛异常。我见过不少团队用 eslint 靠规则约束代码风格却没有人约束模块之间的依赖方向。接上这个检查之后循环依赖基本失去了进入主仓库的机会。一点务实建议如果你要在一个规模较大的鸿蒙 Flutter 工程里推这个方案我建议别一上来就做全员工具培训先自己在本地跑通脚本生成当前工程的依赖图把可观的循环依赖列表整理出来后再带着数据去和架构组对齐。有了图和报告讨论“怎么拆”就变得非常具体而不是靠感觉。layerlens 的鸿蒙化适配并不复杂但它的价值不在于“能跑”而在于让团队重新看见依赖关系。架构治理的第一步永远是看清楚现状这个工具能把这一步的成本降到最低。