本文详细介绍了在 node.js 应用中如何正确配置和使用 es 模块（esm）的 `import` 语句，以解决常见的 'cannot use import statement outside a module' 错误。通过修改 `package.json` 文件中的 `type` 字段为 `module`，并调整相关代码，开发者可以顺利地在项目中引入并利用现代 javascript 模块化特性，提升代码的可维护性和可读性。
在 Node.js 项目开发中，开发者经常会遇到需要引入不同模块化规范的库。当项目中主要使用 CommonJS 规范的 require 语句（例如 const translate = require('google-translate-open-api');）时，尝试引入一个只支持 ES 模块（ESM）规范的库（例如 http-proxy-agent）并使用 import { HttpProxyAgent } from 'http-proxy-agent'; 语句时，Node.js 运行时会抛出 SyntaxError: Cannot use import statement outside a module 错误。这表明当前项目环境并未被识别为 ES 模块。此外，如果尝试使用 require 语法去加载一个纯 ESM 模块，则可能会遇到 TypeError: createHttpProxyAgent is not a function 这类错误，因为 ESM 模块的导出机制与 CommonJS 不同，不能直接通过 require 方式解构其命名导出。
启用 ES 模块支持
为了在 Node.js 项目中正确使用 import 语句并兼容 ES 模块，最直接且推荐的方法是在项目的 package.json 文件中明确声明项目的模块类型为 module。
具体操作如下： 在项目的根目录下的 package.json 文件中添加或修改 type 字段：
{
// ... 其他配置
"name": "my-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"
// ... 其他依赖
}
}将 "type": "module" 添加到 package.json 后，Node.js 会将项目中的所有 .js 文件默认视为 ES 模块。这意味着你可以在这些文件中自由使用 import 和 export 语句。
使用 import 语句引入模块
一旦 package.json 中的 type 字段被设置为 module，你就可以按照 ES 模块的语法来引入所需的库了。例如，要引入 http-proxy-agent 模块，可以直接使用：
// index.js (或你的其他 .js 文件)
import { HttpProxyAgent } from 'http-proxy-agent';
// 接下来就可以正常使用 HttpProxyAgent 类了
const proxyAgent = new HttpProxyAgent('http://localhost:8080');
// 示例：使用代理发起一个 HTTP 请求
// const fetch = require('node-fetch'); // 如果node-fetch是CommonJS
// import fetch from 'node-fetch'; // 如果node-fetch是ESM
// fetch('http://example.com', { agent: proxyAgent })
// .then(res => res.text())
// .then(body => console.log(body))
// .catch(err => console.error(err));
console.log('HttpProxyAgent 模块已成功加载并实例化。');重要注意事项
在将项目类型设置为 module 后，需要注意以下几点，以确保项目平稳运行：
-
全局影响： 将 type 设置为 module 会影响项目中所有 .js 文件的默认解析方式。这意味着如果你的项目中存在大量使用 require 语句的 CommonJS 模块，它们可能需要进行相应的调整。
-
在 ESM 中加载 CommonJS： 如果你需要在 ES 模块文件中加载一个 CommonJS 模块，可以使用 createRequire 函数：
import { createRequire } from 'module'; const require = createRequire(import.meta.url); const commonJsModule = require('./path/to/commonjs-module.js'); - 显式 CommonJS 文件： 对于明确需要保持 CommonJS 规范的文件，可以将其文件扩展名更改为 .cjs（例如 legacy-module.cjs）。Node.js 会始终将 .cjs 文件视为 CommonJS 模块，无论 package.json 中的 type 设置如何。
-
在 ESM 中加载 CommonJS： 如果你需要在 ES 模块文件中加载一个 CommonJS 模块，可以使用 createRequire 函数：
文件扩展名： 在 ES 模块环境中，相对路径导入通常需要包含完整的文件扩展名，例如 import './myModule.js'; 而不是 import './myModule';。这有助于明确模块的类型和位置。
顶层 await： 在 ES 模块中，你可以在模块的顶层（即函数外部）使用 await 关键字，这在 CommonJS 模块中是不允许的。这使得异步初始化代码更加简洁。
-
__dirname 和 __filename： 在 ES 模块中，全局变量 __dirname 和 __filename 不再可用。你可以通过 import.meta.url 结合 path 模块来模拟它们的功能：
import path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); console.log('当前文件路径:', __filename); console.log('当前目录路径:', __dirname);
总结
通过在 package.json 中设置 "type": "module"，Node.js 开发者能够顺利地从 CommonJS 迁移到 ES 模块，或者在现有项目中集成需要 import 语法的现代模块。这一配置不仅解决了 SyntaxError: Cannot use import statement outside a module 错误，也使得项目能够利用 ES 模块带来的诸多优势，例如更清晰的模块依赖管理、更好的静态分析能力以及对顶层 await 等新特性的支持。在进行此项更改时，请务必检查并适当地调整项目中其他可能受影响的 require 语句、文件路径以及对 __dirname / __filename 的使用，确保项目平稳过渡。
