AI 清理导出时，小心别名与动态引用

AI 编程代理删除了一个被工具标成「未使用」的导出，类型检查和单元测试全部通过，真实功能却在加载时出错。原文讨论的是一种清理风险：路径别名、聚合导出和动态加载，都可能让静态分析漏掉调用者。

作者的结论是：删除导出之前，先证明它没有消费者。对经常让 Agent 清理 TypeScript 项目的人，这篇文章最有用的地方，是把「工具没找到引用」和「引用确实不存在」分开了。

「未使用」可能只是工具没解析出来

原文用 formatReceipt 举例：这个辅助函数既被业务代码通过 @billing/receipt 导入，也通过一个注册表按需加载。注册表负责把字符串映射到模块加载逻辑，可以理解为「拿到功能名称，再决定加载哪个模块」。

当 Agent 使用 knip 或 ts-prune 清理代码时，某些配置可能没有完整读取 TypeScript 的 paths 映射，也可能无法分析动态 import() 的参数。工具于是把 formatReceipt 列为没有已解析调用者的导出，Agent 随即删除它，并把报告条目减少视为优化成功。

这里需要分清两种情况：工具已经覆盖所有入口，确认没有引用；工具只能覆盖部分入口，在它看得到的范围内没有引用。后者不能直接支持删除。

静态分析报告里的「没有找到」，不等于整个系统里的「没有使用」。

路径别名只是其中一个入口。barrel file，也就是集中转导出其他模块的聚合文件，会让调用关系多绕一层；运行时字符串驱动的加载，则可能让具体模块路径直到执行时才确定。

原文没有提供可运行的示例、工具版本或实际配置，因此这是一种故障机制说明，不能据此认定 knip 或 ts-prune 默认都会误判。

为什么 Agent 容易删错，检查通过又证明了什么

作者认为，Agent 容易把工具报告当成明确任务：列表里有多少未使用符号，就删除多少符号。工具的能力限制通常写在文档里，输出却未必区分「确认不可达」和「解析不了引用」。

当目标只是让报告清零时，删除代码就成了最直接的行动。问题出在证据不足，Agent 却给出了确定结论。

类型检查和单元测试也有覆盖边界。一个依赖运行时字符串的 import()，可能只有用户进入特定页面、触发特定功能后才执行。对应导出消失，或者加载指向缺失的 chunk，都未必被已有测试触发。

不过，原文把路径别名导入和动态加载失败放在同一个叙述里，需要补上条件：如果业务文件明确导入 formatReceipt，而它又被同一次 TypeScript 检查覆盖，删除导出通常应该报错。出现「全绿但功能坏了」，还需要检查范围、类型声明或加载方式等具体前提。原文没有交代这些细节。

检查通过有价值，但只能证明检查覆盖到的范围。

删除之前，要补齐哪几类证据

作者给出的第一步，是让清理工具读取编译器实际使用的同一份 tsconfig，并挑一个已知通过别名导入的符号，验证工具确实能够找到调用者。配置文件里出现了 paths，还不足以证明工具已经正确解析。

接着做全仓库文本搜索。搜索对象不只有导出名，还包括别名前缀、文件基本名，以及可能通向模块的路径片段。文本搜索不能替代语义分析，却能补充另一种观察角度。

遇到由变量、注册表或配置对象拼接参数的 import()，作者建议停止自动删除。这里的意思是转入人工核查：确认字符串如何生成、可能加载哪些模块，以及是否存在间接消费者。

公开发布的包还要单独处理。仓库内部没人导入，不代表外部用户没有使用。包入口应当作为公开契约保护，也可以围绕 package.json 的 exports 明确需要保留的接口范围。

最后，删除后需要完成构建和相关集成运行，尤其要实际走到懒加载入口。作者要求的闭环包括：解析器理解别名、全仓库搜索及公开接口核查没有发现消费者、删除后的构建与集成运行通过。任何一环不确定，就保留符号，或先弃用一个发布周期；文末也提到用一到两个版本收集使用证据，再决定删除。

我的判断

我赞同把导出删除视为潜在破坏性变更，尤其是公共包和包含插件注册机制的项目。导出承担的是调用契约，判断范围不能只停留在当前文件或当前仓库。

但原文没有给出事故复现、误报比例，也没有提供不同工具配置的对照数据。「花几分钟检查就能避免问题」属于经验建议，不能保证覆盖复杂的动态加载系统。即使文本搜索没有命中，也可能只是消费者用了另一种名称或位于仓库之外。

与完全依赖人工搜索相比，配置正确的静态分析仍然更适合批量定位候选项。合理的分工是让工具筛选，再为删除补证据。对于公开包，用明确的 API 清单保护入口，也比每次临时判断更稳定。

弃用则适合仍有疑问的接口。但「没有观测到调用」也有前提：团队确实具备相应的使用数据。原文没有说明如何获取遥测，不能默认所有团队都能靠等待一个版本解决不确定性。

能拿来做什么

• 给清理 TypeScript 项目的 Agent 增加明确约束：删除前必须检查 tsconfig 路径别名、聚合导出和动态加载，并列出核查过的引用与尚未解决的不确定项。
• 清理前端懒加载模块时，选取受影响的路由或功能入口做集成验证，实际触发加载过程，避免只依赖类型检查和普通单元测试。
• 维护公开的 Node 或前端工具包时，将包入口和 package.json 的 exports 纳入接口核查范围，对外部使用情况不明确的导出先保留或弃用。