JavaScript-06-模块化与工程化
本篇讲什么
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)是一个独立的代码单元,它同时满足四个条件:
- 有自己的作用域:模块内声明的变量不会泄漏到外部;
- 显式导出:只有明确写出的东西才能被外部拿到;
- 显式导入:用到什么就写什么,依赖关系可读;
- 单例缓存:同一个模块无论被导入多少次,只执行一次,共享同一份实例。
JavaScript 的模块化史可以分成三段:
| 阶段 | 时间 | 代表做法 | 解决的问题 | 留下的问题 |
|---|---|---|---|---|
| 无模块 | 1995–2009 | 多个 <script> 顺序拼接 | 无 | 全局污染、顺序脆弱、命名冲突 |
| 社区方案 | 2009–2015 | 命名空间对象、IIFE、AMD、CommonJS | 作用域隔离、依赖声明 | 各方案互不兼容,浏览器里要额外加载器 |
| 语言标准 | 2015 至今 | ES Module(ES2015 起) | 语法级模块、静态可分析 | 生态迁移期需要处理 CJS/ESM 互操作 |
一句话抓住本质
模块系统要解决的核心矛盾是:"我需要复用小颗粒的代码,但我不想让这些小颗粒互相污染。"
所有模块方案都是同一件事的三种实现:用一个函数作用域把代码包起来(隔离)+ 通过一个约定好的出口传值(接口)+ 记录谁引用了谁(依赖图)。
二、为什么这样设计:历史问题与设计取舍
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) |
为什么浏览器方案(AMD/CMD)输了
2010 年前后浏览器端流行 AMD(Asynchronous Module Definition,代表实现 RequireJS)和 CMD(代表实现 SeaJS)。它们用
define([...], function(){})把依赖写成数组,运行时异步加载。缺点是要额外引入加载器、语法不是语言的一部分、而且无法做静态分析。ESM 一进标准,这两套就基本退出了历史舞台——能被语言原生支持的方案,最终会赢过库方案。
三、核心内容
3.1 史前时代:全局函数 → 命名空间 → IIFE
// 运行环境:任意浏览器控制台或 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 的核心只有三个东西:
// 运行环境: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):
// Node 官方文档给出的模块包装函数(示意,不是你要写的代码)
(function (exports, require, module, __filename, __dirname) {
// 你写的模块代码原封不动地放在这里
});
于是:
module是当前模块的对象,module.exports才是真正的出口;exports只是进入函数时exports = module.exports得到的局部变量,一个指向同一对象的别名;require是包装函数传入的参数,不是全局变量(在 ESM 里更是不存在)。
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 → 返回。
// 运行环境: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 —— 删了缓存才会重新执行
"值的拷贝"要理解准确
CommonJS 导出的是一个对象引用。所以
module.exports.count++这种改属性的操作,导入方是能看到的;看不到的是"模块内部用let变量重新赋值"这件事——因为{ count }在导出那一刻就把值抄下来了。一句话:CJS 导出的是"快照 + 共享对象",不是指向模块内部变量的绑定。
3.2.3 循环依赖:拿到"半成品"
假设 a.cjs 与 b.cjs 互相 require,Node 的处理方式是:执行到一半的模块,其 module.exports 也会被放进缓存,于是对方拿到的是"半成品"。
// 运行环境: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 位置碰运气。循环依赖在依赖图 上就是一条有向环 ,工程上通常用 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 导入。
// 运行环境: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 优先用具名导出 |
为什么很多规范建议"库不要用默认导出"
默认导出允许导入方随便改名,一个
import a from 'x'和另一个文件里的import b from 'x'可能指的是同一个东西,重命名重构、自动导入、tree-shaking 都更难做。对外发布的库优先具名导出;默认导出留给"单文件单组件"这类场景。
3.3.2 静态分析、tree-shaking 与前提条件
ESM 的 import / export 是语法结构而不是函数调用,所以在不执行代码的前提下就能画出完整的依赖图。这就是静态分析(static analysis)能力的来源,也是 tree-shaking(摇树优化,即删掉未被使用的导出)的前提。
tree-shaking 生效需要四个条件:
- 代码是 ESM(
import/export),CJS 的动态require无法安全删除; - 打包器开启了 production / 压缩流程(开发模式下通常不摇);
- 模块没有副作用,或通过
package.json的"sideEffects": false明确声明; - 导出确实没有被引用,且没有被
export *之类的动态再导出搞乱。
副作用是 tree-shaking 的最大杀手
```js
// polyfill.js —— 这个模块"导出"是空的,但 import 它本身就有意义
import 'core-js/stable'; // 执行时会往全局补 API
```
打包器无法证明它无害,只能保留。这正是
"sideEffects": false存在的意义:用声明换取更小的产物——但声明错了会真的删掉必要的代码,必须谨慎。
3.3.3 动态绑定(live binding)
ESM 的导出不是"值",而是"指向变量的绑定"。导入方看到的是实时的值。
// 运行环境: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)
CJS 与 ESM 最关键的心智差异
- CommonJS:
require返回一个对象,对象里的属性是导出那一刻的快照。- ES Module:
import拿到的是指向源模块变量的只读绑定,源模块改变量,导入方立刻看到新值。所以"ESM 导出的是引用,CJS 导出的是值"这句话方向是对的,但更精确的说法是:ESM 导出绑定(binding),CJS 导出对象(object)。
3.3.4 顶层 await、import.meta 与 JSON 导入
// 运行环境: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);
// 运行环境: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,可以写在任何位置、可以用变量拼路径。
// 运行环境: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`); // ⚠️ 变量拼接会让打包器把整个目录都打进去
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 指定 | 无后缀可依据,只能靠参数 |
# 运行环境: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()))"
语法检测会掩盖配置错误
一个忘了写
"type": "module"的包,因为文件里有export,在新版 Node 上"碰巧能跑";一旦换到旧版本 Node 或加上--no-experimental-detect-module,立刻报SyntaxError: Unexpected token 'export'。永远显式声明type字段或用明确的.mjs/.cjs后缀,不要依赖自动检测。相关行为仍在演进,以 Node 官方文档为准。
3.4.2 混合使用:互操作的两条规则
// 运行环境: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
互操作三大坑
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">
<!-- 运行环境:现代浏览器,需通过 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 |
浏览器里想用包名怎么办
用 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 关键字段逐项解释
{
"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 语义化版本与 ^ / ~
版本号是三元组 ,含义是承诺:
- major:不兼容的破坏性变更;
- minor:向后兼容地新增功能;
- patch:向后兼容地修 bug。
范围符号与之对应(下表中 [a, b) 表示左闭右开区间,即含 不含 ):
| 写法 | 等价区间 | 含义 | 何时自动升级 |
|---|---|---|---|
1.2.3 | 精确锁定 | 不会 | |
^1.2.3 | 允许 minor 与 patch 升级 | npm update 时 | |
^0.2.3 | 0.x 视为不稳定:只允许 patch 升级 | npm update 时 | |
^0.0.3 | 只允许 patch 且 minor 为 0 时更严格 | npm update 时 | |
~1.2.3 | 只允许 patch 升级 | npm update 时 | |
1.2.x | 同上,另一种写法 | npm update 时 | |
>=1.2.3 <2 | 组合范围 | 显式区间 | 视范围而定 |
* / latest | 任意版本 | 危险 | 随时 |
三条必须记住的规则
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.4.2,三个月后同事装出来也是1.4.2,而不是1.6.0。CI 与生产环境尤其关键。 - 安全与校验:
integrity字段能发现被篡改或损坏的包。 - 加速:安装时不必反复向 registry 询问版本元数据。
npm ci依赖它:CI 里用npm ci才能得到"完全按锁文件、干净安装"的结果。
# 运行环境: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 # 看哪些依赖落后于范围允许的最新版
关于 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) | 严格(默认不提升) |
幽灵依赖(phantom dependency)为什么危险
扁平化安装把所有间接依赖都提升到顶层
node_modules,于是你的代码可以import 'lodash'而从未在package.json里声明它——只是碰巧某个依赖带了它。哪天那个依赖升级去掉了 lodash,你的项目立刻构建失败,而错误信息离真正原因很远。pnpm 用符号链接只暴露声明过的直接依赖,从根上避免这个问题。
该选哪个
- 只想省事、团队没特殊要求:npm(Node 自带,生态兼容性最好)。
- 多包仓库(monorepo):pnpm(省磁盘、workspace 好用、依赖隔离严格)。
- 已有 Yarn 项目:跟随现状即可,Classic 与 Berry 差异很大,不要混用。
包管理器的通用原理(依赖解析、锁文件、私有仓库)见 工具-03-包管理器。
3.6.5 npx:临时执行包里的命令
npx 解决的是"我只想跑一次某个命令行工具,不想全局安装":
# 运行环境: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)做的事可以归纳为五步:
- 解析入口(entry):从
index.html或src/main.js出发; - 构建依赖图:递归解析每个
import,得到 , 是模块, 是导入关系; - 转译(transpile):TypeScript / JSX / 新语法 → 目标环境能跑的 JS;
- 合并与压缩(bundle & minify):把模块包装进运行时,删除死代码,压缩体积;产物体积大致是
- 代码分割(code splitting):把
import()的分割点拆成独立 chunk,实现按需加载。
现代工具的分工
- 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 生成)
// 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" }
}
// 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); }; // 返回取消订阅函数
}
// 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');
// 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 }); // 不再触发日志
# 运行环境: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 解析,避免依赖语法自动检测。
五、注意事项与常见坑
模块与包管理的十二个高频陷阱
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)。
三个会造成线上事故的操作
- 删除或忽略锁文件:团队每个人装出的依赖树都不同,"我本地是好的"从此无法复现。
- 在
import()里拼用户可控的字符串:打包器会把整个目录(甚至整个项目)打进去,产物体积爆炸;更糟的是在服务端可能造成任意模块加载。- 把带副作用的初始化代码放进
"sideEffects": false的包里:打包器会把它删掉,出现"开发正常、生产少了一段逻辑"的诡异 bug。
实践建议
- 新项目一律 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纳入例行维护,而不是等到出安全问题。
六、练习题
练习 1(CJS 陷阱诊断)
下面代码执行后,外部
require('./m.cjs')得到什么?解释为什么,并改写为两种都能正确导出的写法。```js
exports.a = 1;
module.exports = { b: 2 };
exports.c = 3;
module.exports.d = 4;
```
练习 2(拷贝 vs 绑定)
分别用 CJS 与 ESM 写一对模块:
lib内部维护let total = 0,导出total与add(n)。在main里引入后连续调用add(1)两次,打印total。写出两次输出并解释差异,再用一句话总结两套规范的导出语义。
练习 3(循环依赖)
用三个文件复现 CJS 的循环依赖:
a.cjs→b.cjs→a.cjs,使b中打印a的某个字段为undefined。然后把共享数据抽到第三个模块shared.cjs,消除这个环,并说明为什么这样改之后就安全了。
练习 4(
exports字段设计)为一个名为
tiny-date的库设计package.json:要求同时支持require与import,支持子路径tiny-date/format,声明 Node>=18、无副作用,并把构建产物放在dist/。写出完整的exports、type、files、engines、sideEffects字段,并说明为什么default条件必须放在最后。
练习 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
新项目该用 ESM 还是 CommonJS?
能用 ESM 就用 ESM。 理由:语言标准、静态可分析(tree-shaking、IDE 跳转、按需加载都更好)、浏览器原生支持、支持顶层
await。需要退回 CJS 的场景只剩三类:① 维护老代码;② 依赖的某个关键工具链尚不支持 ESM(越来越少);③ 需要require的同步语义(现在 Node 也支持require(esm)了)。发布给别人的库建议双入口(exports里同时给import与require),但要警惕双包陷阱。
ESM 会成为标准,那
require是不是可以忘了?不需要背 API,但必须理解
require的语义,原因有两个:① 生态里仍有海量 CJS 包,读源码、排查Cannot find module都要用;② CJS 与 ESM 的差异本身就是高频面试题与事故根源(值拷贝 vs 动态绑定、同步 vs 静态、循环依赖的不同表现)。理解 CJS 也是理解"为什么打包器必须存在"的前提。
为什么
import 'lodash'在 Node 里能用、在浏览器里报错?Node 实现了完整的包解析算法(逐级向上找
node_modules、读package.json的exports/main)。浏览器只认 URL,裸模块名没有对应的网络地址,所以报Failed to resolve module specifier。三个解法:打包器(生产主流)、import map(无需构建的小项目)、CDN + 完整 URL(快速原型)。
打包器都说支持 tree-shaking,为什么我的产物还是很大?
逐项排查:① 依赖是不是 CJS 版本(CJS 摇不动)?② 有没有开 production 模式?③ 包有没有声明
sideEffects: false?④ 是不是import as x或export from导致整个命名空间被引用?⑤ 是不是import()里用了变量拼接,把整个目录都拉进来了?⑥ 有没有第三方库在顶层做了重副作用(如注入全局样式)?多数"摇不掉"都是①和⑤。
锁文件到底提交还是忽略?
提交。 应用项目(网站、服务、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 模块(指南)
- MDN:
import声明 - MDN:
export声明 - MDN:动态
import() - MDN:
import.meta - MDN:import attributes(
with { type: 'json' }) - MDN:
<script type="importmap"> - Node.js 官方文档:CommonJS 模块
- Node.js 官方文档:ECMAScript 模块
- Node.js 官方文档:包(
package.json与exports解析) - npm 官方文档:
package.json字段说明 - npm 官方文档:
package-lock.json - npm 官方文档:
npm ci - npm 官方文档:
npx - npm 官方文档:
scripts生命周期 - npm 官方文档:关于语义化版本
- 语义化版本 2.0.0 中文版
- pnpm 官方文档:项目初衷(硬链接与存储机制)
- pnpm 官方文档:基于符号链接的 node_modules 结构
- Yarn 官方文档:快速开始
- 现代 JavaScript 教程:模块简介
- 现代 JavaScript 教程:导出与导入
- 现代 JavaScript 教程:动态导入
- ECMAScript 语言规范(TC39 官方最新版)
- Vite 官方文档:为什么选 Vite
- Webpack 官方文档:核心概念
- 说明:Node 的模块语法自动检测、
require(esm)的支持范围、npm CLI 的 v10 文档路径都属于版本敏感信息,请以 Node.js 与 npm 官方最新文档为准。本篇代码除特别标注外均在本机 Node.js v24.18.0 上实测通过。