如何在 CommonJS 项目中无缝使用 ES 模块（如 translate）-js教程-PHP中文网

如何在 CommonJS 项目中无缝使用 ES 模块（如 translate）

本文详解在 node.js 16+ 的 commonjs 项目中混合使用 require 和 import 的兼容方案，重点解决“cannot use import statement outside a module”错误，并提供安全、可维护的过渡策略。

本文详解在 node.js 16+ 的 commonjs 项目中混合使用 require 和 import 的兼容方案，重点解决“cannot use import statement outside a module”错误，并提供安全、可维护的过渡策略。

在 Node.js 中，CommonJS（require/module.exports）与 ES 模块（import/export）属于两种互不兼容的模块系统。当你引入仅支持 ESM 的第三方包（如 translate@2.0.2）时，直接 import 会触发 SyntaxError: Cannot use import statement outside a module；而强行将项目设为 "type": "module" 又会导致所有原有 require() 调用失效——这是典型的模块系统迁移阵痛。

根本解法不是二选一，而是桥接共存。Node.js 自 v12.20.0 起提供了官方兼容机制：通过 createRequire() 在 ESM 环境中创建一个兼容 CommonJS 的 require 函数。该方案无需重写全部代码，也避免了 .mjs 动态导入带来的链式改造负担。

✅ 推荐解决方案（零重构、全兼容）

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

在 package.json 中保留 "type": "module"（启用 ESM 支持）；
在需同时使用 require 和 import 的文件顶部，显式创建 require 实例：

// src/utils/translator.js
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

// ✅ 仍可正常使用 CommonJS 模块
const mongoose = require('mongoose');
const jwt = require('jsonwebtoken');

// ✅ 同时支持 ESM 模块（如 translate）
import translate from 'translate';

// 封装翻译服务（ESM + CommonJS 混合调用）
export const translateText = async (text, targetLang = 'es') => {
  try {
    const result = await translate(text, targetLang);
    return { success: true, translated: result };
  } catch (error) {
    console.error('Translation failed:', error.message);
    return { success: false, error: error.message };
  }
};

⚠️ 关键注意事项

createRequire(import.meta.url) 必须在 ESM 文件（.js + "type": "module"）中使用，不可用于 CommonJS 文件；
所有 .js 文件均按 ESM 解析，因此原 module.exports 需改为 export（或保留 exports.xxx 写法，但推荐统一为 export）；
若仍有部分文件必须用 CommonJS（如某些旧版工具链），可将其后缀改为 .cjs，Node.js 会自动按 CommonJS 解析，不受 "type": "module" 影响；
translate 包本身依赖 node-fetch，确保已安装（npm install node-fetch@2 或升级至 translate@3.0.0+ 使用内置 fetch）；
动态 import() 仅适用于临时、条件性加载，不推荐作为主逻辑（如 const { translate } = await import('translate')），因其返回 Promise 且破坏同步语义。

? 验证与部署建议
运行前请确认：