在本地开发 npm 包的时候，一个很常见的困惑是：明明改了 node_modules 里某个包的源码，页面上却毫无变化，热更新也不触发。多数人第一反应是缓存问题，清缓存、删目录、重启，折腾一圈后发现还是不行。其实根源往往很简单：Webpack 的 watch 模式默认不会深度监听 node_modules 目录下的文件变化，改动根本没进入它的视野。这篇文章就来聊聊这个机制的来龙去脉，以及到底什么情况下才值得开启对 node_modules 的监听。
一、Webpack 默认为什么不监听 node_modules
要理解这个问题，先得知道 Webpack 的 watch 模式是怎么工作的。当你在开发环境运行 webpack --watch 或者使用 webpack-dev-server 时，Webpack 会基于 chokidar 这类文件监听库，对构建图中涉及到的文件注册监听事件。注意这里的关键词是“构建图中涉及到的文件”，而不是整个磁盘目录。理论上说，既然 node_modules 里的包也是构建图的一部分，改动它们理应触发重新编译才对。
但现实是，Webpack 对依赖文件采用了不同的快照策略。它通过 snapshot 机制记录文件的时间戳和内容哈希，判断依赖是否变化。对于 node_modules 中的文件，默认策略通常只记录包级别的元信息（比如 package.json 的修改时间、包的版本号），而不是逐个文件的细粒度快照。这样做的核心原因是性能：一个中型项目的依赖动辄几万个文件，如果每次编译都要对全部依赖文件做哈希比对，增量构建的耗时会被严重拖累，尤其在 macOS 和 Windows 上，文件系统的目录遍历本身就比 Linux 慢不少。
另外，很多脚手架（比如早期版本的 create-react-app 内部配置）会直接在 watchOptions 里显式忽略 node_modules：
// webpack.config.js
module.exports = {
watchOptions: {
ignored: /node_modules/,
// Windows 等系统上建议加大轮询间隔
aggregateTimeout: 300,
poll: 1000,
},
};
这段配置里的 ignored 字段是 chokidar 提供的能力，被匹配到的路径不会注册任何文件系统事件。也就是说，如果配置里写了这一行，那么无论你怎么改 node_modules 里的代码，watch 都不会有反应。这是“改了没效果”最直接的技术原因之一。
二、什么场景下真的需要开启监听
并不是所有人都需要监听 node_modules。绝大多数业务开发中，依赖是稳定的，改源码调试属于偶发行为，为这种情况牺牲整个项目的构建性能并不划算。但在下面几类场景中，开启监听能显著提升开发体验。
第一类是本地联调 npm 包。你正在开发一个组件库或工具库，用 npm link 或者 pnpm 的 link: 协议把它挂到业务项目里调试。这时你的日常工作就是改这个包的源码，如果每次都要手动重启构建，效率极低。开启对特定包的监听是最合理的做法。关键技巧是不要粗暴地去掉 ignored，而是精确排除：
// 只监听 node_modules 中正在开发的本地包
module.exports = {
watchOptions: {
ignored: /node_modules\/(?!(my-ui-lib|@my-scope)\/).*/,
},
// 同时确保该包不被解析为软链接指向的外部路径
resolve: {
symlinks: true,
},
};
上面的正则含义是：忽略 node_modules 下所有内容，但 my-ui-lib 和 @my-scope 命名空间下的包除外。这样既保留了忽略海量第三方依赖的性能收益，又能让本地包的改动即时生效。
第二类是 monorepo 场景。在使用 pnpm workspace 或者 yarn workspaces 的仓库里，如果业务应用和依赖包都在同一仓库中，包往往通过符号链接指向源码目录，这种情况下 Webpack 监听的是真实路径，一般不需要特殊处理。但如果你的 workspace 配置把依赖提升（hoist）到了根目录的 node_modules，或者使用了 hard-link 机制，就要注意监听路径是否落在被忽略的范围内。排查方法是开启 stats: 'verbose' 观察 watch 的实际路径，或者直接用 resolve.symlinks: false 让 Webpack 按链接路径解析，确保监听目标与文件真实位置一致。
第三类是通过 patch-package 之类工具给第三方包打补丁的场景。补丁文件本身是在安装阶段应用的，如果你频繁修改补丁内容，每次都要重新执行 patch 命令并触发一次全量安装，此时让 watch 覆盖被 patch 的那几个包，可以省掉反复执行命令的步骤。不过要注意，patch-package 的官方推荐流程仍是修改后重新 patch，监听只适合临时调试，不要把半成品补丁留在提交里。
三、开启之后可能踩到的坑与替代方案
把 ignored 去掉或者调整正则之后，最常见的副作用是 CPU 占用飙升。尤其是在 Linux 之外的系统上，inotify 不可用，chokidar 会退化为轮询模式，几万个文件的轮询会让风扇狂转。如果确实需要全量监听，建议显式设置 poll 和合理的 aggregateTimeout，把多次连续改动合并成一次编译：
module.exports = {
watchOptions: {
// 不忽略 node_modules 时的保守配置
aggregateTimeout: 1000, // 攒 1 秒内的改动一起编译
poll: 2000, // 每 2 秒轮询一次
followSymlinks: true, // 跟随软链接监听真实文件
},
snapshot: {
// 对依赖目录使用时间戳判断，避免逐文件哈希
managedPaths: [],
immutablePaths: [],
},
};
这里的 snapshot.managedPaths 默认值包含 node_modules，它告诉 Webpack 这些目录是“包管理器管理的”，可以用宽松策略做快照。如果你希望 Webpack 认真对待依赖文件的变化，需要把它清空，否则即使文件系统事件被监听到了，快照比对阶段也可能认为“包没变”而跳过重建。这个配置项是被很多人忽略的隐藏关卡，改了 ignored 却不调整 snapshot，经常出现“有时候生效有时候不生效”的诡异现象。
还有一个思路上的转变值得考虑：与其让构建工具去监听 node_modules，不如在包那边做文章。比如在组件库目录里跑一个 tsc --watch 或者 rollup 的 watch 构建，把产物输出到业务项目的 node_modules 对应位置，构建产物的变化天然会被业务侧的 watch 捕获（前提是该包没被忽略）。又或者干脆用 webpack 5 的 Module Federation、vite 的 alias 直指源码等方式，从解析层面绕开 node_modules。这些方案把增量编译的责任放在包本身，粒度更细，总体上比让业务项目监听整个依赖树更高效。
总结一个简单的判断标准：如果你只是偶尔改一次依赖源码来排查问题，直接改完重启构建就好，不值得改配置；如果你的日常工作流就是“改依赖包源码、看业务效果”，那就用精确的正则只放开相关的包，并同步调整 snapshot 配置；如果你在维护 monorepo，优先考虑符号链接加源码直连的方案，而不是让 watch 覆盖整个 node_modules。按这个梯度选择，基本能在开发体验和构建性能之间找到平衡点。
Webpack监听node_moduleswatchOptionsignored配置修改时间：2026-09-06 03:50:44