本文详解在 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 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 且破坏同步语义。
? 验证与部署建议
运行前请确认：
- Node.js ≥ 16.0（推荐 18.17+ 或 20.9+）；
- package.json 中 "type": "module" 已设置；
- 原有 require() 调用均已替换为 createRequire 创建的实例（或改用 import）；
- 启动脚本（如 nodemon src/index.js）无需额外 flag，ESM 支持已原生启用。
此方案平衡了渐进式迁移与生产稳定性，既满足新包的 ESM 要求，又最大限度保护存量代码资产，是当前 Node.js 生态中最稳健的模块共存实践。
