Node.js 项目中 import 语句的使用与 ES 模块配置指南

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Node.js 项目中 import 语句的使用与 ES 模块配置指南

2025-11-04

浏览次数：次

返回列表

Node.js 项目中 import 语句的使用与 ES 模块配置指南

本文详细介绍了在 node.js 应用中如何正确配置和使用 es 模块（esm）的 `import` 语句，以解决常见的 'cannot use import statement outside a module' 错误。通过修改 `package.json` 文件中的 `type` 字段为 `module`，并调整相关代码，开发者可以顺利地在项目中引入并利用现代 j*ascript 模块化特性，提升代码的可维护性和可读性。

在 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 模块，它们可能需要进行相应的调整。
OneStory
OneStory 是一款创新的AI故事生成助手，用AI快速生成连续性、一致性的角色和故事。
319 查看详情
- 在 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 设置如何。
文件扩展名： 在 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 的使用，确保项目平稳过渡。