本文旨在解决Node.js开发中常见的SyntaxError: Cannot use import statement outside a module错误。当开发者尝试在以CommonJS模块（require）为主的项目中使用ES模块（import）时，通常会遇到此问题。核心解决方案是在package.json文件中设置"type": "module"，从而将项目配置为ES模块环境，并可能需要相应地调整现有的require语句。
理解Node.js模块系统与语法错误
Node.js在其发展历程中，逐渐从最初的CommonJS模块系统（使用require()和module.exports）过渡到支持ES模块（使用import和export）。当你在一个默认被Node.js识别为CommonJS模块的项目中尝试使用ES模块的import语法时，就会遇到SyntaxError: Cannot use import statement outside a module错误。这通常发生在你想引入一个现代库（如http-proxy-agent）而该库默认采用ES模块导出时。
另一个常见的误区是，即使项目默认是CommonJS，尝试用const { HttpProxyAgent } = require('http-proxy-agent');来引入一个纯ES模块，也可能导致TypeError: createHttpProxyAgent is not a function或类似错误，因为ES模块的导出机制与CommonJS的module.exports不同，直接使用require可能无法正确解析其命名导出。
解决方案：配置项目为ES模块
解决这个问题的最直接和推荐的方法是明确告诉Node.js你的项目是一个ES模块项目。这可以通过修改项目的package.json文件来实现。
步骤一：修改package.json
在你的项目根目录下的package.json文件中，添加或修改"type"字段为"module"：
{
// ... 其他配置项
"name": "your-nodejs-app",
"version": "1.0.0",
"description": "A Node.js application",
"main": "index.js",
"type": "module", // 添加或修改此行
"scripts": {
"start": "node index.js"
},
"dependencies": {
"http-proxy-agent": "^6.0.0"
// ... 其他依赖
}
}步骤二：使用import语法引入模块
完成package.json的修改后，你就可以在你的.js文件中放心地使用import语法来引入ES模块了：
// 例如，引入 http-proxy-agent
import { HttpProxyAgent } from 'http-proxy-agent';
// 你的其他代码
const agent = new HttpProxyAgent('http://your-proxy-server:port');
// ...注意事项：CommonJS模块的兼容性
一旦你在package.json中设置了"type": "module"，Node.js会将该项目中的所有.js文件默认视为ES模块。这意味着：
-
现有require语句可能需要转换： 如果你的项目中存在大量使用require语句引入其他本地模块或第三方CommonJS模块的代码，这些语句可能需要被转换为import语句。例如：
-
文件扩展名：
- 在"type": "module"的项目中，.js文件被视为ES模块。
- 如果你仍需要在一个ES模块项目中编写CommonJS模块，可以使用.cjs文件扩展名。Node.js会始终将其视为CommonJS模块，无论package.json中的"type"设置如何。
- 反之，如果你在一个CommonJS项目中（即没有设置"type": "module"或设置为"type": "commonjs"），但想使用ES模块，可以使用.mjs文件扩展名。Node.js会始终将其视为ES模块。
-
__dirname和__filename： 在ES模块中，全局变量__dirname和__filename不再可用。你需要使用import.meta.url来构造等效的路径：
import { fileURLToPath } from 'url'; import { dirname } from 'path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename);
总结与最佳实践
在现代Node.js开发中，推荐尽可能地采用ES模块系统。通过在package.json中设置"type": "module"，你可以充分利用ES模块的优势，如静态分析、更好的tree-shaking支持等。
当从CommonJS迁移到ES模块时，请务必进行全面的测试，以确保所有模块的导入和导出都按预期工作。对于大型遗留项目，可以考虑分阶段迁移，例如先将新的代码和依赖项使用ES模块，而旧代码暂时保持CommonJS，通过使用.mjs和.cjs文件扩展名来区分。然而，最清晰和推荐的方式是统一整个项目的模块系统。
