使用ts-node-esm运行ESM格式TS文件时出现无追踪语法错误

1. tsconfig.json模块配置不匹配 #

.mts文件要求TypeScript采用Node.js的ESM模块解析策略，若配置错误会直接触发语法解析失败：

• 打开tsconfig.json，确认以下配置项：

  {
    "compilerOptions": {
      "module": "NodeNext",
      "moduleResolution": "NodeNext",
      "target": "ES2020", // 最低要选支持ESM的目标版本
      "allowSyntheticDefaultImports": true // 解决`import fs from "fs"`这类默认导入的语法问题
    }
  }
  

• 运行脚本时显式指定tsconfig路径，避免使用默认配置：修改npm脚本为

  "custom-script": "ts-node-esm --project ./tsconfig.json ./myScript.mts"
  

2. 全局ts-node与本地TypeScript版本不兼容 #

全局安装的ts-node常和项目本地依赖的typescript版本不匹配，导致解析逻辑冲突：

• 卸载全局ts-node：npm uninstall -g ts-node
• 改为本地安装依赖：npm install --save-dev ts-node typescript
• 保持npm脚本不变（npm会自动优先使用node_modules内的可执行文件）

3. 代码存在ESM与CommonJS混写错误 #

.mts文件严格遵循ESM规范，混写CommonJS语法会触发语法错误：

• 把所有require()调用替换为ESM的import语法
• 若必须使用CommonJS模块，改用动态导入：const fs = await import('fs')
• 检查导入语句的拼写，比如是否漏写from、引号是否配对

4. Node.js版本过低 #

Node.js v14及以下对ESM的支持存在局限性，建议升级到v16+（推荐v18 LTS）：

• 查看当前版本：node -v
• 升级后重新运行脚本

5. ts-node ESM模式缓存残留 #

ts-node的缓存可能保留了旧的配置或代码，导致错误无法更新：

• 修改脚本添加清缓存参数：

  "custom-script": "ts-node-esm --clear-cache --project ./tsconfig.json ./myScript.mts"
  

内容的提问来源于stack exchange，提问作者Susccy