Node.js 报 Cannot use import statement outside a module

通过让 package type、文件扩展名与工具链与 ES 模块对齐，修复 import 语句在模块外使用的错误。

症状

运行使用 import 语法的文件时报 SyntaxError: Cannot use import statement outside a module。该文件在会隐式启用 ESM 的转译器或测试运行器下可能可用，从而掩盖问题，直到用原生 node 或其它工具运行时才暴露。错误关乎运行时如何归类该文件，而非 import 行本身。

诊断

检查 package.json 的 type 与文件扩展名；把文件改名为 .mjs 再运行对比；搜索是否存在 require 与 import 混用。

node -p "require('./package.json').type" ; ls package.json *.mjs *.cjs

根因

运行时把该文件归类为 CommonJS，因此 ESM 的 import 语法成了语法错误。模块系统由扩展名与 package type 决定，而非文件内使用的语法。

修复

为 ESM 项目设置 “type”: “module”，或对单个文件使用 .mjs，或在构建中做转译。避免在同一文件中混用 require 与 import。

验证

再次运行确认解析并执行，再跑整个测试套件确认其它模块仍能加载。

常见陷阱

把 .ts 直接交给 node 运行而不转译会触发同类错误；应先编译或使用支持的类型剥离。