如何利用静态分析技术自动将老旧项目中的 CommonJS 语法迁移至标准 ESM

静态分析能自动识别重写CommonJS语法但不能一键迁移，需三步：配置识别（检查package.json"type": "module"）、语法转换（require→import等）、边界修复（__dirname替换、动态导入标注等）。

静态分析能自动识别和重写 CommonJS 模块语法，但不能“一键完成”迁移——它解决的是可判定部分，比如 require 和 module.exports 的模式匹配与替换，而路径补全、动态导入判断、__dirname 替换、第三方兼容处理等需结合规则+人工校验。核心是三步：配置识别、语法转换、边界修复。

识别项目模块类型并启用 ESM 上下文

静态分析工具（如 jscodeshift、esbuild --tree-shaking 配合自定义插件，或专用迁移工具 cjs-to-esm）需先确认项目是否已声明 ESM 意图：

• 检查 package.json 是否含 "type": "module"；若无，工具应提示添加，否则后续解析可能误判为 CJS
• 若存在混合模块（如部分 .cjs 文件），静态分析需按扩展名分组处理，避免跨类型误改
• 不依赖文件扩展名推断（如仅凭 .js 判断）——Node.js v14+ 后，type 字段才是权威依据

自动化重写 import/export 语句

这是静态分析最成熟的部分，基于 AST 精准定位并替换：

• require 调用 → import 声明：将 const fs = require('fs'); 转为 import fs from 'fs';；将 const { read } = require('fs'); 转为 import { read } from 'fs';
• 路径补全强制化：对相对路径 require('./util') 自动补扩展名，生成 import util from './util.js'（非 .mjs，因 type: module 下 .js 已为 ESM）
• module.exports → export default / named：识别 module.exports = function() {} → export default function() {}；识别 module.exports.a = 1; module.exports.b = 2; → export const a = 1; export const b = 2;
• 跳过无法静态推断的 case，例如 require(someVar) 或拼接路径 require('./' + name)，标记为「需手动处理」

识别并标注运行时边界问题

静态分析无法执行代码，但可检测潜在 ESM 不兼容点并生成报告：

• __dirname / __filename 使用处：定位所有出现位置，替换建议为 import.meta.url 并附转换公式（如 new URL('./', import.meta.url).pathname）
• 条件 require：匹配 if (x) require('a') else require('b') 模式，提示改用 await (x ? import('a') : import('b'))，并检查所在作用域是否支持顶层 await
• 第三方包兼容性扫描：读取 node_modules 中各依赖的 package.json，提取 exports、type、main、module 字段，标出仅提供 CJS 入口的包（如未导出 exports['.']['import']）
• 循环引用警告：通过 AST 构建依赖图，高亮 CJS 中合法但 ESM 中会报错的循环 import 链（如 A → B → A）

生成可验证的迁移结果与回滚方案

高质量的静态分析不止输出代码，还提供验证支持：

• 生成差异报告（diff），逐文件列出修改行、原内容、新内容及修改类型（如「require→import」「path补全」「__dirname 替换」）
• 附带最小验证脚本：自动创建 test-esm.mjs，尝试 import 所有被修改的入口文件，捕获 ERR_MODULE_NOT_FOUND 或 ERR_UNSUPPORTED_DIRNAME
• 保留原始文件备份（如 index.js.cjs.bak），确保可快速回退
• 不自动修改 node_modules 或配置文件（如 webpack.config.cjs），这些需单独评估