安全清理死代码：工具分析 + 删除日志

“清理死代码”是典型的高收益/高风险工作：删对了，代码库更轻、更易维护；删错了，线上崩溃还很难排查。一个更稳的落地方式是：先用工具证据锁定“未使用”，再分批删除并跑测试验证，同时记录删除日志。

1) 先做证据：并行跑死代码检测工具

常见的证据来源包括：

• knip：unused files/exports/deps/types
• depcheck：unused dependencies
• ts-prune：unused TypeScript exports
• eslint：unused variables / unused disable directives

落地方式可以做成一个命令（类似 /refactor-clean）：先跑工具 → 生成报告 → 再进入删除阶段。

2) 风险分级：SAFE / CAUTION / DANGER

社区流程强调先分级再删：

• SAFE：明确无引用的内部导出、未使用依赖、测试辅助工具（需确认不影响 CI）
• CAUTION：组件/路由/公共工具（可能存在动态引用）
• DANGER：配置、入口文件、对外 API、框架约定目录

建议只从 SAFE 开始，一次处理一个类别，并在每批后跑验证。

3) 删除节奏：一批一验证 + 可回滚

推荐的“安全节奏”：

1. 删除前：跑一次完整测试/构建，确保基线是绿的
2. 删除一批（小批量）
3. 立即复跑测试/构建
4. 如果失败：优先回滚到上一批，再细化定位

原则：不要把“清理死代码”和“重构业务逻辑”混在同一个批次里。

4) 记录删除日志：让清理可追溯

refactor-cleaner 建议维护一个删除日志（示例用 docs/DELETION_LOG.md），记录：

• 删除了哪些文件/导出/依赖
• 为什么可以删（证据来源：工具报告/搜索结果）
• 被谁替代（如果是重复实现合并）
• 影响评估与验证方式（build/test 是否通过）

这能显著降低“半年后追不回去”的成本。

5) 常见误删风险（务必检查）

• 动态导入/字符串路径引用（grep 搜不到）
• 框架约定入口（Next.js/路由、插件注册、配置加载）
• CLI/脚本入口（CI 在用，但业务代码不引用）
• 文档/代码生成链路（看似不引用，但发布前生成时会用）

遇到这类不确定项，建议先标记“候选”而不是直接删。

参考

无