w wyl123ly 的博客
MD

JavaScript-06-模块化与工程化

51 KB 2026.10.11 原文件

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)是一个独立的代码单元,它同时满足四个条件:

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

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 生效需要四个条件:

  1. 代码是 ESM(import/export),CJS 的动态 require 无法安全删除;
  2. 打包器开启了 production / 压缩流程(开发模式下通常不摇);
  3. 模块没有副作用,或通过 package.json 的 "sideEffects": false 明确声明;
  4. 导出确实没有被引用,且没有被 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);
方案语法特点
顶层 awaitconst x = await fetch(...)仅在 ESM 顶层可用,模块图会串行等待
import.meta.urlimport.meta.url当前模块的 file:// URL,配合 new URL() 拼路径
import.meta.dirnameimport.meta.dirnameNode 20.11+ 起提供,最接近 __dirname
import attributeswith { type: 'json' }让宿主知道该按什么类型解析,避免把 JSON 当 JS 执行
createRequireimport { 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.exportsimport / 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.mjsESM后缀优先,永远 ESM
x.cjsCJS后缀优先,永远 CJS
x.js,最近的 package.json 有 "type": "module"ESM整个包作用域内生效
x.js,最近的 package.json 有 "type": "commonjs" 或无 typeCJS(有例外,见下)默认是 CJS
x.js,无 type 字段,但文件里写了 import/exportESM新版本 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 取代;只为兼容老工具而保留
moduleESM 入口(打包器识别)不是 Node 标准字段,Node 自己不读它
exports官方入口声明,支持条件与子路径一旦写了 exports,未列出的子路径就不可访问,会报 ERR_PACKAGE_PATH_NOT_EXPORTED
typemodule / 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.30.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. 可复现:今天装出 1.4.2,三个月后同事装出来也是 1.4.2,而不是 1.6.0。CI 与生产环境尤其关键。
  2. 安全与校验:integrity 字段能发现被篡改或损坏的包。
  3. 加速:安装时不必反复向 registry 询问版本元数据。
  4. 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 对比
对比项npmYarn(Classic / Berry)pnpm
出品方npm, Inc.(现属 GitHub)Meta社区(pnpm.io)
node_modules 结构v3+ 扁平化(hoist)Classic 扁平化;Berry 默认 PnP(无 node_modules)符号链接 + 内容寻址存储,非扁平
磁盘占用每个项目各存一份同 npm全局一份存储,硬链接到各项目,最省
幽灵依赖存在(可 require 未声明的包)Classic 存在默认隔离,基本消除
安装速度一般较快通常最快(尤其多项目/CI 缓存场景)
锁文件package-lock.jsonyarn.lockpnpm-lock.yaml
workspaceworkspaces 字段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)做的事可以归纳为五步:

  1. 解析入口(entry):从 index.html 或 src/main.js 出发;
  2. 构建依赖图:递归解析每个 import,得到 , 是模块, 是导入关系;
  3. 转译(transpile):TypeScript / JSX / 新语法 → 目标环境能跑的 JS;
  4. 合并与压缩(bundle & minify):把模块包装进运行时,删除死代码,压缩体积;产物体积大致是

  1. 代码分割(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 与锁文件在流水线中的作用

参考来源