在前端工程不断复杂化的今天，“代码能跑”已经远远不够。我们更关心：
- 🧩 模块之间是否耦合过深？
- 🔁 是否存在循环依赖？
- 📦 是否引入了冗余依赖包？
- 🧼 项目中有没有成堆“export但没人用”的死代码？
这就引出了本文的主题：
前端代码结构健康检测 —— 一套看得见、测得出、拦得住的系统方案。
本文将系统介绍结构健康检测的关键维度、主流工具、组合方式与落地建议。
🧠 一、结构健康检测：到底在检测什么？
我们将“结构健康”拆分为五个典型维度：
| 健康维度 | 检查目标 | 问题表现 |
|---|---|---|
| 🧱 模块依赖结构 | 循环依赖、模块耦合、引入链过深 | 改一个 utils，崩三个页面 |
| 🧼 无效代码 | 未使用导出、未引用文件、包冗余 | 项目越来越胖，没人敢动 |
| 🔍 依赖规范性 | 模块 import 边界、层级调用规范 | 页面直接 import service，耦合混乱 |
| 📊 结构演化趋势 | 哪些模块变胖、被过度依赖、引用路径扩散 | 无意中造出“全局工具怪物” |
| 💡 性能引入代价 | import 模块引入了多大体积 | 首页加载慢，Bundle 分析一团糟 |
🧰 二、主流工具盘点：谁负责哪块？
| 工具 | 检查范围 | 是否推荐 | 关键能力 |
|---|---|---|---|
| SonarQube | 函数级别复杂度、重复、代码异味 | ✅ 必须 | 分析函数结构、判断维护成本、支持CI可视化 |
| madge | 模块依赖图、循环引用 | ✅ 必须 | 检测循环依赖、输出依赖图、生成JSON结构 |
| ts-prune / ts-unused-exports | 未使用的 export 项 | ✅ 必须选一个 | 查找死导出（非死代码） |
| depcheck | package.json 中未使用依赖包 | ✅ 建议定期使用 | 剔除冗余 npm 包 |
| dependency-cruiser | 模块 import 规则、层级限制 | ⚠️ 中大型项目推荐 | 自定义结构约束，阻止违规 import |
| eslint-plugin-boundaries | 模块层级边界规则 | ⚠️ 搭配 ESLint 使用 | 限制模块不跨层乱引入 |
| import-cost | 模块引入增加 bundle 体积 | ❌ 插件即可，不适合 CI | 性能意识培养，非结构检测工具 |
🧩 三、工具边界对比图
| 检测类型 | 能力 | 工具 |
|---|---|---|
| ❌ 循环依赖检测 | ✅ | madge |
| ❌ 模块“胖度”监控 | ✅ | madge + 自定义统计脚本 |
| ❌ 未使用的导出项 | ✅ | ts-prune / ts-unused-exports |
| ❌ 未使用的 npm 包 | ✅ | depcheck |
| ❌ 函数复杂度、重复 | ✅ | SonarQube |
| ❌ 模块 import 边界 | ✅ | dependency-cruiser / eslint-plugin-boundaries |
| ❌ import 增加体积提醒 | ⚠️ 仅本地可用 | import-cost 插件 |
🛠️ 四、推荐组合方案：按项目规模划分
✅ 中小型项目（1~3人维护）
SonarQube：日常质量守门madge：依赖结构监测（加上 alias 配置）ts-prune：清理 export 冗余depcheck：每月一次，清理依赖包
✅ 中大型项目（多人协作，层级架构清晰）
在上述基础上，加入：
dependency-cruiser：定义模块边界规则（如 UI 层不可 import domain 层）eslint-plugin-boundaries：开发阶段实时拦截结构违规- 自定义 madge 结构对比脚本：CI 中监控模块“被依赖数突变”→ 预警耦合风险
🤖 五、CI 集成示例
以 GitHub Actions 为例：
jobs:
structure-health-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: npm install
# 1. 检查循环依赖
- run: npx madge --circular src
# 2. 检查未使用导出
- run: npx ts-prune
# 3. 检查冗余依赖
- run: npx depcheck
# 4. 运行 SonarQube
- run: sonar-scanner
📈 六、进阶玩法（可选但有价值）
| 做法 | 意义 |
|---|---|
| 📊 记录每次 madge 输出，生成“结构演化报告” | 查看哪些模块变胖、耦合上升 |
🧠 使用 madge + Git diff 输出结构变更图 | 给 Reviewer 可视化参考 |
| 🔄 将结构健康情况反馈到 PR 评论中 | 拉齐团队对结构变化的感知 |
| 🚨 设置结构指标阈值报警（如被依赖次数 > 10） | 及时拦截“中心化怪物模块” |
✅ 七、总结：结构健康，是软件工程的体检机制
代码质量不只是 bug 少、功能稳，更要“结构清晰、演化有序”。
建立结构健康检测机制，是从“写得快”迈向“改得动、管得住”的关键一步。
SonarQube 管你代码写得怎么样，madge 管你模块拉得清不清，ts-prune 帮你清理门面，depcheck 替你卸包瘦身。
让结构成为你项目的“隐性竞争力”，打造一个真正“自驱动的前端结构卫士”。
