JavaScript import() 在浏览器与 Node.js 环境中的兼容性差异

动态导入语法 import(specifier) 作为 ECMAScript 2020 纳入规范的标准特性，提供了一种在代码运行时按需异步加载模块的能力，并返回一个解析出模块命名空间对象的 Promise。尽管在语法层面上浏览器与 Node.js 均严格遵从同一套语言规范，但在具体的宿主环境实现中，由于资源获取通道（网络 HTTP 请求与浏览器安全沙箱 vs 本地文件系统 I/O 与模块系统）、标识符解析管道以及对 CommonJS 的兼容机制存在本质不同，两者在实际应用中展现出了显著的兼容性差异。

一、底层加载机制与模块解析生命周期差异

理解 import() 行为差异的根源，首先在于区分两个运行时的底层执行管道。浏览器是纯粹的网络驱动环境，每一个动态加载都需要经过 URL 规范化、网络发起、CORS 鉴权与 MIME 检查；而 Node.js 是基于本地磁盘（以及内置模块子系统）的单机运行时，其模块定位主要由内部的包查找算法处理。

二、模块标识符（Specifier）解析规则的冲突与差异

在传入 import(specifier) 的参数字符串处理上，两个环境的行为差异最为直接，主要表现在裸标识符、文件扩展名和 URL 协议三个方面。

1. 裸模块标识符（Bare Specifier）

裸模块标识符指的是形如 import('lodash') 或 import('dayjs') 这样不以 /、./ 或 ../ 开头的字符串。在 Node.js 中，这是最标准的使用方式，Node.js 会自当前目录向上遍历 node_modules 并结合目标包的 package.json 查找入口。

然而在原生浏览器中，直接执行 import('lodash') 会立即抛出异常：TypeError: Failed to resolve module specifier "lodash". Relative references must start with either "/", "./", or "../".。为了在浏览器中原生使用裸标识符，必须在 HTML 中预先声明 <script type="importmap"> 映射表：

<!-- 浏览器端通过 Import Maps 支持裸模块标识符 -->
<script type="importmap">
{
  "imports": {
    "lodash": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/lodash.js"
  }
}
</script>
<script type="module">
  const { debounce } = await import('lodash');
</script>

2. 文件扩展名补全（Extension Auto-resolution）

在传统 Node.js CommonJS 开发中，开发者习惯书写 require('./utils')，由系统自动尝试 .js、.json 或 /index.js。但在原生 ES Modules 规范中，包括 import() 在内，均不支持自动补全扩展名。

• 浏览器环境：必须显式书写完整路径（如 import('./utils.js')）或由服务端配置路由重定向；如果请求 ./utils，浏览器会直接向服务器发送对应路径的 HTTP 请求，若服务器未返回对应的 JavaScript 资源与有效 MIME，则直接 404 或报错。
• Node.js 环境：在原生 ESM 模式（"type": "module"）下，默认严格要求显式扩展名，执行 import('./utils') 会抛出 ERR_MODULE_NOT_FOUND。虽然在早前版本存在试验性开关（如 --experimental-specifier-resolution=node），但在生产与现代版本中已被弃用，统一要求显式后缀。

3. 协议与资源类型支持（Protocols）

浏览器天然支持 https:、http:、blob: 与 data: 协议，但完全不认识 node: 内置协议；Node.js 原生支持 file:、node:（如 import('node:fs')）与 data: 协议，但默认不支持直接通过 https:// 远程 URL 动态加载代码（需要显式开启 --experimental-network-imports 标志）。

三、执行上下文与宿主互操作性

除了路径解析规则外，import() 允许被调用的上下文环境以及跨模块系统交互的能力，也展现出鲜明的环境特异性。

在调用场景上，两者的宽容度存在重要差异：

• 浏览器脚本类型：import() 不仅可以在 <script type="module"> 中调用，也可以在传统的经典脚本（Classic Script，即普通的 <script>）、用户事件交互回调（如按钮点击）以及 Web Worker 中直接执行。这是经典脚本接入现代 ES 模块体系的唯一原生入口。
• Node.js 跨模块体系桥接：Node.js 原生区分 CommonJS（.cjs 文件或未声明 type: module）与 ESM（.mjs 文件或声明 type: module）。静态导入 import x from 'y' 无法在 CommonJS 中书写，但 import() 作为表达式可以在 CommonJS 文件内自由执行。

四、CommonJS 互操作与导入属性（Import Attributes）支持

当动态导入的目标并非标准的 ECMAScript 模块文件时，两个环境的兼容差异尤为突出。

1. CommonJS 互操作机制

浏览器内核本身没有 CommonJS 的概念。如果你尝试在浏览器原生 import() 一个包含 module.exports = ... 的模块，浏览器会将其按普通 JavaScript 脚本解析，通常因找不到全局 module 或 exports 变量而触发运行期异常。

Node.js 则实现了自动包裹机制：当 Node.js 的 import() 遇到 CommonJS 文件时，它会执行该 CJS 模块，并将 module.exports 的值赋予返回命名空间的 default 属性。同时，Node.js 会尝试静态分析 CJS 对象的属性并提供具名导出，但这种推断并不保证覆盖全部动态挂载的键，因此读取 mod.default 是最稳妥的兼容写法。

2. 导入属性（Import Attributes / Import Assertions）

动态导入 JSON 或 CSS 资源是现代前端开发的重要需求。规范经历了从早期 assert { type: 'json' } 到目前正式的 with { type: 'json' } 的语法更迭：

// 现代标准规范（Import Attributes）
const data = await import('./config.json', { with: { type: 'json' } });
console.log(data.default);

在环境兼容性上：

• Node.js：Node.js 16.14.0 起支持 assert 语法；从 Node.js 20.10.0 和 22.0.0 开始全面支持标准的 with 语法，并逐步将 assert 标记为过时弃用。
• 浏览器环境：Chrome 123+、Safari 17.2+ 以及 Firefox 125+ 已经全面支持 with 语法。此外，部分现代浏览器还支持通过 with { type: 'css' } 导入 CSS 样式表生成 CSSStyleSheet 实例供 Shadow DOM 使用，而 Node.js 运行时由于缺少 DOM/CSSOM 解析引擎，原生不支持此类类型。

五、缓存生命周期、性能与异常排查

在性能考量与异常处理机制上，宿主差异同样不可忽视：

1. 模块缓存生命周期

两个环境对同一个标识符的重复 import() 调用均具备缓存特性：只在第一次调用时执行模块的顶层代码，后续调用直接返回已评估完毕的同一模块命名空间实例。但是，缓存的失效机制截然不同：

• 浏览器环境：模块缓存受浏览器页面生命周期和 HTTP 强缓存/协商缓存影响。如果需要跳过浏览器模块缓存重新执行脚本，通常需要附加随机查询参数（如 import(`./module.js?t=${Date.now()}`)）。
• Node.js 环境：模块一旦加载进内部 ESM Module Registry，在当前 Node.js 进程存活期间便永久常驻。目前 Node.js 原生并未对外暴露类似 CommonJS 中 delete require.cache[key] 这样方便清除 ESM 缓存的官方 API。

2. 异常捕获的最佳实践

由于 import() 是异步返回 Promise，必须通过 try...catch 或 .catch() 明确拦截异常。两个环境常见的报错类型包括：

async function safeLoadModule(specifier) {
  try {
    const module = await import(specifier);
    return module;
  } catch (err) {
    if (err.name === 'TypeError') {
      // 浏览器中多为：裸模块名无法解析、CORS 违规或 MIME 类型错误
      // Node.js 中多为：传递非字符串标识符或类型错误
      console.error('模块解析失败或跨域被拦截:', err.message);
    } else if (err.code === 'ERR_MODULE_NOT_FOUND') {
      // Node.js 典型错误：文件不存在或相对路径缺少 .js 扩展名
      console.error('文件未找到，请检查路径与扩展名:', err.message);
    } else {
      // 模块自身的顶层语法或运行时执行错误
      console.error('模块执行期间崩溃:', err);
    }
    throw err;
  }
}

六、跨环境同构开发的避坑清单与实践建议

在同时需要兼顾浏览器客户端与 Node.js 服务端（例如 SSR 框架、通用 SDK 或跨平台 CLI 工具）的同构开发中，开发者应恪守以下原则：

总结

import() 动态导入在语法层面虽然提供了统一的规范接口，但其在浏览器与 Node.js 中的实际运行高度依赖于宿主环境的基础设施。浏览器以 URL 为核心、由网络协议与浏览器安全机制主导；Node.js 以本地文件系统为核心、由多模块子系统（CJS/ESM）与 package.json 查找规则主导。在日常开发中，通过显式书写文件扩展名、利用 Import Maps 规范前端裸模块解析、做好 CommonJS 的 default 导出防御解构，以及统一采用现代标准的 with 导入属性，即可在不同环境中获得可靠、一致的动态导入体验。