1. 为什么我会跟rea较上劲组件依赖失真的日常先交代一下背景。我之前在一个维护了三年的中后台项目里天天跟几百个 React 组件打交道。那段时间最折磨人的不是写新功能而是改老组件——你永远不知道一个看起来人畜无害的 props 改动会在哪个犄角旮旯的页面里炸出类型错误。有一次我要给一个按钮组件加个新参数全局搜了一遍引用肉眼数出十一个地方在用改完之后测试环境直接红了四个页面原因是有两个组件通过一个我没注意到的中间层间接引用了它。这种经历多了之后我开始琢磨一件事团队嘴上说的组件化开发实际上对组件之间关系的理解是高度私有的。每个人脑子里都有一张模糊的依赖图但没人能画出来新来的同事更是只能靠猜。文档写过几版很快就过期了IDE 自带的结构视图只能看单文件跨文件关系全靠人肉。我那时候特别想要一个东西能自动把整个项目的组件依赖关系摸清楚然后把结果变成一张看得懂的报表。这就是 rea 的起点。rea 不是那种帮你写代码的框架也不是约束代码风格的 lint 工具它是一个面向 React 项目的依赖关系分析器。它能扫描一个目录把组件之间复杂的引用关系拉成一张结构化的网告诉你谁依赖谁、谁在反复被引用、哪里有循环依赖、哪个组件已经没人用了但还在仓库里躺着。对维护老项目的人来说它就是一次组件关系普查对刚接手代码库的人来说它就是一张不用维护、永远最新的架构地图。我自己定义 rea 的定位是它不是代码规范工具而是关系普查工具。规范工具告诉你该怎么写rea 告诉你现在到底是什么样。先搞清楚现状再谈改进这个顺序不能反。1.1 一次改一处崩三处的实际案例具体说说那次让我下决心的经历。项目里有一个UserAvatar组件最初只是在用户列表里显示头像和名字后来被人扩展了几次增加了在线状态、部门标签、跳转链接等能力。我接手时显示用户信息这个需求已经有三个组件在各自实现全都直接或间接引用了UserAvatar。我改了UserAvatar的 props 结构把原来分散的几个参数合并成一个user对象。结果列表页直接引用它报错预期内详情页的MemberCard引用了UserAvatar它自己又把 props 透传出去报错也能理解最诡异的是ChatPanel它压根没写过UserAvatar但它的子组件MessageItem里用了MemberCard于是错误一路传上来整个聊天面板崩溃。这个问题的本质不是UserAvatar改得不好而是团队对谁在依赖谁这件事完全没有共识。我当时花了半小时翻引用、回看提交记录、问之前的维护人才拼出这张图。如果有工具能在改动前五分钟生成一份依赖清单后面这些返工根本不会发生。1.2 大多数人是怎么理清依赖关系的我观察了一下不同团队的做法大致分三种第一种是硬记派。项目规模小的时候还好超过五十个组件之后就全靠个人记忆离职一个人就带走一部分地图。第二种是文档派。ARTS 架构图、Notion 页面画得漂漂亮亮但代码一变文档就没人更新三个月之后文档描述的系统跟真实代码已经不是一个东西了。第三种是工具派。用 IDE 的 Find Usages、用 grep 搜 import 语句比前两种靠谱但只适合查单个组件做不了全量分析更发现不了间接引用和循环依赖。这三种做法共同的问题在于它们都在处理人应该怎么理解代码而 rea 处理的是代码之间的关系应该怎么被计算。后者是确定性的是可以自动化的而且是项目发展的过程中唯一不会撒谎的信息源——源码本身。1.3 rea 的定位先普查再规划我给自己定的原则很简单先把现状完整地、准确地呈现出来让团队在同一个事实基础上讨论问题。至于怎么重构、怎么分层那是后面的事情。这就像接手一个老仓库之前你先别急着清理货架先做一次盘点哪些货有人买哪些货积压了几个月哪些货放在两个不同的货架上。rea 做的就是这件事它把组件依赖这种抽象的、藏在代码里的关系变成一份可以打印出来、可以在会议上指着讨论的清单。2. rea 三个字母背后的架构取向项目起名叫 rea不是随手敲的。三个字母分别对应我设计的三个阶段Relate、Export、Analyze。这也决定了工具的整体架构不是一个单点脚本而是三条清晰的处理流水线。2.1 Relate以依赖图为中心的关系建模Relate 阶段负责回答一个问题这个项目的组件之间到底有哪些关系在这个阶段rea 不关心组件内部的实现细节不关心样式怎么写只关注一个东西引用关系。谁 import 了谁谁在 JSX 里渲染了谁谁通过 React.lazy 动态加载了谁这些信息被统一收集起来形成一个以组件为节点、以引用为边的有向图。我选择有向图作为核心数据结构是有原因的。第一有向图天然能表达A 依赖 B但 B 不依赖 A这种非对称关系这个在 UI 组件场景里非常常见——底层组件永远不知道谁在用自己。第二图结构方便做后续分析比如找环、算入度出度、做连通性判断这些都是图论里的经典问题不需要发明新算法。这个阶段最忌讳的是把出现过的字符串当成真正的依赖。比如有的组件在注释里写了Button有的组件在字符串拼接里用了组件名这些都不能算数。rea 只认两类东西真实的 import 语句以及 JSX 里实际渲染的组件标签。宁可漏掉一些模糊的情况也不能把假依赖混进图里否则后面所有分析都是脏数据。2.2 Export从源码到结构化报表的流水线Relate 阶段产出的是一张内存里的图但人没法直接看内存图所以还需要一个 Export 阶段。这个阶段做的事是把依赖图转换成一系列结构化输出。目前 rea 支持三种格式JSON给程序读方便二次加工Markdown 表格给人读方便贴进文档或者发到群里以及一个简单的 HTML 报告用颜色和连线把依赖关系可视化出来适合在评审会上投屏讲解。Export 阶段有个容易被忽视的设计点输出格式不能影响分析结果。也就是说不管你是要 JSON 还是 HTML底层那张依赖图必须是同一张。我在设计 rea 的时候把 Relate 和 Export 严格分成了两层中间通过一个统一的内部模型传递数据不能让某个输出格式反过来影响分析逻辑。2.3 Analyze把看得见的关系变成说得清的决策前两个阶段解决的是看到了什么Analyze 阶段解决的是这意味着什么。同样是一张依赖图不同角色关心的点完全不同后端开发拿到这张图关心的是循环依赖会不会导致初始化死循环前端 Leader 关心的是某个底层组件被三百个地方引用改动它是不是高风险新人关心的是这个组件能不能删删了会不会有什么隐形依赖绷断性能优化的人关心的是有没有组件在一个页面里被重复渲染多次是不是因为多个入口都引到了同一个子组件。Analyze 阶段把这些关心点转化成具体的判定规则输出带有倾向性的结论。比如循环依赖警告高危公共组件提示孤儿组件提示。这些结论不一定都是错的但至少能让讨论有一个共同的出发点。3. 从 JSX 到依赖图谱rea 的解析链路拆解知道整体架构之后我想把解析链路拆开讲一遍。理解这条链路你才能自己改 rea 去适配特殊项目或者在其他语言、其他框架里复现同样的思路。3.1 第一层文件遍历与入口发现rea 的起点不是某个具体文件而是整个目录。你可以给它一个入口文件比如src/App.tsx它会顺着这个入口往外扩散也可以不指定入口直接扫描整个src目录把所有.tsx、.ts、.jsx、.js文件都纳入分析范围。这一层有个重要参数叫--depth控制递归深度。默认不限制但如果是第一次对一个老项目跑分析我建议先限制在四层以内把主干关系看清楚再逐步加深。否则几百个组件的图展开之后信息量太大反而抓不住重点。文件遍历阶段会顺带做两个过滤node_modules目录直接跳过测试文件和.stories.tsx文件默认跳过但可以通过参数手动开启。测试文件里经常有 mock 数据导致的关系冲突故事文件依赖的引用方式也跟业务组件不一样混在一起会污染分析结果。3.2 第二层AST 解析与导入声明收集拿到文件列表之后rea 会对每个文件做词法分析和语法分析。这里用的是成熟的 JS 解析器先把源码解析成 AST抽象语法树然后从中提取结构化的语法事实。在这一步rea 核心收集的信息是两类第一类是import声明。不管是import A from ./A、import { B } from ./B还是import type { C } from ./C都会被抓出来。这里要特别注意区分type导入——它只影响类型检查不影响运行逻辑如果混进依赖图会制造大量虚假的运行时依赖所以 rea 把 type-only 导入单独标记默认不计入运行时依赖图。第二类是 JSX 标签。一个组件文件可能没有显式 import 某个组件但通过全局注册或者window挂载的方式在 JSX 里使用了它。rea 会把 JSX 里出现的组件标签名跟当前文件的 import 列表做交叉比对识别出用了但没本地导入的组件这种往往是隐式依赖风险点。AST 这层看起来复杂其实逻辑可以用一句话概括把代码从给人看的文本变成给机器看的树然后在树上做遍历和标记。下面这是 rea 内部处理 import 语句的核心逻辑示意用 TypeScript 写的import { parse } from babel/parser; import traverse from babel/traverse; export function extractImports(filePath: string, source: string) { const ast parse(source, { sourceType: module, plugins: [jsx, typescript, decorators-legacy], }); const imports: Array{ source: string; importedName: string; isTypeOnly: boolean; } []; traverse(ast, { ImportDeclaration(path) { const node path.node; node.specifiers.forEach((spec) { imports.push({ source: node.source.value, importedName: spec.type ImportDefaultSpecifier ? default : spec.local.name, isTypeOnly: node.importKind type, }); }); }, }); return imports; }实际的 rea 代码比这个复杂一些因为还要处理 re-export、namespace import、动态 import 等情况但核心思路就是上面的代码解析、遍历、收集。3.3 第三层组件识别与依赖权重计算拿到所有的 import 关系之后会得到一个非常稠密的图。一个工具函数可能被五十个组件引用了一个 UI 组件可能引用了十几个其他组件。如果直接把这个图铺开信息噪音很大。所以 rea 在第三层做了一件事给每条边赋予权重给每个节点赋予角色。节点角色的判定规则是这样的文件名首字母大写且文件里有 JSX 返回值判定为组件文件名小写且文件不在 UI 目录下判定为工具模块文件里没有任何导出只包含副作用逻辑判定为副作用模块一个文件同时导出组件和其他函数判定为混合模块。边权重的计算规则是直接引用记 1 分通过 re-export 间接引用记 0.5 分通过动态 importReact.lazy或import()调用引用记 0.3 分。简单说越是直接的、静态的、运行时就确定的依赖权重越高越是一层套一层的间接引用权重越低。下面这张表是 rea 对节点角色和边权重的默认设定节点角色判定依据风险倾向组件首字母大写、含 JSX作为依赖源影响下游使用者工具模块小写命名、纯逻辑作为被依赖方支撑多个组件副作用模块无导出、有副作用逻辑导入即执行隐藏风险高混合模块组件与函数同时导出依赖关系模糊建议拆分类型模块仅导出类型不计入运行时依赖3.4 第四层环形依赖与悬空引用的判定最后这一步是 rea 最有实用价值的部分在图里找环、找悬空引用。环形依赖指的是 A 依赖 B、B 又依赖 A 的情况。在 React 项目里环形依赖不一定立刻让程序崩溃但会让模块加载顺序变得不确定容易出现某个组件渲染时拿到 undefined的诡异 bug而且这种 bug 非常难复现。rea 用深度优先搜索遍历有向图一旦发现某个节点出现在当前遍历路径上就认定存在环并输出完整的环路链路。悬空引用则有两种情况。一种是源码里 import 了一个不存在的路径这通常是重构时漏改了另一种是 import 的模块存在但里面没有导出你要的那个名字这通常是导出的名字被改掉了。这两种情况 rea 都会汇总成一个断链清单方便你一次性修复。需要说明的是rea 的循环依赖检测只是针对静态分析的运行时动态创建依赖导致的环它检测不到。但实际情况里静态层面的循环依赖已经覆盖了绝大多数问题场景动态依赖那部分占比很低。4. 在真实项目里跑一遍安装、扫描、报表解读说了这么多原理下面实际操作一遍。我用一个模拟的中后台项目做演示项目结构大概是这样的src/ components/ common/ # 通用基础组件比如 Button、Input、Modal business/ # 业务组件比如 UserCard、OrderTable pages/ Dashboard.tsx UserList.tsx OrderDetail.tsx utils/ format.ts request.ts App.tsx4.1 安装与前置条件rea 是一个命令行工具全局安装就能用。项目本身不要求 React 版本只要源码是标准的 JS/TS 语法就行。如果项目用了比较新的 ECMAScript 语法或者实验性的装饰器语法rea 会尽量用 AST 解析器的插件去兼容。npm i -g rea-cli安装完成后先跑一下版本验证rea --version如果你更希望把它作为项目内的开发依赖可以局部安装然后用npx rea调用这样团队里每个人能用的版本都能锁定避免在我电脑上能跑的问题。4.2 第一次扫描会得到什么进入项目根目录跑第一条命令rea scan --entry src/App.tsx --out ./rea-report--entry指定入口文件--out指定输出目录。跑完之后会生成几个文件rea-report/ report.json # 全量结构化数据 overview.md # 概览报表 dependency-graph.html # 可视化关系图 issues.md # 问题清单第一次扫描的结果通常会让你吃一惊。以我自己的项目为例第一次跑出来这些数据全项目一共有 87 个组件、34 个工具模块其中 29 个组件从来没有任何地方引用它们也就是孤儿组件检测到 3 组循环依赖其中一组跨了 6 个文件有一个底层组件被 74 个其他组件直接或间接引用。看到29 个组件没人用的时候我是很震惊的。它们大多是为了某个半途而废的功能写的或者被替换之后忘了删。如果不做普查这些代码会一直躺在仓库里成为新人阅读代码时的干扰噪音。4.3 看懂三张核心报表overview.md是一张组件依赖总表按引用数量排序所以进入这个表格第一眼就能看到高危组件。表结构大致是这样组件名被引用次数被间接引用循环依赖风险等级Button74132无高危Modal4588无中危UserCard2341有高危DeprecatedBadge30无低危被引用次数高意味着改动成本高风险等级是 rea 综合了引用基数、间接引用量、环检测结果算出来的。这个表不能直接决定你这个组件能不能改但能告诉你改之前要花多少精力做回归测试。issues.md则是问题清单会列出所有检测到的问题包括环路由、悬空引用、孤儿组件、副作用模块的位置。这个清单最有价值的地方在于它给了你一个可以逐条消化的待办列表而不是一个模糊的感觉项目有些问题。HTML 可视化图适合拉到会议室里投屏。每个组件节点用圆形表示颜色深浅代表引用热度箭头代表依赖方向。人手一点开看哪里是重灾区一目了然。4.4 把 rea 接进 CI 的配置示例手动跑一次只是清理问题真正要让依赖关系长期可控得把它接进持续集成流程。我推荐的做法是在代码合并前加一步检查依赖情况跟基线报告不一致就报警让开发者自己在提测前就知道影响范围。package.json里增加一条脚本{ scripts: { rea:check: rea scan --entry src/App.tsx --compare ./rea-report/baseline.json --check-cycle --check-orphan } }--compare参数会拿当前扫描结果跟上次的基线做差异对比如果有新增的循环依赖或者新出现的高危组件命令会以非零码退出CI 就会拦截这次合并。这里提个建议CI 里跑分析时尽量选一个稳定的入口文件不要用src全量扫描作为判断标准。因为全量扫描对每次的改动差异太敏感很容易因为一些无关紧要的改名导致整个流水线变红时间久了大家就不看这个检查了。入口聚焦到某几条核心链路反而能形成有意义的约束。5. 实战中绕不开的三个坑工具做出来是一回事拿到真实项目里跑是另一回事。rea 在反复打磨的过程中遇到了三个让我印象很深的坑这里单独拿出来讲。5.1 动态 import 与 React.lazy 造成的盲区第一版 rea 只处理静态的import语句很快就在一个项目上栽了跟头。那个项目大量使用路由懒加载所有页面组件都写在React.lazy(() import(./pages/xxx))里。rea 跑完之后页面组件全部出现在孤儿组件清单里因为静态 import 抓不到这种动态引用的关系。这个坑的本质是静态分析和动态加载天然存在盲区。但这里的盲区不是一个无解的难题因为动态 import 的路径参数通常是一个字符串字面量还是可以从 AST 里提取的。我后来在 rea 里加了对import()调用表达式的解析能识别出React.lazy和loadable()这几种常见的动态加载封装的参数把动态引用也纳入依赖图。但有一种情况只能靠约定来补路径变量拼接比如import(./locales/${lang})这种动态性太强任何静态分析工具都无能为力。遇到这种代码只能用配置的方式在 rea 里手动声明这层关系或者干脆接受它不在依赖图里。5.2 路径别名与 barrel file 带来的假依赖第二个坑是路径别名。现在主流 React 项目都会配路径别名/components/Button这种写法到处都是。第一版 rea 直接拿绝对路径去做匹配结果/components/Button和../components/Button指向同一文件在依赖图里却被当成了两个不同的节点导致整个图出现了大量重复节点引用次数统计严重失真。解决思路是对路径做归一化先读取项目的tsconfig.json或者jsconfig.json提取paths字段的别名映射再把所有 import 的路径根据映射关系解析成真实文件路径最后基于真实文件路径做去重。这里有一个优先级问题也一并说一下如果项目里同时有tsconfig.json和webpack.config.js我建议优先信tsconfig.json的映射因为它是 TypeScript 类型检查实际在用的那份配置跟代码能成功编译的路径保持一致。第三个坑是 barrel file也就是index.ts这种集中转发的文件。一个目录里的组件都通过index.tsre-export 出去其他组件再从index.ts导入。这在依赖图里会形成一层很厚的中间节点分析结果里出现大量组件 A → index.ts → 组件 B的间接路径。rea 的默认策略是把 barrel file 当作透明的转发层穿透它直接连接真实的来源组件让依赖图更干净。但如果你们团队有意把index.ts当作对外 API 边界不想穿透也可以关掉这个行为。我把这三个配置项整理成一个速查表问题参数作用需要扫描动态导入--include-dynamic解析import()调用需要自动读取别名--resolve-alias-from tsconfig按 tsconfig 归一化路径需要穿透 index.ts--resolve-barrel穿过 barrel file 直达真实组件不想穿透 barrel--keep-barrel保留中间转发层节点5.3 大项目扫描性能与缓存策略最后一个坑是性能。第一次在一个有几百个组件的项目上跑时rea 全量扫描花了将近四十秒。单次跑还能接受但接进 CI 之后每次提交都等四十秒开发体验很差而且很容易导致流水线超时。性能瓶颈主要在两处。一是重复解析同一个工具模块被多个组件引用每次都在 import 解析时被重新读文件、重新做 AST这对纯函数模块来说是纯浪费。二是级联分析rea 需要沿着依赖关系逐层往外找模块数量一大递归展开的路径指数级增长。优化方案做了两个。第一个是文件级缓存基于文件内容哈希做缓存只有内容变了才重新解析。第二次扫描如果项目没有改动耗时直接从四十秒降到三秒以内。第二个是定时清理缓存每次扫描时如果发现缓存目录里的条目超过一定数量或者缓存文件太老会自动重建。这个方案让 rea 既快又不会积累垃圾数据。6. 目前正在尝试的几个迭代方向rea 现在已经在团队内部稳定用了几个月效果是实打实的。但工具这个东西用起来之后总能看到新的可能性这里列几个我正在尝试的方向。6.1 让版本控制信息参与依赖决策当前 rea 只分析源码现状不关心历史。一个组件被引用了一百次和另一个组件也被引用了一百次对 rea 来说风险等级一样。但实际上这两个组件的维护成本完全可能差很多前者三个月没动过很稳定后者这周已经被改了五回每次改都牵扯一堆人。我开始尝试把版本控制系统信息接进来比如给每个依赖关系打上最近更新时间和变更频率两个标签。标签不改变依赖图结构只是给风险等级计算增加一个维度一个高频变更的组件如果又是高被引用的组件那它就是这个项目里最值得优先重构的对象。6.2 从分析工具变成约束工具分析工具只负责汇报约束工具还能在代码提交前拦住问题。我的目标是让 rea check 能按团队自定义的规则执行循环依赖新增拦截高危组件被新增引用超过 N 次拦截并提示拆分新增孤儿组件提示确认而非直接拦截组件目录深度超过约定层数提示检查是否过度嵌套。规则全部写在项目根目录的.rea.config.json里不同项目可以配不同的阈值。这种红线式的约束比让人自学规范靠谱得多。6.3 给组件的健康打一个综合分最后一个方向比较实验性把依赖图指标和可维护性指标合在一起算一个组件健康分。参考维度包括被引用次数、是否存在循环依赖、组件文件行数、导出结构是否单一、是否在测试文件和业务文件里被同时引用。健康分不追求工程学正确只是想让团队在谈代码好坏时能有一个直观的数字抓手。把这个数字展示在组件的开发文档页面里每周自动刷新一次让技术债变得可见。技术债不可怕可怕的是看不见。最后再分享两个小技巧从项目立项到稳定使用其实整个周期不到一个月但收益远超预期。最大的收获不是那些报表本身而是团队开始用同一套语言讨论组件边界了——这个组件是重度的动它要小心终于有了数据支撑而不是凭感觉。最后送两个小技巧。第一个排查老项目问题时先跑rea scan --entry src/App.tsx它会产出一份当下最新的依赖清单比你在代码里一个文件一个文件地点要全面得多。第二个如果你的项目里 tsconfig 和 webpack 的别名配置不一致rea 默认会读取 tsconfig经常对不上的建议把 webpack 的 resolve.alias 统一到 tsconfig 同源一劳永逸。依赖关系从来不会因为你不看它就不存在。早一点把它拉出来摆到桌面上改代码的时候会踏实很多。