如何阻止TypeScript将用于导入ESM的动态导入转译为require()?
问题根因
tsc在传统module: "commonjs"编译模式下,会将所有动态import()语法降级为基于require()的辅助实现(附带__importStar、__importDefault等编译辅助函数),直接丢失Node.js原生动态import的能力。而CommonJS环境下的Node原生动态import,是加载ESM模块的唯一官方路径,被转写为require后自然无法正常加载本地的Lib ESM项目。
可落地解决方案
方案1:调整tsconfig配置,保留原生动态import
该方案改动最小,无需编写额外辅助代码:
- 打开DiscordBot项目根目录下的
tsconfig.json - 修改
compilerOptions下的三项关键配置:- 将
module字段值从默认的"commonjs"改为"node16"(或更高的"nodenext") - 同步将
moduleResolution字段值设为和module匹配的"node16" - 确认
target字段值不低于"es2018",更低的target配置会主动移除动态import语法
- 将
- 保持项目
package.json中"type": "commonjs"的设置不变,tsc在node16模式下会根据该字段识别当前项目的模块系统,不会将代码编译为ESM格式
配置生效后,tsc会识别当前项目运行在Node.js CommonJS上下文中,不再改写原生动态import()调用,编译输出的导入逻辑和你手动修改js文件的效果完全一致,可直接被Node正常执行。
方案2:编写加载辅助函数,绕过tsc的转译逻辑
如果不想调整tsc的模块编译模式,可以通过极小的代码逻辑避开tsc的静态转译:
- 在DiscordBot项目中新建
esmLoader.ts,写入以下代码:
import path from 'node:path'; import { pathToFileURL } from 'node:url'; // 通用ESM加载器,绕过tsc对动态import的转译 export async function loadEsmModule<T>(modulePath: string): Promise<T> { // 转换本地路径为Node动态import要求的file协议URL const absolutePath = path.resolve(process.cwd(), modulePath); const moduleUrl = pathToFileURL(absolutePath).href; // 通过Function构造器包裹原生import,tsc静态扫描时无法识别,不会转写为require const nativeImport = new Function('targetUrl', 'return import(targetUrl)') as (url: string) => Promise<T>; return nativeImport(moduleUrl); }
- 将项目中所有原直接编写的
await import('Lib的导入路径'),替换为await loadEsmModule<Lib的类型定义>('Lib的导入路径')
该方案的原理是,tsc做静态语法转译时,仅会扫描代码中直接书写的import()语法,不会解析new Function字符串中的代码,因此字符串内的原生动态import会原封不动保留在编译产物中,由Node.js原生执行,无需再手动修改编译后的js文件。
常见避坑提示
- 保持
esModuleInterop配置为开启状态,该设置不会影响上述两个方案的运行,还能减少导入ESM模块时的类型报错 - 本地路径导入Lib时,必须通过
pathToFileURL转换路径格式,否则Node会抛出ERR_UNSUPPORTED_ESM_URL_SCHEME错误 - 建议将TypeScript版本升级到5.x以上,低于4.5的版本在node16模块模式下存在动态import转译的已知bug
内容的提问来源于stack exchange,提问作者The Freeze
相关产品推荐
相关产品推荐

