如何解决Node.js+TypeScript项目ES import报模块外无法使用的错误

你遇到的Cannot use import statement outside a module报错有两个核心诱因：

1. Node默认仅对.mjs后缀文件、或者package.json顶层声明了"type": "module"的项目启用ES Module语法解析，普通JS文件默认走CommonJS规范，不识别import语句
2. 你直接用原生node命令运行.ts后缀的TypeScript文件，Node没有内置TS解析能力，直接把TS源码当JS执行自然会报错

方案一：最小改动兼容模式（走CommonJS转译，适合大多数普通项目） #

• 第一步：安装ts-node作为开发依赖，用来直接运行TS文件，无需提前编译

yarn add -D ts-node

• 第二步：修改package.json中的scripts配置，把start命令替换为：

"start": "ts-node src/index.ts"

• 你当前tsconfig中"module":"commonjs"的配置已经可以自动把TS里的ES import/export转成CommonJS规范的语法，改完直接执行yarn start即可正常运行

方案二：原生ES Module模式（不需要转译CommonJS，完全用ES规范） #

• 第一步：在package.json顶层添加配置，告诉Node当前项目用ES Module规范：

"type": "module"

• 第二步：修改tsconfig.json的compilerOptions配置，适配ES Module解析规则：

{
    "compilerOptions":{
        "target":"es2020",
        "module":"NodeNext", // 把原来的commonjs改成NodeNext
        "rootDir":"./src",
        "moduleResolution":"NodeNext",
        "esModuleInterop":true,
        "forceConsistentCasingInFileNames":true,
        "strict":true,
        "skipLibCheck":true,
        "allowImportingTsExtensions": true, // 新增配置，允许导入ts后缀文件
        "noEmit": true // 新增配置，不需要输出编译后的js文件
    }
}

• 第三步：修改package.json的start命令，适配ES Module模式的ts-node运行规则：

"start": "node --loader ts-node/esm src/index.ts"

注意事项 #

• 原生ES Module模式下所有相对路径导入都需要补全后缀名，比如import util from './util'需要改为import util from './util.ts'
• 不要在项目内混用CommonJS的require语法和ES Module的import语法，会触发额外的兼容报错

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