JavaScript模块化开发入门指南

JavaScript模块化并非简单的语法选择，而是关乎运行环境匹配的核心实践难题：浏览器需显式声明type="module"并使用URL路径，Node.js则依赖.mjs后缀或package.json中的"type":"module"配置，ESM与CommonJS的互操作存在单向限制，裸写import/export却忽略环境差异，正是ReferenceError和“Cannot use import statement outside a module”等报错的根源；真正决定模块能否正常工作的，不是你写了什么语法，而是代码将在哪个上下文中执行——理解并主动管理这一环境边界，才是现代JavaScript模块化开发成败的关键。

JavaScript 模块化不是“选不选”的问题，而是“用哪种、怎么用才不出错”的问题。ESM（import/export）已是现代前端开发的事实标准，但直接在浏览器或 Node.js 中混用 require、define 或裸写 IIFE，极易触发 ReferenceError: exports is not defined、Cannot use import statement outside a module 这类报错——根源往往不在语法写错，而在运行时环境与模块系统不匹配。

浏览器中直接使用 ESM 必须加 type="module"

不加这个属性，哪怕文件里全是 import/export，浏览器也会按传统脚本解析，立刻报错。

<script type="module" src="./main.js"></script>

• type="module" 启用 ES 模块上下文：自动启用严格模式、顶层 this 为 undefined、支持顶层 await
• 模块路径必须是相对或绝对 URL（如 ./utils.js、/lib/helpers.mjs），不能是 bare specifier（如 import { foo } from 'lodash'）——浏览器原生不解析包名
• 动态 import() 可绕过静态限制，且返回 Promise，适合按需加载：const mod = await import('./feature.js');

Node.js 中 ESM 需明确标识，且 .mjs 优先于 package.json 的 "type": "module"

Node 默认把 .js 当 CommonJS，即使写了 export 也会报错。两种方式可启用 ESM：

• 改后缀为 .mjs：Node 强制按 ESM 解析，无需其他配置
• 在 package.json 中设 "type": "module"：整个包内 .js 文件都走 ESM（但 require() 在 ESM 文件中不可用）
• 注意：__dirname 和 __filename 在 ESM 中不可用，要用 import.meta.url + file:// URL API 替代

CommonJS 和 ESM 互操作有单向限制，别硬混用

ESM 可以 import CommonJS 模块（如 const fs = require('fs') 的等价写法 import fs from 'fs'），但反过来不行：require() 无法加载原生 ESM 文件（会报 ERR_REQUIRE_ESM）。

• 若必须让 CommonJS 消费 ESM，得通过中间封装层（如导出一个 exports.default = ... 的 CJS 兼容入口）
• 第三方库如 Lodash 提供 lodash-es 专用于 ESM 场景，而 lodash 主要面向 CommonJS；用错会导致 tree-shaking 失效或循环依赖
• Vite/Webpack 等工具会自动处理互操作，但裸跑 Node 或浏览器时，这点必须手动兜底

模块化真正的难点不在语法，而在环境边界：浏览器不认 node_modules 路径，Node 不认裸 import，打包器又可能静默转换行为。写 export 前，先确认执行上下文是什么——这是比记住语法更关键的一步。

到这里，我们也就讲完了《JavaScript模块化开发入门指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！