---
title: JavaScript-06-模块化与工程化
aliases:
  - JavaScript 模块化
  - CommonJS 与 ES Module
  - npm 与包管理
  - JavaScript Modules and Tooling
tags:
  - 编程语言/JavaScript
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[JavaScript-01-基础语法与类型]]"
  - "[[JavaScript-02-函数与作用域]]"
sources:
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Modules
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/export
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Operators/import
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import.meta
  - https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import/with
  - https://developer.mozilla.org/zh-CN/docs/Web/HTML/Reference/Elements/script/type/importmap
  - https://nodejs.org/docs/latest/api/modules.html
  - https://nodejs.org/docs/latest/api/esm.html
  - https://nodejs.org/docs/latest/api/packages.html
  - https://docs.npmjs.com/cli/v10/configuring-npm/package-json
  - https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json
  - https://docs.npmjs.com/cli/v10/commands/npm-ci
  - https://docs.npmjs.com/cli/v10/commands/npx
  - https://docs.npmjs.com/cli/v10/using-npm/scripts
  - https://docs.npmjs.com/about-semantic-versioning
  - https://semver.org/lang/zh-CN/
  - https://pnpm.io/zh/motivation
  - https://pnpm.io/zh/symlinked-node-modules-structure
  - https://yarnpkg.com/getting-started
  - https://zh.javascript.info/modules-intro
  - https://zh.javascript.info/modules
  - https://zh.javascript.info/modules-dynamic-imports
  - https://tc39.es/ecma262/
  - https://vitejs.dev/guide/why
  - https://webpack.js.org/concepts/
---

# JavaScript-06-模块化与工程化

> [!abstract] 本篇讲什么
> JavaScript 最初是"往网页里塞几十行脚本"的语言，**没有模块系统**。当项目代码涨到几万行、依赖几十个第三方库时，"文件怎么组织、变量怎么隔离、依赖怎么装、代码怎么送到浏览器"就变成了一门专门的学问，也就是**模块化（Modularization）**与**工程化（Engineering）**。
> 本篇回答五个问题：
> ① 没有模块系统时会出什么问题？前人是怎样用**命名空间**和 **IIFE**（Immediately Invoked Function Expression，立即调用函数表达式）硬扛的？
> ② **CommonJS**（CJS，Node 的传统模块规范）的 `require` / `module.exports` / `exports` 到底是什么关系，缓存与循环依赖怎么表现？
> ③ **ES Module**（ESM，语言标准模块规范）为什么能做**静态分析**与 **tree-shaking**？**动态绑定（live binding）**和 CommonJS 的"值拷贝"差在哪？
> ④ **npm** 与包管理：`package.json` 的每个字段意味着什么，语义化版本 `^` / `~` 的取值范围到底是什么，`package-lock.json` 为什么必须提交？
> ⑤ **打包（bundling）**：为什么浏览器不能直接跑 `node_modules` 里的包，打包器究竟做了什么？
> 读完你应该能：为一个新项目选对模块规范、看懂 `exports` 条件导出、解释"为什么改了这个包却安装失败"、判断某个依赖什么时候会进产物。

---

## 一、是什么：从"一个文件"到"一张依赖图"

**模块（Module）**是一个独立的代码单元，它同时满足四个条件：

1. **有自己的作用域**：模块内声明的变量不会泄漏到外部；
2. **显式导出**：只有明确写出的东西才能被外部拿到；
3. **显式导入**：用到什么就写什么，依赖关系可读；
4. **单例缓存**：同一个模块无论被导入多少次，只执行一次，共享同一份实例。

JavaScript 的模块化史可以分成三段：

| 阶段 | 时间 | 代表做法 | 解决的问题 | 留下的问题 |
|---|---|---|---|---|
| 无模块 | 1995–2009 | 多个 `<script>` 顺序拼接 | 无 | 全局污染、顺序脆弱、命名冲突 |
| 社区方案 | 2009–2015 | 命名空间对象、IIFE、AMD、CommonJS | 作用域隔离、依赖声明 | 各方案互不兼容，浏览器里要额外加载器 |
| 语言标准 | 2015 至今 | **ES Module**（ES2015 起） | 语法级模块、静态可分析 | 生态迁移期需要处理 CJS/ESM 互操作 |

> [!important] 一句话抓住本质
> **模块系统要解决的核心矛盾是："我需要复用小颗粒的代码，但我不想让这些小颗粒互相污染。"**
> 所有模块方案都是同一件事的三种实现：**用一个函数作用域把代码包起来**（隔离）＋ **通过一个约定好的出口传值**（接口）＋ **记录谁引用了谁**（依赖图）。

---

## 二、为什么这样设计：历史问题与设计取舍

### 2.1 没有模块系统的三个真实事故

**事故一：全局污染。** 三个文件都写 `var count = 0`，最后一个把前两个覆盖掉，而 JS 不会报错。

**事故二：依赖顺序脆弱。** 只要 `<script>` 标签顺序调换，`undefined is not a function` 就出现了；文件多了以后顺序变成口头约定，无法自动校验。

**事故三：命名冲突。** 两个库都叫 `utils.format`，只能靠人工加前缀（`myLibFormat`），可读性急剧下降。

### 2.2 设计取舍表

| 设计决策 | 动机 | 代价 |
|---|---|---|
| 用**函数作用域**做隔离（IIFE） | 2009 年只有 `var`，函数是唯一能造作用域的东西 | 每个模块要写一层包装，样板代码多 |
| CommonJS 用**同步 `require`** | 服务端从磁盘读文件很快，同步写法最简单直观 | 浏览器里同步读网络文件会卡死主线程，必须靠打包器 |
| CommonJS **运行时求值** | 可以 `require(变量名)`、可以写在 `if` 里，灵活 | 打包器无法在编译期确定依赖，只能把可能用到的都打进去 |
| ESM 设计成**静态结构** | 编译期就能画出依赖图，支持 tree-shaking、预加载、循环依赖处理 | 不能在 `if` 里写 `import`，路径必须是字符串字面量 |
| ESM 导出**动态绑定（live binding）** | 导出的是"变量的视图"而不是快照，模块间状态能自然同步 | 初学者按"值拷贝"的心智模型理解会出错 |
| Node 同时支持 CJS 与 ESM | 不能一夜之间让百万个包改语法，必须平滑迁移 | 出现双包（dual package）、`require(esm)`、互操作差异等一堆历史包袱 |
| `node_modules` 嵌套/扁平化 | 每个包自带依赖，能解决版本冲突 | 目录极深、磁盘浪费、**幽灵依赖（phantom dependency）** |

> [!note] 为什么浏览器方案（AMD/CMD）输了
> 2010 年前后浏览器端流行 **AMD**（Asynchronous Module Definition，代表实现 RequireJS）和 **CMD**（代表实现 SeaJS）。它们用 `define([...], function(){})` 把依赖写成数组，运行时异步加载。缺点是要额外引入加载器、语法不是语言的一部分、而且无法做静态分析。ESM 一进标准，这两套就基本退出了历史舞台——**能被语言原生支持的方案，最终会赢过库方案。**

---

## 三、核心内容

### 3.1 史前时代：全局函数 → 命名空间 → IIFE

```js
// 运行环境：任意浏览器控制台或 Node（语法与 DOM 无关部分通用）
// ① 全局函数时代：所有东西挂在 window 上，靠前缀区分
function shopFormatPrice(n) { return '¥' + n.toFixed(2); }
function cartFormatPrice(n) { return '$' + n.toFixed(2); }   // 只好加前缀

// ② 命名空间对象：把相关的函数收进一个对象，减少全局名字数量
var Shop = {
  formatPrice(n) { return '¥' + n.toFixed(2); },
  items: [],
};
// 问题：对象内部没有任何隐私，Shop.items 可以被任何人改写

// ③ IIFE 模块模式：用函数作用域做真正的隔离
var Cart = (function () {
  var items = [];                       // 私有：外部拿不到这个变量
  function formatPrice(n) { return '¥' + n.toFixed(2); }
  return {                              // 只暴露想暴露的
    add(name, price) { items.push({ name, price }); return this; },
    total() { return items.reduce((s, i) => s + i.price, 0); },
    report() { return items.map(i => `${i.name}: ${formatPrice(i.price)}`); },
  };
})();

Cart.add('键盘', 399).add('鼠标', 99);
console.log(Cart.total());     // 498
console.log(Cart.report());    // ['键盘: ¥399.00', '鼠标: ¥99.00']
console.log(typeof items);     // 'undefined' —— 私有变量确实拿不到
```

IIFE 把"模块"的四个条件里的前三个都实现了，唯独**依赖顺序**仍然靠人工：`Cart` 如果依赖 `Shop`，你必须保证 `Shop` 的 `<script>` 在前面。这正是 CommonJS 要解决的问题——**让模块自己声明依赖**。

### 3.2 CommonJS：Node 的第一套模块系统

CommonJS 的核心只有三个东西：

```js
// 运行环境：Node.js（CJS，文件后缀 .cjs 或在无 "type": "module" 的包里用 .js）
const dep = require('./dep.cjs');   // 同步引入，返回对方的 module.exports
module.exports = { foo: 1 };        // 定义本模块的出口
exports.bar = 2;                    // exports 是 module.exports 的初始别名
```

#### 3.2.1 `require` / `module.exports` / `exports` 的关系

Node 在执行一个 CJS 文件前，会把它**包进一个函数**（官方称 module wrapper）：

```js
// Node 官方文档给出的模块包装函数（示意，不是你要写的代码）
(function (exports, require, module, __filename, __dirname) {
  // 你写的模块代码原封不动地放在这里
});
```

于是：

- `module` 是当前模块的对象，`module.exports` 才是真正的出口；
- `exports` 只是进入函数时 `exports = module.exports` 得到的**局部变量**，一个指向同一对象的别名；
- `require` 是包装函数传入的参数，不是全局变量（在 ESM 里更是不存在）。

> [!warning] CommonJS 第一大坑：给 `exports` 重新赋值
> ```js
> // 运行环境：Node.js（CJS），实测于 v24.18.0
> exports.a = 1;
> exports = { b: 2 };          // ❌ 只是让局部变量指向了新对象
> module.exports.c = 3;
> // 别的模块 require 到的是：{ a: 1, c: 3 }
> ```
> **规则：想替换整个出口，只能写 `module.exports = {...}`；`exports.xxx = ...` 只能用于挂属性。**

#### 3.2.2 同步加载与缓存机制

`require` 的语义是：**解析路径 → 查缓存 → 命中则返回，未命中则读取并执行整个文件 → 缓存 `module.exports` → 返回**。

```js
// 运行环境：Node.js（CJS），实测于 v24.18.0
// counter.cjs
let count = 0;
module.exports = { count, inc() { count++; return count; } };

// main.cjs
const c = require('./counter.cjs');
const { count } = require('./counter.cjs');
console.log(c.count, count);    // 0 0  —— 导出的是当时的"值"
c.inc(); c.inc();
console.log(c.count, count);    // 0 0  —— 模块内部的 count 变了，导出对象不会跟着变
console.log(require('./counter.cjs') === c);   // true —— 同一实例（缓存）
delete require.cache[require.resolve('./counter.cjs')];
console.log(require('./counter.cjs') === c);   // false —— 删了缓存才会重新执行
```

> [!important] "值的拷贝"要理解准确
> CommonJS 导出的是一个**对象引用**。所以 `module.exports.count++` 这种**改属性**的操作，导入方是能看到的；看不到的是"模块内部用 `let` 变量重新赋值"这件事——因为 `{ count }` 在导出那一刻就把值抄下来了。
> 一句话：**CJS 导出的是"快照 + 共享对象"，不是指向模块内部变量的绑定。**

#### 3.2.3 循环依赖：拿到"半成品"

假设 `a.cjs` 与 `b.cjs` 互相 require，Node 的处理方式是：**执行到一半的模块，其 `module.exports` 也会被放进缓存**，于是对方拿到的是"半成品"。

```js
// 运行环境：Node.js（CJS），实测于 v24.18.0
// a.cjs
exports.ready = false;
const b = require('./b.cjs');     // 进入 b，此时 a 只执行了第一行
exports.ready = true;
console.log('a 里看到的 b.done =', b.done);

// b.cjs
const a = require('./a.cjs');     // 命中缓存，拿到未完成的 a
console.log('b 里看到的 a.ready =', a.ready);
exports.done = true;

// 执行 node a.cjs 输出：
// b 里看到的 a.ready = false
// a 里看到的 b.done = true
```

结论：**CJS 的循环依赖不会死循环，但会读到 `undefined` 或旧值**，属于"能跑但随时可能炸"的代码。真正可靠的解法是**重构掉环**（把共享部分抽成第三个模块），而不是靠调整 require 位置碰运气。循环依赖在依赖图 $G=(V,E)$ 上就是一条有向环 $v_1 \to v_2 \to \cdots \to v_k \to v_1$，工程上通常用 `madge` 之类工具做环检测。

#### 3.2.4 常用 API 速查

| API | 作用 | 备注 |
|---|---|---|
| `require(id)` | 加载模块 | `id` 可以是相对路径、绝对路径、包名 |
| `require.resolve(id)` | 只解析出绝对路径，不执行 | 常用于拿到缓存键 |
| `require.cache` | 模块缓存表 | 键是解析后的绝对路径；工程代码里**不要**随意删除 |
| `require.main === module` | 判断当前文件是否是入口 | 老式"直接运行则执行"写法 |
| `module.exports` / `exports` | 出口 | 见上文陷阱 |
| `__filename` / `__dirname` | 当前文件/目录的绝对路径 | ESM 中不存在，要用 `import.meta.url` 换算 |

### 3.3 ES Module：语言级的模块系统

ESM 的语法只有两条：`export` 导出、`import` 导入。

```js
// 运行环境：Node.js 18+（文件后缀 .mjs，或 package.json 里 "type": "module"），实测于 v24.18.0
// lib.mjs
export const PI = 3.14159;            // 具名导出（named export）
export function area(r) { return PI * r * r; }
export default function hello() { return 'hello'; }   // 默认导出（default export）

// use.mjs
import hello, { PI, area } from './lib.mjs';          // 默认导出与具名导出可同时导入
import * as lib from './lib.mjs';                     // 命名空间导入
console.log(hello(), PI, area(1));
```

#### 3.3.1 默认导出与具名导出的区别

| 对比项 | 默认导出 `export default x` | 具名导出 `export { x }` |
|---|---|---|
| 本质 | 一个名为 `default` 的特殊具名导出 | 普通具名导出 |
| 导入时名字 | **可以任意取名**：`import whatever from ...` | 必须用原名，或用 `as` 重命名 |
| 数量 | 每个模块最多一个 | 不限 |
| 语法 | `export default function () {}` 可匿名 | 必须有名（声明或 `as`） |
| 重新导出 | `export { default } from './x.mjs'` | `export { y } from './x.mjs'` |
| 静态分析友好度 | 较差：改名让工具难以追踪 | **好**：名字稳定，利于 tree-shaking 与 IDE 跳转 |
| 工程建议 | 只用于"这个模块就是这一个东西"（如一个 Vue 组件文件） | 库的公共 API 优先用具名导出 |

> [!tip] 为什么很多规范建议"库不要用默认导出"
> 默认导出允许导入方随便改名，一个 `import a from 'x'` 和另一个文件里的 `import b from 'x'` 可能指的是同一个东西，重命名重构、自动导入、tree-shaking 都更难做。**对外发布的库优先具名导出**；默认导出留给"单文件单组件"这类场景。

#### 3.3.2 静态分析、tree-shaking 与前提条件

ESM 的 `import` / `export` 是**语法结构**而不是函数调用，所以在**不执行代码**的前提下就能画出完整的依赖图。这就是静态分析（static analysis）能力的来源，也是 **tree-shaking**（摇树优化，即删掉未被使用的导出）的前提。

tree-shaking 生效需要四个条件：

1. 代码是 **ESM**（`import`/`export`），CJS 的动态 `require` 无法安全删除；
2. 打包器开启了 **production / 压缩**流程（开发模式下通常不摇）；
3. 模块**没有副作用**，或通过 `package.json` 的 `"sideEffects": false` 明确声明；
4. 导出确实**没有被引用**，且没有被 `export *` 之类的动态再导出搞乱。

> [!warning] 副作用是 tree-shaking 的最大杀手
> ```js
> // polyfill.js —— 这个模块"导出"是空的，但 import 它本身就有意义
> import 'core-js/stable';           // 执行时会往全局补 API
> ```
> 打包器无法证明它无害，只能保留。这正是 `"sideEffects": false` 存在的意义：**用声明换取更小的产物**——但声明错了会真的删掉必要的代码，必须谨慎。

#### 3.3.3 动态绑定（live binding）

ESM 的导出不是"值"，而是"**指向变量的绑定**"。导入方看到的是实时的值。

```js
// 运行环境：Node.js 18+（ESM），实测于 v24.18.0
// lib.mjs
export let n = 0;
export function inc() { n++; }

// use.mjs
import { n, inc } from './lib.mjs';
console.log(n);   // 0
inc();
console.log(n);   // 1  —— 不是拷贝，是绑定！

// 反过来：导入的绑定是只读的
// n = 5;         // TypeError: Assignment to constant variable.（实测于 Node v24.18.0）
```

> [!important] CJS 与 ESM 最关键的心智差异
> - **CommonJS**：`require` 返回**一个对象**，对象里的属性是导出那一刻的快照。
> - **ES Module**：`import` 拿到的是**指向源模块变量的只读绑定**，源模块改变量，导入方立刻看到新值。
> 所以"ESM 导出的是引用，CJS 导出的是值"这句话方向是对的，但更精确的说法是：**ESM 导出绑定（binding），CJS 导出对象（object）。**

#### 3.3.4 顶层 await、`import.meta` 与 JSON 导入

```js
// 运行环境：Node.js 18+（ESM 顶层 await 可用），实测于 v24.18.0
import { readFile } from 'node:fs/promises';

// 顶层 await：模块自己的求值可以等待异步结果，导入它的模块会自动等它完成
const config = JSON.parse(await readFile(new URL('./config.json', import.meta.url), 'utf8'));

// import.meta：ESM 里替代 __filename / __dirname 的官方方案
console.log(import.meta.url);        // file:///.../config-user.mjs
console.log(import.meta.dirname);    // Node 20.11+ / 21.2+ 提供，浏览器中为 undefined
console.log(config.name);
```

```js
// 运行环境：Node.js 20.10+ / 22+ 支持 import attributes（以官方最新文档为准）
import pkg from 'demo-pkg/package.json' with { type: 'json' };   // 声明式 JSON 导入
console.log(pkg.version);
```

| 方案 | 语法 | 特点 |
|---|---|---|
| 顶层 `await` | `const x = await fetch(...)` | 仅在 ESM 顶层可用，模块图会串行等待 |
| `import.meta.url` | `import.meta.url` | 当前模块的 `file://` URL，配合 `new URL()` 拼路径 |
| `import.meta.dirname` | `import.meta.dirname` | Node 20.11+ 起提供，最接近 `__dirname` |
| import attributes | `with { type: 'json' }` | 让宿主知道该按什么类型解析，避免把 JSON 当 JS 执行 |
| `createRequire` | `import { createRequire } from 'node:module'` | 在 ESM 里获得一个 `require`，用于加载 CJS 包 |

#### 3.3.5 动态 `import()` 与代码分割

`import()` 是**函数调用式**的导入，返回 Promise，可以写在任何位置、可以用变量拼路径。

```js
// 运行环境：Node.js 18+ 或现代浏览器（<script type="module"> 内）
// 场景：只有用户点了"导出报表"才加载体积很大的报表库
async function exportReport(rows) {
  const { buildXlsx } = await import('./heavy-xlsx-lib.mjs');   // 真正需要时才下载/求值
  return buildXlsx(rows);
}

// 动态导入同一模块仍然命中缓存（实测于 Node v24.18.0）
const a = await import('./lib.mjs');
const b = await import('./lib.mjs');
console.log(a === b);   // true

// 打包器看到 import() 会把它作为一个"分割点"，产出独立 chunk，这就是代码分割
const page = await import(`./pages/${route}.mjs`);   // ⚠️ 变量拼接会让打包器把整个目录都打进去
```

> [!warning] `import()` 与 `import` 不是一回事
> `import x from 'm'` 是**声明**，只能写在模块顶层，会被提升到模块求值之前；`import('m')` 是**表达式**，位置自由、返回 Promise。前者参与静态依赖图，后者产生运行时请求与代码分割点。

### 3.4 两套规范对比

| 对比项 | CommonJS（CJS） | ES Module（ESM） |
|---|---|---|
| 出现时间 / 定位 | 2009，社区规范，Node 实现 | 2015（ES2015），语言标准 |
| 语法 | `require` / `module.exports` | `import` / `export` |
| 加载时机 | **运行时**同步加载并执行 | **解析期**确定依赖，**求值时**执行 |
| 是否静态可分析 | 否（`require` 可带变量、可在分支里） | **是**（路径必须是字符串字面量） |
| 导出内容 | 对象（值快照） | 绑定（live binding，只读） |
| 导入的绑定能否赋值 | 可以（改的是对象的属性） | 不可以，`TypeError` |
| `this` 指向 | `module.exports`（顶层 `this`） | **`undefined`**（模块顶层） |
| 严格模式 | 默认宽松，需 `'use strict'` | **始终严格** |
| 循环依赖 | 返回"半成品"，可能读到 `undefined` | 提升的函数可用；`const`/`let` 未初始化时抛 TDZ 错误 |
| 顶层 await | 不支持 | 支持 |
| 浏览器直接使用 | 不支持 | `<script type="module">` 原生支持 |
| tree-shaking | 很难 | 支持 |
| Node 中的标识 | `.cjs`，或无 `type` 字段包里的 `.js` | `.mjs`，或 `"type": "module"` 包里的 `.js` |

#### 3.4.1 Node 里到底按哪种规范解析？

判断优先级（Node 官方规则，实测于 v24.18.0）：

| 文件名 / 配置 | 解析为 | 说明 |
|---|---|---|
| `x.mjs` | ESM | 后缀优先，永远 ESM |
| `x.cjs` | CJS | 后缀优先，永远 CJS |
| `x.js`，最近的 `package.json` 有 `"type": "module"` | ESM | 整个包作用域内生效 |
| `x.js`，最近的 `package.json` 有 `"type": "commonjs"` 或无 `type` | CJS（有例外，见下） | 默认是 CJS |
| `x.js`，无 `type` 字段，但文件里写了 `import`/`export` | **ESM** | 新版本 Node 默认开启"模块语法检测"，自动按 ESM 运行 |
| `node -e "..."` | 由 `--input-type=module` / `commonjs` 指定 | 无后缀可依据，只能靠参数 |

```bash
# 运行环境：Node.js 18+（实测 v24.18.0）；bash / PowerShell 均可
node --version
node main.mjs            # 按 ESM 跑
node main.cjs            # 按 CJS 跑
node --input-type=module -e "import('node:os').then(os => console.log(os.platform()))"
```

> [!warning] 语法检测会掩盖配置错误
> 一个忘了写 `"type": "module"` 的包，因为文件里有 `export`，在新版 Node 上"碰巧能跑"；一旦换到旧版本 Node 或加上 `--no-experimental-detect-module`，立刻报 `SyntaxError: Unexpected token 'export'`。**永远显式声明 `type` 字段或用明确的 `.mjs` / `.cjs` 后缀**，不要依赖自动检测。相关行为仍在演进，以 Node 官方文档为准。

#### 3.4.2 混合使用：互操作的两条规则

```js
// 运行环境：Node.js 18+，实测于 v24.18.0
// ① ESM 里导入 CJS：default 就是 module.exports
const m = await import('./cjs-named.cjs');
console.log(Object.keys(m));      // [ 'default', 'extra', 'module.exports', 'named' ]
console.log(m.default.named);     // 1 —— default 指向整个 module.exports
// 打包器/Node 会用静态分析（cjs-module-lexer）尽量还原具名导出，但不是 100% 可靠

// ② CJS 里加载 ESM：新版本 Node 已支持（require(esm)）
const esm = require('./lib.mjs');
console.log(typeof esm.default, esm.n);   // 'function' 0
```

> [!warning] 互操作三大坑
> 1. **`import x from 'cjs-pkg'` 拿到的往往是整个 `module.exports`**，而具名导入 `import { foo }` 依赖静态分析，遇到 `exports[动态名]` 就会失败。
> 2. **双包陷阱（dual package hazard）**：同一个库同时提供 CJS 与 ESM 入口，如果两种入口都被加载，会得到**两份不同的模块实例**（各自的模块级状态、各自的 `instanceof`），出现"明明同一个类却 `instanceof` 为 false"的怪事。
> 3. **CJS 里没有 `__dirname` 以外的 ESM 特性**，ESM 里没有 `require` / `__dirname` / `module`（实测三者 `typeof` 均为 `'undefined'`）。

### 3.5 浏览器中的 `<script type="module">`

```html
<!-- 运行环境：现代浏览器，需通过 http(s) 提供（本地要起静态服务器） -->
<script type="module" src="./main.mjs"></script>
<script type="module">
  // 内联模块：同样拥有模块作用域，也可以 import
  import { init } from './app.mjs';
  init();
</script>
<script nomodule src="./legacy-bundle.js"></script>  <!-- 老浏览器回退 -->
```

| 行为 | 普通 `<script>` | `<script type="module">` |
|---|---|---|
| 解析阻塞 | 默认阻塞 HTML 解析 | **默认 defer**（下载不阻塞，DOM 解析完后按顺序执行） |
| 作用域 | 全局（顶层变量挂到 `window`） | **模块作用域**，不污染全局 |
| 严格模式 | 默认非严格 | **始终严格** |
| 执行次数 | 每个标签各执行一次 | 同一个 URL **只执行一次** |
| 跨域脚本 | 允许（无 CORS 要求） | **必须带 CORS 响应头**，否则被拦 |
| `file://` 直接打开 | 可用 | **不可用**（CORS 报错），必须起本地服务器 |
| 顶层 `await` | 不适用 | 支持 |
| 异步属性 | `async` / `defer` 可选 | 默认即 defer；加 `async` 可打乱顺序提前执行 |
| 裸模块名 `import 'vue'` | — | **不允许**，必须是相对路径或完整 URL |

> [!tip] 浏览器里想用包名怎么办
> 用 **import map**（导入映射，`<script type="importmap">`）把裸标识符映射到真实 URL：
> ```html
> <script type="importmap">
> { "imports": { "vue": "https://cdn.example.com/vue@3/dist/vue.esm-browser.prod.js" } }
> </script>
> ```
> 但生产环境的主流做法仍然是**打包**：把裸模块名在构建期就解析成真实文件，见 3.7 节。

### 3.6 npm 与包管理

**npm**（Node Package Manager）随 Node 一起安装，是世界上最大的包仓库；`package.json` 是项目的**清单文件**。

#### 3.6.1 `package.json` 关键字段逐项解释

```jsonc
{
  "name": "my-app",                  // 包名，发布到 npm 时全局唯一；私有项目也建议写
  "version": "1.2.3",                // 版本号，语义化版本（SemVer）
  "private": true,                   // 防止手滑 npm publish 把内部项目发出去
  "description": "示例项目",
  "type": "module",                  // 决定本包作用域内 .js 按 ESM 还是 CJS 解析
  "main": "./dist/index.cjs",        // 入口（老字段，主要给 CJS require 用）
  "module": "./dist/index.mjs",      // 打包器友好的 ESM 入口（社区约定，非 Node 官方标准）
  "exports": {                       // 现代入口声明，优先级高于 main/module
    ".": {
      "import": "./dist/index.mjs",  // ESM 导入时命中
      "require": "./dist/index.cjs", // CJS require 时命中
      "default": "./dist/index.mjs"  // 兜底，必须放最后
    },
    "./math": "./dist/math.mjs",     // 子路径导出：允许 import 'my-app/math'
    "./package.json": "./package.json"
  },
  "browser": "./dist/browser.mjs",   // 打包器在浏览器环境下替换入口（社区约定）
  "sideEffects": false,              // 告诉打包器"本包无副作用"，可放心 tree-shaking
  "files": ["dist"],                 // 发布时要包含的文件白名单
  "engines": { "node": ">=18" },     // 声明运行环境要求
  "scripts": {                       // npm run 的任务
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run"
  },
  "dependencies": { "vue": "^3.4.0" },
  "devDependencies": { "vite": "^5.0.0" },
  "peerDependencies": { "react": ">=18" }
}
```

| 字段 | 作用 | 常见误区 |
|---|---|---|
| `main` | 传统入口 | 在新包里应该被 `exports` 取代；只为兼容老工具而保留 |
| `module` | ESM 入口（打包器识别） | **不是 Node 标准字段**，Node 自己不读它 |
| `exports` | 官方入口声明，支持条件与子路径 | 一旦写了 `exports`，**未列出的子路径就不可访问**，会报 `ERR_PACKAGE_PATH_NOT_EXPORTED` |
| `type` | `module` / `commonjs`，决定 `.js` 的解析方式 | 漏写会导致 ESM 代码在新旧 Node 上表现不一致 |
| `scripts` | 可执行任务，`npm run <name>` 调用 | `pre`/`post` 前缀会自动串联；`prepare` 在 `npm install` 后自动跑 |
| `dependencies` | **运行时**需要，用户安装你的包时会一起装 | 把构建工具写进这里，会让使用者的依赖树变胖 |
| `devDependencies` | 只在本仓库开发/构建/测试时需要 | 应用项目的构建工具、类型定义放这里 |
| `peerDependencies` | 声明"我要求宿主提供某个包" | 插件类库必须用，否则会出现两份 React |
| `files` | 发布白名单 | 不写会把源码、测试、配置全部发到 npm |

#### 3.6.2 语义化版本与 `^` / `~`

版本号是三元组 $\langle \text{major},\ \text{minor},\ \text{patch} \rangle$，含义是**承诺**：

- **major**：不兼容的破坏性变更；
- **minor**：向后兼容地新增功能；
- **patch**：向后兼容地修 bug。

范围符号与之对应（下表中 `[a, b)` 表示左闭右开区间，即含 $a$ 不含 $b$）：

| 写法 | 等价区间 | 含义 | 何时自动升级 |
|---|---|---|---|
| `1.2.3` | $[1.2.3,\ 1.2.3]$ | 精确锁定 | 不会 |
| `^1.2.3` | $[1.2.3,\ 2.0.0)$ | 允许 minor 与 patch 升级 | `npm update` 时 |
| `^0.2.3` | $[0.2.3,\ 0.3.0)$ | **0.x 视为不稳定**：只允许 patch 升级 | `npm update` 时 |
| `^0.0.3` | $[0.0.3,\ 0.0.4)$ | 只允许 patch 且 minor 为 0 时更严格 | `npm update` 时 |
| `~1.2.3` | $[1.2.3,\ 1.3.0)$ | 只允许 patch 升级 | `npm update` 时 |
| `1.2.x` | $[1.2.0,\ 1.3.0)$ | 同上，另一种写法 | `npm update` 时 |
| `>=1.2.3 <2` | 组合范围 | 显式区间 | 视范围而定 |
| `*` / `latest` | 任意版本 | 危险 | 随时 |

> [!important] 三条必须记住的规则
> 1. **`^` 遇到 `0.x` 会"降级"成 `~` 的效果**：`^0.2.3` 不允许升到 `0.3.0`。因为 SemVer 规定 0.x 阶段任何 minor 都可能破坏兼容。
> 2. **预发布版本不会被普通范围命中**：`1.5.0-beta.1` 不在 `^1.2.3` 的区间里，除非范围里显式写了预发布标识。
> 3. `npm install`（不带参数）**不会**把已安装的包升到范围内的最新版——它严格按锁文件装；要升级得显式 `npm update <pkg>`。

#### 3.6.3 `package-lock.json` 为什么必须提交

`package.json` 里的 `^1.2.3` 只描述了一个**区间**，而 `package-lock.json` 记录的是**这次真正装出来的那棵完整的树**：每个包的确切版本、下载地址（`resolved`）与完整性校验（`integrity`）。

必须提交的四个理由：

1. **可复现**：今天装出 `1.4.2`，三个月后同事装出来也是 `1.4.2`，而不是 `1.6.0`。CI 与生产环境尤其关键。
2. **安全与校验**：`integrity` 字段能发现被篡改或损坏的包。
3. **加速**：安装时不必反复向 registry 询问版本元数据。
4. **`npm ci` 依赖它**：CI 里用 `npm ci` 才能得到"完全按锁文件、干净安装"的结果。

```bash
# 运行环境：Node.js + npm（任意版本，行为以官方文档为准）
npm install            # 按 package.json 装依赖，并更新 lock
npm ci                 # 严格按 lock 安装（不会修改 lock），CI 专用，要求 lock 与 package.json 一致
npm install vue@^3.4   # 装指定范围并写回 package.json
npm ls vue             # 看实际装了哪个版本、被谁依赖
npm outdated           # 看哪些依赖落后于范围允许的最新版
```

> [!warning] 关于 lock 文件的三个错误做法
> - **把它加进 `.gitignore`**：等于放弃可复现性，是新手最常犯的错。
> - **手动编辑它**：格式复杂且带校验和，冲突时应删除后重新 `npm install` 生成。
> - **提交了却用 `npm install` 跑 CI**：`npm install` 会在必要时改写 lock；CI 应当用 `npm ci`。

#### 3.6.4 npm / yarn / pnpm 对比

| 对比项 | npm | Yarn（Classic / Berry） | pnpm |
|---|---|---|---|
| 出品方 | npm, Inc.（现属 GitHub） | Meta | 社区（pnpm.io） |
| `node_modules` 结构 | v3+ 扁平化（hoist） | Classic 扁平化；Berry 默认 PnP（无 node_modules） | **符号链接 + 内容寻址存储**，非扁平 |
| 磁盘占用 | 每个项目各存一份 | 同 npm | 全局一份存储，**硬链接**到各项目，最省 |
| 幽灵依赖 | **存在**（可 require 未声明的包） | Classic 存在 | **默认隔离，基本消除** |
| 安装速度 | 一般 | 较快 | 通常最快（尤其多项目/CI 缓存场景） |
| 锁文件 | `package-lock.json` | `yarn.lock` | `pnpm-lock.yaml` |
| workspace | `workspaces` 字段 | `workspaces` 字段（最成熟） | `pnpm-workspace.yaml` |
| 严格性 | 宽松 | Berry 最严格（PnP） | 严格（默认不提升） |

> [!note] 幽灵依赖（phantom dependency）为什么危险
> 扁平化安装把所有间接依赖都提升到顶层 `node_modules`，于是你的代码可以 `import 'lodash'` 而**从未在 `package.json` 里声明它**——只是碰巧某个依赖带了它。哪天那个依赖升级去掉了 lodash，你的项目立刻构建失败，而错误信息离真正原因很远。pnpm 用符号链接只暴露**声明过的直接依赖**，从根上避免这个问题。

> [!tip] 该选哪个
> - 只想省事、团队没特殊要求：**npm**（Node 自带，生态兼容性最好）。
> - 多包仓库（monorepo）：**pnpm**（省磁盘、workspace 好用、依赖隔离严格）。
> - 已有 Yarn 项目：跟随现状即可，Classic 与 Berry 差异很大，不要混用。
> 包管理器的通用原理（依赖解析、锁文件、私有仓库）见 [[工具-03-包管理器]]。

#### 3.6.5 `npx`：临时执行包里的命令

`npx` 解决的是"我只想跑一次某个命令行工具，不想全局安装"：

```bash
# 运行环境：Node.js 自带 npx（npm 5.2+），bash / PowerShell 均可
npx create-vite@latest my-app     # 下载最新版脚手架并执行
npx --no-install eslint .         # 只用本地已安装的 eslint，找不到就报错（CI 推荐）
npx -p typescript tsc --version   # 临时安装 typescript 这个包，只为跑 tsc
```

`npx` 的查找顺序是：**本地 `node_modules/.bin` → 缓存 → 远程下载**。所以它也可以当作"本地命令的快捷方式"：`npm run` 之外的场景直接 `npx vite` 即可。

### 3.7 打包：为什么浏览器跑不了 `node_modules`

一个真实的 npm 包被 `import` 时，浏览器面对四类无法处理的东西：

| 障碍 | 具体表现 | 打包器怎么解决 |
|---|---|---|
| 裸模块名（bare specifier） | `import 'vue'`，浏览器不知道去哪找 | 按 Node 解析算法在 `node_modules` 里找到真实文件路径 |
| CommonJS 语法 | `require` / `module.exports` 浏览器不认识 | 把 CJS 包装成函数并注入 `require` 实现（或转成 ESM） |
| Node 内置模块 | `import fs from 'node:fs'` | 浏览器场景替换为 polyfill 或直接报错提示 |
| 非 JS 资源与超集语法 | `.vue`、`.scss`、`.ts`、JSX | 通过插件转译成 JS |

**打包器（bundler）**做的事可以归纳为五步：

1. **解析入口**（entry）：从 `index.html` 或 `src/main.js` 出发；
2. **构建依赖图**：递归解析每个 `import`，得到 $G=(V,E)$，$V$ 是模块，$E$ 是导入关系；
3. **转译**（transpile）：TypeScript / JSX / 新语法 → 目标环境能跑的 JS；
4. **合并与压缩**（bundle & minify）：把模块包装进运行时，删除死代码，压缩体积；产物体积大致是
   $$
   S \;=\; \sum_{v \in V_{\text{reachable}}} s(v) \;-\; S_{\text{treeshaken}} \;-\; S_{\text{minify}}
   $$
5. **代码分割**（code splitting）：把 `import()` 的分割点拆成独立 chunk，实现按需加载。

> [!note] 现代工具的分工
> - **Vite**：开发时不打包（用浏览器原生 ESM 直接跑，只对依赖做预构建），生产用 Rollup 打包；
> - **Webpack**：全流程自己打包，生态与插件最丰富；
> - **esbuild / SWC / Rolldown**：用原生语言实现的高性能转译与压缩器，常作为底层引擎。
> 具体配置与优化手段见 [[前端-08-构建工具-Vite与Webpack]]。

### 3.8 模块化与工程化的关系

| 工程问题 | 模块化提供了什么 | 还需要什么 |
|---|---|---|
| 代码组织 | 文件即模块、显式依赖 | 目录约定、分层架构、路径别名 |
| 依赖管理 | `import` 声明依赖 | 包管理器、锁文件、私有源、依赖审计 |
| 构建产物 | 静态依赖图 | 打包、转译、压缩、代码分割、缓存策略 |
| 质量保障 | 模块可单独测试 | 单元测试、类型检查、Lint、CI 流水线 |
| 团队协作 | 接口边界清晰 | 代码规范、提交规范、Code Review、发布流程 |
| 运行时可靠 | 单例缓存、作用域隔离 | 错误监控、日志、灰度与回滚 |

一句话：**模块化解决"代码怎么切分与组合"，工程化解决"这套切分如何被稳定地生产、验证和交付"。** 模块化是工程化的地基，不是全部。

---

## 四、怎么用：一个端到端的可运行示例

下面这个例子把 ESM、动态导入、顶层 await、`exports` 字段与 npm 脚本串起来。**运行环境：Node.js 18+（本机实测 v24.18.0）；目录结构与命令在 bash / PowerShell 下均可用。**

```
demo/
├── package.json
├── src/
│   ├── main.mjs
│   ├── store.mjs
│   └── plugins/
│       ├── json.mjs
│       └── csv.mjs
└── node_modules/（由 npm install 生成）
```

```jsonc
// demo/package.json
{
  "name": "demo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": { "import": "./src/main.mjs", "default": "./src/main.mjs" },
    "./plugins/*": "./src/plugins/*"
  },
  "scripts": {
    "start": "node src/main.mjs"
  },
  "engines": { "node": ">=18" }
}
```

```js
// demo/src/store.mjs —— 简单的发布订阅，演示 ESM 的 live binding
let listeners = [];
export const state = { items: [] };

export function add(item) {
  state.items.push(item);                 // 改属性：所有导入方立即可见
  listeners.forEach((fn) => fn(state));
}
export function subscribe(fn) {
  listeners.push(fn);
  return () => { listeners = listeners.filter((f) => f !== fn); };   // 返回取消订阅函数
}
```

```js
// demo/src/plugins/json.mjs 与 csv.mjs —— 约定相同接口，供动态导入选择
// json.mjs
export default (items) => JSON.stringify(items, null, 2);
// csv.mjs
export default (items) => ['name,price', ...items.map((i) => `${i.name},${i.price}`)].join('\n');
```

```js
// demo/src/main.mjs —— 入口：顶层 await + 动态导入 + 代码分割
import { state, add, subscribe } from './store.mjs';

const unsub = subscribe((s) => console.log(`[事件] 现在有 ${s.items.length} 件商品`));

add({ name: '键盘', price: 399 });
add({ name: '鼠标', price: 99 });

// 顶层 await：模块求值可以等待异步操作
const format = process.env.FORMAT ?? 'json';
const mod = await import(`./plugins/${format}.mjs`);   // 运行时决定加载哪个插件
console.log(mod.default(state.items));

unsub();                               // 取消订阅
add({ name: '显示器', price: 1299 });   // 不再触发日志
```

```bash
# 运行环境：Node.js 18+（实测 v24.18.0）
cd demo
npm start                     # 等价于 node src/main.mjs
# 输出：
# [事件] 现在有 1 件商品
# [事件] 现在有 2 件商品
# [ { "name": "键盘", "price": 399 }, { "name": "鼠标", "price": 99 } ]
FORMAT=csv npm start          # Linux/macOS
$env:FORMAT='csv'; npm start  # Windows PowerShell
```

**关键点解释：**

- `store.mjs` 导出的是 `state` 这个**绑定**，`main.mjs` 里读到的永远是当前值——不需要重新 require；
- `await import(\`./plugins/${format}.mjs\`)` 是运行时决策，打包器会把它变成**分割点**（同时把 `plugins` 目录下所有可能匹配的文件都纳入）；
- `"exports"` 里的 `./plugins/*` 让"包外"也能访问子路径；**没写进去的路径会被拒绝**（实测报 `ERR_PACKAGE_PATH_NOT_EXPORTED`）；
- `"type": "module"` 让本包里所有 `.js` 都按 ESM 解析，避免依赖语法自动检测。

---

## 五、注意事项与常见坑

> [!warning] 模块与包管理的十二个高频陷阱
> 1. **`exports = {...}` 不生效**：断开了与 `module.exports` 的别名关系，必须写 `module.exports = {...}`。
> 2. **把 CJS 的导出当"活值"用**：`const { count } = require('./c')` 之后再 `c.inc()`，`count` 永远是旧值——它是快照。
> 3. **给导入的绑定赋值**：`import { n } from './m.mjs'; n = 1;` → `TypeError: Assignment to constant variable.`（实测）。
> 4. **ESM 忘记写扩展名**：`import './x'` 会直接抛 `ERR_MODULE_NOT_FOUND`，必须写 `./x.js` / `./x.mjs`，目录索引也不会自动解析。
> 5. **在 ESM 里用 `require` / `__dirname`**：三者 `typeof` 都是 `'undefined'`；用 `createRequire(import.meta.url)` 或 `import.meta.dirname` 代替。
> 6. **循环依赖里读 `const` 绑定**：ESM 中会抛 TDZ 错误（`Cannot access '...' before initialization`）；CJS 中会静默拿到 `undefined`。
> 7. **`package.json` 写了 `exports` 却漏了子路径**：使用者 `import 'pkg/xxx'` 立刻失败，属于**破坏性变更**，要按 SemVer 升 major。
> 8. **`^0.x` 的误解**：以为 `^0.2.3` 能升到 `0.9.0`，实际不能（只到 `<0.3.0`）。
> 9. **`npm install` 当成"升级到最新"**：它按锁文件装；升级要 `npm update`（且仍受范围限制）。
> 10. **`devDependencies` 与 `dependencies` 放错**：把 `vite`、`typescript` 写进 `dependencies` 会让使用者的安装体积翻倍；反过来把运行时依赖写进 `devDependencies`，用户装完运行时报 `Cannot find module`。
> 11. **在循环里反复 `import()` 同一个模块**：虽然模块本身有缓存，但每次调用都产生一次微任务与一次解析；应把结果缓存在变量里。
> 12. **依赖自动语法检测**：`"type"` 字段漏写时，同一个文件在不同 Node 版本上行为不同（见 3.4.1）。

> [!danger] 三个会造成线上事故的操作
> - **删除或忽略锁文件**：团队每个人装出的依赖树都不同，"我本地是好的"从此无法复现。
> - **在 `import()` 里拼用户可控的字符串**：打包器会把整个目录（甚至整个项目）打进去，产物体积爆炸；更糟的是在服务端可能造成任意模块加载。
> - **把带副作用的初始化代码放进 `"sideEffects": false` 的包里**：打包器会把它删掉，出现"开发正常、生产少了一段逻辑"的诡异 bug。

> [!tip] 实践建议
> - 新项目一律 **ESM 优先**：`"type": "module"`，库对外提供 `exports` 条件导出（`import` / `require` 双入口）。
> - 团队统一包管理器，并在 `packageManager` 字段里锁定版本（以官方最新文档为准）。
> - 提交 `package-lock.json` / `pnpm-lock.yaml`，CI 用 `npm ci` 或 `pnpm install --frozen-lockfile`。
> - 定期 `npm ls <pkg>` 排查"同一个包出现多个版本"，必要时用 `overrides` / `resolutions` 收敛。
> - 用 `npm audit`、`npm outdated` 纳入例行维护，而不是等到出安全问题。

---

## 六、练习题

> [!question] 练习 1（CJS 陷阱诊断）
> 下面代码执行后，外部 `require('./m.cjs')` 得到什么？解释为什么，并改写为两种都能正确导出的写法。
> ```js
> exports.a = 1;
> module.exports = { b: 2 };
> exports.c = 3;
> module.exports.d = 4;
> ```

> [!question] 练习 2（拷贝 vs 绑定）
> 分别用 CJS 与 ESM 写一对模块：`lib` 内部维护 `let total = 0`，导出 `total` 与 `add(n)`。在 `main` 里引入后连续调用 `add(1)` 两次，打印 `total`。写出两次输出并解释差异，再用一句话总结两套规范的导出语义。

> [!question] 练习 3（循环依赖）
> 用三个文件复现 CJS 的循环依赖：`a.cjs` → `b.cjs` → `a.cjs`，使 `b` 中打印 `a` 的某个字段为 `undefined`。然后把共享数据抽到第三个模块 `shared.cjs`，消除这个环，并说明为什么这样改之后就安全了。

> [!question] 练习 4（`exports` 字段设计）
> 为一个名为 `tiny-date` 的库设计 `package.json`：要求同时支持 `require` 与 `import`，支持子路径 `tiny-date/format`，声明 Node `>=18`、无副作用，并把构建产物放在 `dist/`。写出完整的 `exports`、`type`、`files`、`engines`、`sideEffects` 字段，并说明为什么 `default` 条件必须放在最后。

> [!question] 练习 5（范围与锁文件推理）
> 项目依赖 `"lodash": "^4.17.20"`。回答：① 装到 `4.17.21` 是否符合范围？② 装到 `4.18.0`？③ 装到 `5.0.0`？④ 某同事 `npm install` 时装到了 `4.17.21`，而你昨天装到 `4.17.20`，如果锁文件被 `.gitignore` 忽略了，会出现什么现象？⑤ 用 `~4.17.20` 替代 `^4.17.20` 会改变哪些情况下的行为？

---

## 七、常见问题 FAQ

> [!question] 新项目该用 ESM 还是 CommonJS？
> **能用 ESM 就用 ESM。** 理由：语言标准、静态可分析（tree-shaking、IDE 跳转、按需加载都更好）、浏览器原生支持、支持顶层 `await`。需要退回 CJS 的场景只剩三类：① 维护老代码；② 依赖的某个关键工具链尚不支持 ESM（越来越少）；③ 需要 `require` 的同步语义（现在 Node 也支持 `require(esm)` 了）。发布给别人的库建议**双入口**（`exports` 里同时给 `import` 与 `require`），但要警惕双包陷阱。

> [!question] ESM 会成为标准，那 `require` 是不是可以忘了？
> 不需要背 API，但必须理解 `require` 的**语义**，原因有两个：① 生态里仍有海量 CJS 包，读源码、排查 `Cannot find module` 都要用；② **CJS 与 ESM 的差异本身就是高频面试题与事故根源**（值拷贝 vs 动态绑定、同步 vs 静态、循环依赖的不同表现）。理解 CJS 也是理解"为什么打包器必须存在"的前提。

> [!question] 为什么 `import 'lodash'` 在 Node 里能用、在浏览器里报错？
> Node 实现了完整的包解析算法（逐级向上找 `node_modules`、读 `package.json` 的 `exports`/`main`）。浏览器只认 URL，裸模块名没有对应的网络地址，所以报 `Failed to resolve module specifier`。三个解法：**打包器**（生产主流）、**import map**（无需构建的小项目）、**CDN + 完整 URL**（快速原型）。

> [!question] 打包器都说支持 tree-shaking，为什么我的产物还是很大？
> 逐项排查：① 依赖是不是 CJS 版本（CJS 摇不动）？② 有没有开 production 模式？③ 包有没有声明 `sideEffects: false`？④ 是不是 `import * as x` 或 `export * from` 导致整个命名空间被引用？⑤ 是不是 `import()` 里用了变量拼接，把整个目录都拉进来了？⑥ 有没有第三方库在顶层做了重副作用（如注入全局样式）？**多数"摇不掉"都是①和⑤。**

> [!question] 锁文件到底提交还是忽略？
> **提交。** 应用项目（网站、服务、App 后端）必须提交，这是可复现构建的前提；发布的**库**通常也提交（保证 CI 与本地一致），但库的使用者不会用到你的锁文件——他们只看 `package.json` 的范围与自己的锁文件。唯一可以忽略锁文件的场景是"一次性脚本/教学示例"，而这类场景根本不需要依赖管理。

---

## 相关笔记

- [[JavaScript-01-基础语法与类型]] —— `let`/`const` 与块级作用域是模块作用域的基础
- [[JavaScript-02-函数与作用域]] —— IIFE、闭包与作用域链，本篇 3.1 节的历史方案都建立在这些机制上
- [[JavaScript-03-对象与原型链]] —— `module.exports` 就是一个普通对象，属性的读写规则在这一篇
- [[JavaScript-04-异步编程]] —— 动态 `import()` 返回 Promise，`await` 与事件循环是理解它的前提
- [[前端-08-构建工具-Vite与Webpack]] —— 本篇"打包概念"的完整展开：插件、热更新、产物优化
- [[前端-09-前端工程化与调试]] —— Lint、格式化、CI 与错误监控这些"模块化之外"的部分
- [[工具-03-包管理器]] —— npm / pnpm / pip / NuGet 的横向对比与锁文件通用原理
- [[后端-02-Nodejs与Express]] —— Node 运行时对 CJS/ESM 的支持细节与服务端模块组织
- [[Python-03-函数与模块]] —— 与 Python 的 `import` 机制对照：两者都有模块缓存与循环导入问题
- [[工具-08-CICD入门]] —— `npm ci` 与锁文件在流水线中的作用

## 参考来源

- [MDN：JavaScript 模块（指南）](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Modules)
- [MDN：`import` 声明](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import)
- [MDN：`export` 声明](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/export)
- [MDN：动态 `import()`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Operators/import)
- [MDN：`import.meta`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import.meta)
- [MDN：import attributes（`with { type: 'json' }`）](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/import/with)
- [MDN：`<script type="importmap">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Reference/Elements/script/type/importmap)
- [Node.js 官方文档：CommonJS 模块](https://nodejs.org/docs/latest/api/modules.html)
- [Node.js 官方文档：ECMAScript 模块](https://nodejs.org/docs/latest/api/esm.html)
- [Node.js 官方文档：包（`package.json` 与 `exports` 解析）](https://nodejs.org/docs/latest/api/packages.html)
- [npm 官方文档：`package.json` 字段说明](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
- [npm 官方文档：`package-lock.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)
- [npm 官方文档：`npm ci`](https://docs.npmjs.com/cli/v10/commands/npm-ci)
- [npm 官方文档：`npx`](https://docs.npmjs.com/cli/v10/commands/npx)
- [npm 官方文档：`scripts` 生命周期](https://docs.npmjs.com/cli/v10/using-npm/scripts)
- [npm 官方文档：关于语义化版本](https://docs.npmjs.com/about-semantic-versioning)
- [语义化版本 2.0.0 中文版](https://semver.org/lang/zh-CN/)
- [pnpm 官方文档：项目初衷（硬链接与存储机制）](https://pnpm.io/zh/motivation)
- [pnpm 官方文档：基于符号链接的 node_modules 结构](https://pnpm.io/zh/symlinked-node-modules-structure)
- [Yarn 官方文档：快速开始](https://yarnpkg.com/getting-started)
- [现代 JavaScript 教程：模块简介](https://zh.javascript.info/modules-intro)
- [现代 JavaScript 教程：导出与导入](https://zh.javascript.info/modules)
- [现代 JavaScript 教程：动态导入](https://zh.javascript.info/modules-dynamic-imports)
- [ECMAScript 语言规范（TC39 官方最新版）](https://tc39.es/ecma262/)
- [Vite 官方文档：为什么选 Vite](https://vitejs.dev/guide/why)
- [Webpack 官方文档：核心概念](https://webpack.js.org/concepts/)
- 说明：Node 的模块语法自动检测、`require(esm)` 的支持范围、npm CLI 的 v10 文档路径都属于**版本敏感**信息，请以 Node.js 与 npm 官方最新文档为准。本篇代码除特别标注外均在本机 Node.js v24.18.0 上实测通过。
