高效清理TypeScript项目

高效清理TypeScript项目：npx ts-unused-exports tsconfig.json完全指南

在大型TypeScript项目中，未使用的导出符号（如函数、变量、类）会逐渐积累，导致代码冗余、编译负担增加和维护成本上升。通过 npx ts-unused-exports tsconfig.json命令，开发者可以快速定位并清理这些“僵尸代码”，显著提升项目健康度。

一、命令的核心价值

1. 精准检测未使用导出
   ts-unused-exports通过分析 tsconfig.json指定的文件范围，扫描项目中所有导出符号（export）的引用关系，标记未被其他文件导入（import）的项。其原理基于TypeScript编译器API，确保分析结果与编译逻辑一致。
2. 核心优势
   • 减少编译体积：移除未使用代码可降低输出文件大小，优化运行时性能。
   • 提升可维护性：避免开发者误用废弃接口或混淆代码逻辑。
   • 无缝集成：无需全局安装，通过 npx直接调用最新版本工具。

二、完整使用流程

1. 安装与基础命令

# 局部安装（推荐）
npm install --save-dev ts-unused-exports
# 运行扫描
npx ts-unused-exports tsconfig.json

注意：需确保 tsconfig.json已正确配置 include/exclude字段，例如：

{
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

2. 关键参数解析

3. 典型输出示例

src/utils/date.ts:5 - formatDate (未使用)
src/components/Button.tsx:12 - OldButton (未使用)

每行输出包含文件路径、符号名称和行号，直接指导清理操作。

三、进阶实践技巧

1. 解决误报问题

   • 若工具错误标记内部使用的导出（如工具类函数），使用 --ignoreLocallyUsed跳过。
   • 通过 // ts-unused-exports:disable-next-line注释临时屏蔽误报。

2. 与CI/CD流程集成
   在代码合并前自动扫描，阻止未使用代码进入主分支：

   // package.json
   "scripts": {
     "precommit": "ts-unused-exports tsconfig.json --error"
   }
   

   --error参数使发现未使用导出时返回非零状态码，中断流程。

3. 结合ESLint深度清理
   对于文件内部未使用但已导出的变量（如重构残留），可扩展ESLint规则：

   • 改写 no-unused-vars规则，使其支持导出变量分析。
   • 调用ESLint API自动删除无用变量，并通过Prettier格式化代码。

四、实际案例与效果

• 字节跳动Web Infra团队：通过类似工具链（基于 ts-unused-exports和ESLint扩展）删除6万行废弃代码，显著降低维护成本。
• 持续优化收益：某中型项目（约10万行TS代码）定期运行该命令，每次清理约200-500行冗余代码，编译时间减少约7%。

五、替代方案对比

六、常见问题解决

• 安装失败：检查Node.js≥12.x，切换npm镜像源：

  npm config set registry https://registry.npmmirror.com
  

• 扫描遗漏：确认 tsconfig.json中 include覆盖所有目标文件，排除测试文件避免干扰。
• 类型导出误判：对纯类型声明（如 export interface），需启用TS 4.5+的 --preserveValueImports。

结语

npx ts-unused-exports tsconfig.json是优化TypeScript项目的利器，尤其适合长期迭代的中大型代码库。定期运行此命令，结合ESLint和CI流程，可构建高可维护性的代码底座。