模块系统

模块解决的是 作用域隔离 + 依赖声明。全栈日常踩坑几乎都在：CJS 和 ESM 两套规矩、循环依赖、以及「源码能 import，产物却按另一种模块格式发出」。类型侧写法见 TypeScript 模块与命名空间；打包时模块怎么变成浏览器文件，见构建工具与 Vite。

解决什么问题

痛点	模块怎么帮
全局变量互相覆盖	一文件一模块，导出显式
不知道依赖从哪来	`import` / `require` 是图，可静态分析
Node 能跑、浏览器报错	宿主默认模块格式不同；要打包或标 `type="module"`
改 A 却影响到不该用 A 的包	依赖应走 package 导出，而不是深挖 `node_modules` 内部文件

一句话：ESM 是静态、异步友好的标准；CJS 是 Node 历史默认。混用要按边界处理，不要假装它们是同一种语法。

	CommonJS (CJS)	ES Module (ESM)
语法	`require` / `module.exports`	`import` / `export`
加载	同步，运行到那一行才执行	静态声明，先链接再求值；`import()` 动态
典型文件	`.cjs`、未 `"type":"module"` 的 `.js`（Node）	`.mjs`、`"type":"module"` 的 `.js`、浏览器 native
导出形状	`exports` 对象，可事后改属性	绑定（live binding），导出的是只读绑定
循环依赖	拿到尚未填完的 `exports`	先建立绑定，求值顺序仍可能读到暂时的 `undefined`

// CJS
const { add } = require("./math");
module.exports = { add };

// ESM
import { add } from "./math.js";
export { add };

浏览器原生 ESM 必须带齐路径或靠 import map；不能省略扩展名还指望像 Webpack 一样猜 .js。Vite 开发期用原生 ESM，所以源码侧更接近标准行为。

双模包（自己要同时给 require 和 import 用）靠 exports 条件导出，而不是在 ESM 文件里写 require。

{
  "name": "lib",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

import ESM 里不能直接 require。反过来，CJS require 一个纯 ESM 包会报错，要用动态 import()（返回 Promise）。

a.js → b.js → a.js

两边都还没执行完就互相要值，读到的可能是 未初始化的绑定 或 半成品 exports。

出现 Cannot access X before initialization（ESM 的 TDZ）或「导入是 undefined」，先画依赖图，别先怪打包器。

const { init } = await import("./heavy.js");

阶段	模块含义
源码	你写 `import`，图由打包器或运行时解析
开发（Vite）	浏览器直接加载 ESM 转换后的模块
生产产物	常打成少量 chunk（仍可能是 ESM 或 IIFE/CJS，看配置）
Tree-shaking	依赖 ESM 静态结构；CJS 很难摇掉没用到的导出

sideEffects、默认导出、export * 都会影响摇树，细节放到产物篇。这里记住：想摇树，先用 ESM。