使用TypeScript时Express无法通过import导入的问题排查

核心问题拆解 #

报错SyntaxError: Cannot use import statement outside a module本质是Node.js未将你的文件识别为ES模块，再加上直接用node运行TS文件的操作本身存在问题，具体分为以下几点：

1. dev脚本直接用node运行.ts文件 #

Node.js默认不支持直接执行TypeScript文件，你当前的dev脚本node --env-file=.env --watch server.ts是让node直接读取TS源码，它既不会转译TS语法，也无法处理里面的ES模块import语句，必然报错。

2. package.json未声明ES模块类型 #

Node.js默认将.js/.ts文件当作CommonJS模块处理，你使用了ES模块的import语法，但未明确告诉Node.js这是ES模块，因此触发“不能在模块外使用import”的错误。

3. tsconfig.json缺少关键模块配置 #

你仅修改了target和outDir，但未设置module和moduleResolution，TypeScript转译后的代码模块格式会与Node.js的预期不匹配，进一步加剧模块识别问题。

具体修复步骤 #

步骤1：修改package.json，声明ES模块 #

在package.json中添加"type": "module"，明确告诉Node.js项目使用ES模块：

{
  "type": "module",
  // 其他原有配置...
  "scripts": {
    "dev": "tsx --env-file=.env --watch server.ts",
    "build": "tsc",
    "start": "node build/server.js"
  }
}

步骤2：替换dev脚本的运行工具 #

使用tsx替代node来直接运行TS文件，它会实时转译TS并原生支持ES模块。先安装tsx开发依赖：

npm install -D tsx

然后将dev脚本替换为上述配置中的内容。

步骤3：完善tsconfig.json的模块配置 #

更新tsconfig.json，确保模块相关配置适配Node.js的ES模块规则：

{
  "compilerOptions": {
    "target": "ES2021",
    "outDir": "./build",
    "module": "ESNext", // 生成符合标准的ES模块代码
    "moduleResolution": "NodeNext", // 适配Node.js的ES模块解析逻辑
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true // 可选，开启TypeScript严格类型检查
  },
  "include": ["server.ts"] // 指定需要编译的TS文件，可根据项目结构调整
}

步骤4：验证修复 #

• 开发环境：执行npm run dev，tsx会实时转译TS文件并运行，import语法可正常使用。
• 生产环境：先执行npm run build将TS编译到build目录，再执行npm run start，Node.js会识别build目录下的ES模块代码正常运行。

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