模块化

┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  无模块时代   │ → │  社区方案    │ → │  语言标准    │ → │  构建工具    │
│  2005-2009   │ │  2009-2013   │ │  2015+       │ │  2020+       │
│  script 标签 │ │  AMD/CMD     │ │  ES Modules  │ │  原生 ESM    │
└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘

问题：全局变量污染 + 依赖管理混乱

<script src="jquery.js"></script>     <!-- jQuery 定义 $ -->
<script src="prototype.js"></script>   <!-- Prototype 也定义 $ -->
<script src="app.js"></script>         <!-- $ 被覆盖了，代码崩溃 -->

顺序还得手动管理——jquery 必须在 app.js 前面

解决：每个模块有自己的作用域，显式声明依赖

import $ from 'jquery';      // 显式导入，不污染全局
import { ajax } from './api'; // 依赖关系一目了然

┌──────────────┐         ┌──────────────┐
│  a.js        │ require │  b.js        │
│              │ ──────→ │              │
│  const b =   │         │  module.     │
│  require(b)  │ ←────── │  exports = {}│
│              │ 返回值  │              │
└──────────────┘         └──────────────┘

// b.js — CommonJS 导出
const name = "module-b";
function greet() {
  return `Hello from ${name}`;
}

// module.exports 是模块对外暴露的接口——require 拿到的就是这个对象
module.exports = { name, greet };
// 注意：exports 是 module.exports 的引用，直接给 exports 赋值会断开引用
// 所以推荐直接操作 module.exports

// a.js — CommonJS 导入
const b = require("./b"); // 同步加载 b.js，执行其代码，返回 module.exports
console.log(b.name); // 'module-b'      // 通过返回的 exports 对象访问导出值
console.log(b.greet()); // 'Hello from module-b'

require() 的执行过程：

1. 解析路径 → 找到文件
2. 检查缓存 → 如果已加载，直接返回缓存的 exports
3. 如果没缓存 → 创建一个空的 module 对象
4. 执行模块代码 → 填充 module.exports
5. 缓存 module → 返回 module.exports

/**
 * CommonJS 的缓存机制：每个文件只执行一次，后续 require 直接返回缓存
 * 这就是为什么 CommonJS 模块是"单例"的
 */
// a.js
console.log("a 被加载了");
const b1 = require("./b"); // 第一次 require：加载并执行 b.js，缓存 module.exports
const b2 = require("./b"); // 第二次 require：直接返回缓存，不重新执行 b.js
console.log(b1 === b2); // true           // 同一个引用——证明模块只执行了一次

// b.js 只会被执行一次，输出一次 'a 被加载了'

/**
 * CommonJS 循环依赖的执行过程
 * 核心：遇到循环 require 时，返回的是当前已执行部分的 exports（半成品）
 * 这是 Node.js 处理循环依赖的机制——不会死循环，但拿到的值可能不完整
 */

// a.js
console.log("a 开始");
exports.done = false; // 设置 a 的初始状态
const b = require("./b"); // 遇到 require('./b') → 暂停 a，去执行 b.js
console.log("在 a 中, b.done =", b.done); // b 已经执行完毕，b.done = true
exports.done = true; // 更新 a 的状态
console.log("a 结束");

// b.js
console.log("b 开始");
exports.done = false; // 设置 b 的初始状态
const a = require("./a"); // 此时 a.js 还在执行中，Node.js 返回 a 当前的 exports
console.log("在 b 中, a.done =", a.done); // false — 拿到的是 a 执行到一半的"半成品"！
exports.done = true;
console.log("b 结束");
// 执行顺序：a 开始 → b 开始 → 在 b 中, a.done = false → b 结束 → 在 a 中, b.done = true → a 结束

┌──────────────┐         ┌──────────────┐
│  a.mjs       │ import  │  b.mjs       │
│              │ ──────→ │              │
│  import {    │         │  export const│
│    name      │ ←────── │  name = 'b'; │
│  } from './b'│ live    │              │
│              │ binding │              │
└──────────────┘         └──────────────┘

// b.mjs — ES Modules 导出
// export 声明必须在模块顶层（不能在 if/for/函数内），这是静态分析的前提
export const name = "module-b"; // 命名导出：导出变量的绑定（live binding）
export function greet() {
  return `Hello from ${name}`;
}
// 也可以统一导出：export { name, greet };

// a.mjs — ES Modules 导入
import { name, greet } from "./b.js"; // 按名称导入，名字必须匹配
console.log(name); // 'module-b'
console.log(greet()); // 'Hello from module-b'

// 重命名导入：用 as 关键字起别名
import { name as moduleName } from "./b.js";

// 默认导出：每个模块只能有一个 default export
// b.js: export default function() {}
// a.js: import myFunc from './b.js';  // 默认导出的名称可以自定义

// ❌ 不能在条件中使用 import
if (condition) {
  import { foo } from "./foo.js"; // SyntaxError
}

// ✅ 动态导入用 import()
const module = await import("./foo.js");

// ✅ 静态导入必须在顶层
import { foo } from "./foo.js";

ES Modules 的静态分析能力带来的好处：

1. Tree Shaking：编译时就能知道哪些 export 没有被 import，打包时删除未使用的代码
2. 代码分割：import() 动态导入可以实现按需加载
3. 类型检查：TypeScript 可以在编译时检查模块的类型

┌──────────┐         ┌──────────┐
│  模块 A  │ ──────→ │  模块 B  │
│          │ ←────── │          │
└──────────┘         └──────────┘
      ↑                    │
      └────────────────────┘
           循环依赖

// a.js
console.log("a 开始加载");
const b = require("./b");
console.log("a 中 b.done =", b.done); // 可能是不完整的值
exports.done = true;
console.log("a 加载完成");

// b.js
console.log("b 开始加载");
const a = require("./a");
console.log("b 中 a.done =", a.done); // false — a 还没执行完
exports.done = true;
console.log("b 加载完成");

CommonJS 的处理机制：

1. 执行 a.js → 遇到 require('./b') → 暂停 a.js，去执行 b.js
2. 执行 b.js → 遇到 require('./a') → a.js 正在执行中
3. Node.js 返回 a.js 当前已执行部分的 exports（不完整的值）
4. b.js 继续执行完毕
5. 回到 a.js 继续执行

结果：b.js 拿到的是 a.js 的"半成品"

/**
 * ESM 循环依赖的处理：通过 live binding 机制
 * 即使变量还没被赋值，绑定关系已在实例化阶段建立
 * 求值阶段赋值后，import 方通过 live binding 能拿到最新值
 */

// a.mjs
import { bDone } from "./b.mjs"; // 导入 b 的 bDone 变量（live binding）
console.log("a 中 bDone =", bDone); // 如果 a 先执行，bDone 可能还是 undefined
export const aDone = true; // 导出 aDone

// b.mjs
import { aDone } from "./a.mjs"; // 导入 a 的 aDone 变量（live binding）
console.log("b 中 aDone =", aDone); // 如果 b 先执行，aDone 可能还是 undefined
export const bDone = true; // 导出 bDone

ES Modules 的处理机制：

1. 解析阶段：静态分析所有 import/export，建立模块依赖图
2. 实例化阶段：为每个模块创建 Module Record，分配内存空间
3. 求值阶段：按照依赖顺序执行模块代码

ES Modules 的 live binding 机制让循环依赖更优雅：
- 即使变量还没被赋值，绑定关系已经建立了
- 等变量被赋值后，导入方能拿到最新值

// ❌ 循环依赖：A 和 B 直接互相引用
// service-a.js
import { processB } from "./service-b.js";
export function processA() {
  return processB() + 1;
}

// service-b.js
import { processA } from "./service-a.js";
export function processB() {
  return processA() + 1;
}

// ✅ 解决方案 1：提取公共模块
// shared.js
export function baseProcess() {
  return 1;
}

// service-a.js
import { baseProcess } from "./shared.js";
export function processA() {
  return baseProcess() + 1;
}

// service-b.js
import { baseProcess } from "./shared.js";
export function processB() {
  return baseProcess() + 2;
}

// ✅ 解决方案 2：依赖注入
// service-a.js
export function createServiceA(serviceB) {
  return { processA: () => serviceB.processB() + 1 };
}

┌──────────────────────────┐
│  源代码                   │
│  export function used() {}│  ← 被 import 了
│  export function unused(){}│  ← 没有被 import
└──────────────┬───────────┘
               │ Tree Shaking
               ▼
┌──────────────────────────┐
│  打包结果                 │
│  function used() {}       │  ← 保留
│                          │
│  unused() 被删除了        │
└──────────────────────────┘

Tree Shaking 的实现步骤：

1. 构建依赖图：静态分析所有 import/export 语句
2. 标记（Mark）：从入口文件开始，标记所有被使用的 export
3. 清除（Sweep）：删除没有被标记的 export
4. 压缩（Minify）：删除死代码（dead code elimination）

// ❌ 情况 1：CommonJS 模块不能 Tree Shaking
const utils = require("./utils"); // 动态导入，编译时无法分析
utils.used();

// ❌ 情况 2：副作用（Side Effects）模块
// 如果模块有副作用，打包工具不敢删除它
import "./polyfill.js"; // 这个文件可能修改了全局对象

// ✅ 在 package.json 中声明无副作用
// { "sideEffects": false }
// 或者指定哪些文件有副作用：
// { "sideEffects": ["*.css", "./src/polyfill.js"] }

// ❌ 情况 3：导出被重新赋值
export let count = 0; // let 导出可能被修改，打包工具保守处理
export const COUNT = 0; // const 导出不会被修改，更安全

// webpack.config.js
module.exports = {
  mode: "production", // 自动开启 Tree Shaking
  optimization: {
    usedExports: true, // 标记未使用的导出
    minimize: true, // 删除死代码
    sideEffects: true, // 识别并跳过无副作用的模块
  },
};

// 确保使用 ES Modules 语法
import { debounce } from "lodash-es"; // ✅ 可以 Tree Shaking
import _ from "lodash"; // ❌ 无法 Tree Shaking（CommonJS）

┌──────────────┐         ┌──────────────┐
│  主包         │ import() │  异步 Chunk  │
│  (首页代码)   │ ──────→ │  (详情页代码) │
│              │ 返回     │              │
│              │ ←────── │              │
│              │ Promise │              │
└──────────────┘         └──────────────┘

用户访问首页 → 只加载主包
用户点击"查看详情" → 动态加载详情页代码

// 静态导入：打包时就确定依赖关系
import HeavyComponent from "./HeavyComponent";

// 动态导入：运行时按需加载
button.addEventListener("click", async () => {
  const { default: HeavyComponent } = await import("./HeavyComponent");
  render(HeavyComponent);
});

import { lazy, Suspense } from "react";

// 路由级别的代码分割
const Dashboard = lazy(() => import("./pages/Dashboard"));
const Settings = lazy(() => import("./pages/Settings"));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

// Webpack 会自动把 import() 的模块分割成独立的 Chunk
// 输出：
// main.js          — 主包（首页代码）
// Dashboard.js     — 异步 Chunk（详情页代码）
// Settings.js      — 异步 Chunk（设置页代码）

// 魔法注释：给 Chunk 命名
const Dashboard = lazy(
  () =>
    import(
      /* webpackChunkName: "dashboard" */
      "./pages/Dashboard"
    ),
);

/**
 * Webpack 打包后的运行时代码（简化版）
 * Webpack 将所有模块包装在一个 IIFE 中，用自己的 require 实现模块加载
 * 核心机制：模块缓存 + 包装函数 + 依赖注入
 */
(function (modules) {
  var installedModules = {}; // 模块缓存：已加载的模块不会重复执行

  /**
   * Webpack 版的 require：模拟 CommonJS 的 require 行为
   * @param {string} moduleId - 模块路径（如 './src/utils.js'）
   * @returns {object} 模块的 exports 对象
   */
  function __webpack_require__(moduleId) {
    if (installedModules[moduleId]) {
      // 检查缓存：已加载则直接返回
      return installedModules[moduleId].exports;
    }
    // 创建新模块对象：i=模块ID, l=是否已加载, exports=导出对象
    var module = (installedModules[moduleId] = {
      i: moduleId,
      l: false,
      exports: {}, // 空的 exports 对象，模块代码执行后填充
    });
    // 执行模块代码：用 call 绑定 this 为 module.exports
    // 传入 module, exports, __webpack_require__ 三个参数
    // 这就是为什么 CommonJS 模块中能直接用 module.exports 和 require()
    modules[moduleId].call(
      module.exports,
      module,
      module.exports,
      __webpack_require__,
    );
    module.l = true; // 标记为已加载
    return module.exports; // 返回填充后的 exports
  }

  // 加载入口模块，启动整个应用
  return __webpack_require__((__webpack_require__.s = "./src/index.js"));
})({
  // 模块表：每个模块路径对应一个包装函数（Webpack 将源码包装在这里）
  "./src/index.js": function (module, exports, __webpack_require__) {
    var _utils = __webpack_require__("./src/utils.js"); // 同步 require，加载 utils 模块
    console.log(_utils.add(1, 2));
  },
  "./src/utils.js": function (module, exports) {
    exports.add = function (a, b) {
      return a + b;
    }; // 挂载到 exports 上
  },
});

Webpack 开发模式：
  1. 分析所有依赖
  2. 把所有模块打包成 Bundle
  3. 启动开发服务器
  4. 修改文件 → 重新打包 → 刷新

Vite 开发模式：
  1. 启动开发服务器（几乎瞬间）
  2. 浏览器请求模块时，按需转换和返回
  3. 修改文件 → 只重新编译修改的模块 → HMR

// Vite 开发模式下，浏览器直接请求 ESM 模块
// http://localhost:3000/src/App.tsx → Vite 实时转换为浏览器可执行的 ESM
// import { ref } from 'vue' → 转换为 '/node_modules/vue/dist/vue.esm-bundler.js'

// Vite 的预构建（Pre-bundling）：
// 用 esbuild 把 CommonJS 的 node_modules 转为 ESM
// 解决了"裸模块导入"（bare import）的问题

src/
├── components/          # 通用组件
│   ├── Button/
│   │   ├── index.ts     # 导出入口
│   │   ├── Button.tsx   # 组件实现
│   │   └── Button.test.tsx
├── pages/               # 页面组件（路由级别代码分割）
│   ├── Dashboard/
│   └── Settings/
├── hooks/               # 自定义 Hooks
├── utils/               # 工具函数（纯函数，容易 Tree Shaking）
├── services/            # API 服务
├── stores/              # 状态管理
└── types/               # TypeScript 类型定义

// utils/index.ts — Barrel Export
export { debounce } from "./debounce";
export { throttle } from "./throttle";
export { formatDate } from "./formatDate";

// 使用时：一个 import 搞定
import { debounce, throttle } from "@/utils";

// ⚠️ 注意：Barrel Export 可能影响 Tree Shaking
// 如果 barrel 文件导出了大量模块，打包工具可能无法精确 Tree Shaking
// 解决方案：直接导入具体文件
import { debounce } from "@/utils/debounce";

// ❌ 直接导入其他模块的内部文件
import { helper } from "../utils/internal/helper";

// ✅ 通过模块的公共 API 导入
import { helper } from "../utils";

// 模块应该对外暴露稳定的公共 API，隐藏内部实现
// 这样内部重构不会影响其他模块

/**
 * Node.js require() 的核心逻辑（简化版，源自 lib/internal/modules/cjs/loader.js）
 * 完整流程：路径解析 → 缓存检查 → 原生模块检查 → 创建模块 → 编译执行 → 返回 exports
 */
Module._load = function (request, parent, isMain) {
  // 第 1 步：解析文件路径——将 './b' 转为绝对路径（如 /project/src/b.js）
  var filename = Module._resolveFilename(request, parent);

  // 第 2 步：检查模块缓存——同一个文件只执行一次，后续 require 直接返回缓存
  // 这就是为什么 CommonJS 模块是"单例"的
  var cachedModule = Module._cache[filename];
  if (cachedModule) {
    return cachedModule.exports;
  }

  // 第 3 步：检查是否为原生模块（如 fs、path、http 等）
  var NativeModule = require("internal/bootstrap/loaders");
  if (NativeModule.exists(filename)) {
    return NativeModule.require(filename);
  }

  // 第 4 步：创建新模块对象，存入缓存
  var module = new Module(filename, parent);
  Module._cache[filename] = module; // 先存缓存——这是处理循环依赖的关键

  // 第 5 步：根据文件扩展名选择加载方式（.js、.json、.node）
  tryModuleLoad(module, filename);

  // 第 6 步：返回 module.exports——此时模块代码已经执行完毕
  return module.exports;
};

/**
 * 编译模块代码：将源码包装在函数中并执行
 * 这就是 CommonJS 中 module、exports、require、__filename、__dirname 的来源
 * @param {string} content - 模块源码
 * @param {string} filename - 文件路径
 */
Module.prototype._compile = function (content, filename) {
  // Module.wrap 将源码包装在一个函数中，注入 5 个参数
  // 包装后的代码：(function(exports, require, module, __filename, __dirname) { <源码> })
  var wrapper = Module.wrap(content);
  // vm.runInThisContext 在当前 V8 上下文中编译并返回函数
  var compiledWrapper = vm.runInThisContext(wrapper);
  // 用 call 调用包装函数，传入 module.exports、require 等参数
  var result = compiledWrapper.call(
    this.exports,
    this.exports,
    require,
    this,
    filename,
    dirname,
  );
  return result;
};

/**
 * 浏览器原生 ESM 加载的三个阶段
 * 与 Node.js 的 CommonJS 不同，浏览器 ESM 是异步加载的
 */

// 阶段 1：构建（Construction）
// 浏览器解析 HTML 中的 <script type="module"> 标签
// 递归下载所有 import 依赖的模块文件（通过 HTTP 请求）
// 建立完整的模块依赖图（Module Graph）——只解析，不执行代码

// 阶段 2：实例化（Instantiation）
// 为每个模块分配内存空间（Module Record）
// 将 import 和 export 的变量"链接"起来（建立 live binding）
// 不执行任何代码，只是建立绑定关系——此时变量值为 undefined

// 阶段 3：求值（Evaluation）
// 按依赖图的拓扑排序顺序执行模块代码
// 此时变量才被赋值，获得实际值

// 浏览器加载 ESM 的方式：
<script type="module" src="./app.mjs"></script>
// type="module" 属性告诉浏览器：
// 1. 自动 defer（延迟执行，不阻塞 HTML 解析——与普通 script 的阻塞行为不同）
// 2. 自动 strict mode（ESM 强制严格模式，不用写 'use strict'）
// 3. 每个模块有自己的作用域（不像普通 script 共享全局作用域）
// 4. 支持 import/export 语法

ES Modules 的三阶段加载模型：

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   构建        │ → │   实例化      │ → │   求值        │
│ Construction  │   │ Instantiation│   │ Evaluation   │
│               │   │              │   │              │
│ 解析 import   │   │ 分配内存空间  │   │ 执行模块代码  │
│ 递归下载依赖  │   │ 建立绑定关系  │   │ 变量获得值    │
│ 不执行代码    │   │ 不执行代码    │   │              │
└──────────────┘   └──────────────┘   └──────────────┘

/**
 * 阶段 1：构建（Construction）
 * 引擎从入口文件开始，递归解析所有 import 语句，构建模块依赖图
 * 这个阶段只做静态分析，不执行任何代码——这就是 ES Modules 能做 Tree Shaking 的原因
 */

// main.mjs — 入口文件
import { count } from "./counter.mjs"; // 引擎在此发现依赖 counter.mjs
import { debounce } from "./utils.mjs"; // 引擎在此发现依赖 utils.mjs

// counter.mjs — 被依赖的模块
export let count = 0; // export 声明被引擎在构建阶段记录
export function increment() {
  count++;
}

// 构建阶段完成后的依赖图（Module Graph）：
// main.mjs → [counter.mjs, utils.mjs]   main 依赖两个模块
// counter.mjs → []                       counter 无依赖
// utils.mjs → []                         utils 无依赖
// 注意：此时变量 count 的值还没有被赋值，代码还没有执行

/**
 * 阶段 2：实例化（Instantiation）
 * 为每个 export 变量分配内存空间，建立 import/export 之间的 live binding
 * 此阶段不执行代码，变量值为 undefined，但绑定关系已建立
 */

// 实例化后的内存布局：
// counter.mjs 的 export count ←→ main.mjs 的 import count（指向同一块内存）
// 即使 count 还没被赋值（值为 undefined），绑定关系已经建立
// 当 count 在求值阶段被赋值为 0 时，main.mjs 通过 live binding 自动看到 0
// 这就是 ESM 和 CommonJS 的本质区别：ESM 是引用绑定，CommonJS 是值拷贝

/**
 * 阶段 3：求值（Evaluation）
 * 按依赖顺序（拓扑排序）执行模块代码，变量在此时获得实际值
 * 由于 live binding 已在实例化阶段建立，模块间可以实时看到彼此的最新值
 */

// 求值顺序（按依赖图的拓扑排序）：
// 1. counter.mjs 先执行：count 被赋值为 0，increment 被赋值为函数
// 2. main.mjs 后执行：通过 live binding 拿到 count = 0

// live binding 的威力：
// counter.mjs 中执行 increment() 后，count 变为 1
// main.mjs 中读取 count 会得到 1——因为 import 拿到的是引用，不是值的拷贝
// 如果是 CommonJS，main.js 中的 count 永远是 0（值在 require 时就固定了）

/**
 * Live Binding vs 值拷贝：ESM 与 CommonJS 最本质的区别
 * ESM 的 export 是活绑定——import 拿到的是变量的引用，模块内部修改后 import 方能看到最新值
 * CommonJS 的 require 是值拷贝——require 时执行模块代码，返回 exports 的浅拷贝
 */

// === ESM 的 live binding（活绑定）===
// counter.mjs
export let count = 0; // export 导出的是变量的绑定，不是值
export function increment() {
  count++;
} // 内部修改 count，外部通过 live binding 自动感知

// main.mjs
import { count, increment } from "./counter.mjs";
console.log(count); // 0                  // 初始值
increment(); // 调用 increment，count 在 counter.mjs 内部变为 1
console.log(count); // 1                  // 通过 live binding 拿到最新值！

// === CommonJS 的值拷贝 ===
// counter.js
let count = 0;
function increment() {
  count++;
}
module.exports = { count, increment }; // 导出时 count 的值 0 被拷贝到 exports 对象

// main.js
const { count, increment } = require("./counter");
console.log(count); // 0                  // require 时拿到的是值的拷贝
increment(); // 调用 increment，counter.js 内部的 count 变为 1
console.log(count); // 0                  // 但 main.js 中的 count 仍然是拷贝时的值 0

// 编译时就能知道：debounce 被 import 了，throttle 没有
import { debounce } from "./utils.mjs";

// utils.mjs
export const debounce = (fn, ms) => {
  /* ... */
};
export const throttle = (fn, ms) => {
  /* ... */
};
// throttle 没有被任何模块 import → 打包时删除