JS 转 TS 自动化方案：使用 tsc --allowJs 批量重命名与初步迁移

一、为何一次性重命名必然失效：渐进迁移的核心逻辑

当工程团队决定引入 TypeScript 时，直觉做法往往是编写一段脚本将目录下的所有 JavaScript 文件强行改为 TypeScript 后缀。然而，TypeScript 编译器默认对代码语法和类型施加严格审查。在未提供声明文件、缺乏接口定义以及存在动态原型扩展的代码库中，这一操作会瞬间触发雪崩式的诊断失败。

业务系统需要持续交付，无法接受数周的“停工重构”。渐进式迁移的核心原则是：让新旧代码长期共存，任何一次提交后生产环境构建都必须保持绿灯。TypeScript 官方提供的 --allowJs 参数正是实现这一目标的基石。它允许编译器同时处理 .js/.jsx 与 .ts/.tsx，并将它们输出到同一交付管线中。

二、第一步：奠定迁移基线配置

在触碰任何代码文件前，首要任务是在项目根目录创建并精确调优 tsconfig.json。这个初始配置必须保证两点：第一，现有的 JavaScript 项目能够无感知通过 tsc 的语法扫描；第二，构建打包工具（如 Webpack 或 Vite）能够同时解析两种后缀的相对路径引用。

1. 依赖安装与编译器就位

在项目根目录下通过包管理器安装 TypeScript 以及对应的 Node 运行环境类型定义。执行命令如下：

npm install -D typescript @types/node

2. 初始化并配置 tsconfig.json

新建或覆盖根目录下的 tsconfig.json。初期配置的关键在于：放宽类型审查，保持模块解析与现有打包工具一致。

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "jsx": "preserve",
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": false,
    "noImplicitAny": false,
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "build"
  ]
}

3. 基线验证

配置完成后，在命令行执行以下诊断命令：

npx tsc --noEmit

若输出为空或仅返回 0 个错误，说明编译器基线已经成功建立。如果存在语法级别的错误（例如某些老旧项目中混用的 CommonJS 与 ESModule 语法），需要优先在 JS 阶段将其规范化。

三、第二步：迁移整体步骤与阶段流转

建立基线后，整个迁移分为五个环环相扣的阶段，从基线验证、依赖拓扑分析、脚本化批量改名，到解决关键阻断性报错，最后平稳进入渐进式类型收紧。

四、第三步：分层迁移策略与依赖拓扑分析

在批量重命名文件时，执行顺序至关重要。一个中大型工程往往包含复杂的模块导入链。如果从入口文件（如 main.js 或 App.jsx）开始自顶向下迁移，上层模块将频繁调用未具类型的底层函数，导致大量类型推断退化为不安全的隐式 any。

工程上验证有效的做法是自底向上的依赖拓扑迁移法（Bottom-Up Strategy）：

五、第四步：编写自动化批量重命名脚本

直接在操作系统中使用 mv 命令会破坏 Git 的提交变更追踪记录，导致版本库将这一过程识别为“删除旧文件 + 新增无关联的新文件”，从而丢失代码历史作者与变更上下文（git blame 与 git log 断裂）。因此，自动化重命名脚本必须通过 git mv 来执行文件更名。

此外，前端工程中经常混用 React 的 JSX 语法。普通含逻辑代码的文件应转为 .ts，而包含 <Component /> 标签模板的文件必须转为 .tsx，否则 TypeScript 编译器会将其误识别为类型断言语法进而报错。

1. 自动化重命名脚本实现

在项目根目录下创建迁移脚本 scripts/migrate-rename.mjs（可使用 Node.js 16+ 直接运行）：

import fs from 'node:fs';
import path from 'node:path';
import { execSync } from 'node:child_process';

// 目标扫描目录与过滤规则
const TARGET_DIR = path.resolve('src/utils'); // 建议按目录分批次执行
const DRY_RUN = process.argv.includes('--dry-run');

/**
 * 递归获取目录下所有匹配的 JS / JSX 文件
 */
function getFiles(dir) {
  let results = [];
  const list = fs.readdirSync(dir, { withFileTypes: true });
  for (const dirent of list) {
    const fullPath = path.join(dir, dirent.name);
    if (dirent.isDirectory()) {
      if (dirent.name !== 'node_modules' && dirent.name !== '__tests__') {
        results = results.concat(getFiles(fullPath));
      }
    } else if (dirent.isFile() && (dirent.name.endsWith('.js') || dirent.name.endsWith('.jsx'))) {
      results.push(fullPath);
    }
  }
  return results;
}

/**
 * 检查文件内容是否包含 JSX 语法特征
 */
function containsJSX(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8');
  // 简易匹配：包含 JSX 标签、React.createElement 或 import React
  const jsxRegex = /<[A-Za-z0-9_]+(\s+[^>]*)?(\/>|>)/;
  return jsxRegex.test(content);
}

function runMigration() {
  const files = getFiles(TARGET_DIR);
  console.log(`[Info] 检索到待处理文件共 ${files.length} 个。模式: ${DRY_RUN ? '演练(Dry-Run)' : '实际执行'}`);

  let successCount = 0;
  for (const oldPath of files) {
    const isJsx = oldPath.endsWith('.jsx') || containsJSX(oldPath);
    const newExt = isJsx ? '.tsx' : '.ts';
    const newPath = oldPath.replace(/\.jsx?$/, newExt);

    if (DRY_RUN) {
      console.log(`[DryRun] ${path.relative(process.cwd(), oldPath)} -> ${path.relative(process.cwd(), newPath)}`);
    } else {
      try {
        // 使用 git mv 保障版本库追踪连续性
        execSync(`git mv "${oldPath}" "${newPath}"`, { stdio: 'pipe' });
        successCount++;
        console.log(`[OK] 重命名完成: ${path.basename(newPath)}`);
      } catch (err) {
        console.error(`[Error] 重命名失败: ${oldPath}`, err.message);
      }
    }
  }

  console.log(`[Done] 执行完毕，成功更名 ${successCount} 个文件。`);
}

runMigration();

2. 安全执行与分批次提交

按照拓扑规划分步执行，切忌一次性处理全局目录。以工具函数目录 src/utils 为例：

1. 预演检查：运行 node scripts/migrate-rename.mjs --dry-run，确认更名路径与 .ts/.tsx 扩展名判断是否完全准确。
2. 正式更名：运行 node scripts/migrate-rename.mjs 执行 git mv。
3. 校验状态：运行 git status。Git 会显式显示 renamed: src/utils/math.js -> src/utils/math.ts。
4. 建立原子提交：执行 git commit -m "chore: rename utils from js to ts"。将文件重命名操作与后续的代码内容修改拆分在不同的 Commit 中，是保障代码审查与历史追踪清晰度的关键技巧。

六、第五步：初步迁移全流程与阻断性错误排查

当一批文件重命名为 .ts 之后，再次运行 npx tsc --noEmit 时，常常会遇到几类最典型的阻断性报错。需要在保持编译通过的前提下快速对齐，不陷入无休止的业务类型重构细节。

1. 缺乏环境与静态资源类型声明

老项目中通常直接使用 import logo from './logo.png' 或 import styles from './index.module.css'。在原生 JavaScript 中打包器会处理这些语句，但 TypeScript 编译器默认不认识非 JS 模块，会报出：Cannot find module './logo.png' or its corresponding type declarations。

解决方法：在 src/shims.d.ts 中统一补充环境桩声明：

// src/shims.d.ts
declare module '*.svg';
declare module '*.png';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.gif';
declare module '*.css';
declare module '*.scss';
declare module '*.less';

// 声明全局挂载的挂载变量
interface Window {
  __INITIAL_DATA__?: any;
  _czc?: any;
}

2. 第三方无类型库报错

对于部分没有随包发布类型声明的老旧 npm 包，TypeScript 会报 Could not find a declaration file for module 'xxx'。

解决方法：

• 优先尝试安装社区声明库：npm install -D @types/包名。
• 若该包无社区声明，直接在 src/shims.d.ts 中追加简易通用声明：

  declare module 'untyped-old-library';

  这能告知编译器将该包的所有导出暂视为 any，立刻解除编译阻断。

3. 相对路径导入省略扩展名的问题

在已有 JavaScript 代码中，import { add } from './math' 不带后缀。当 math.js 变为 math.ts 时，只要 tsconfig.json 中的 moduleResolution 配置为 node，TypeScript 就能无缝解析无扩展名模块。

但如果旧代码中硬编码了 import { add } from './math.js'，需要特别留意：如果项目使用现代打包器（如 Webpack/Vite），将 .js 改为 .ts 后保持省略后缀最为稳妥；如处于 Node.js 原生 ESM 模式，则应遵循 TypeScript 5.0+ 推荐的相对路径扩展名映射规范。

七、第六步：迁移全景对比与工程化落地检查清单

完成初步迁移后，团队可以基于稳定的基线，在后续迭代中根据文件活跃程度逐步补全类型。以下汇总了激进的“全量重写”与基于 tsc --allowJs 的“渐进重命名”方案在关键维度的对比。

工程化落地阶段性检查清单

借助 tsc --allowJs 建立的双模解析通道，搭配 git mv 脚本的自动化重命名，使看似庞大复杂的 TypeScript 迁移工程拆解为低风险、可量化、可持续推进的日常改进。遵循这套工程范式，团队不仅能在无任何业务阻断的前提下平稳演进代码库，更能将每一条类型提示真正转化为提升系统稳定性的生产力保障。