调试时修改node_modules内npm依赖文件未生效？原因及npm缓存排查

你遇到的修改文件后仍运行旧代码的情况，和npm运行时的缓存机制没有直接关联，常见原因可以分为三类：

• 改错了实际被加载的目标文件
  • 受包管理器的依赖提升策略影响，项目可能存在多份同版本的包B：npm/yarn会将大部分依赖提升到项目根目录的node_modules下，结合Node.js的模块向上查找加载规则、workspace软链接配置等场景，实际加载的可能是根目录、全局存储里的版本，根本不是你手动修改的A\node_modules\B\index.js。
  • 修改的文件不是包的实际运行入口：打开包B的package.json文件，核对main、exports字段的配置，很多第三方包的根目录index.js只是占位文件，实际运行入口指向的是dist/、lib/目录下的编译产物，你修改的源码文件本身就不会被执行。
  • pnpm这类使用虚拟存储结构的包管理器场景下，你在项目node_modules下看到的包文件大多是指向全局存储的软链接，直接修改软链接路径下的文件，可能存在权限拦截、修改未同步到实体存储的问题。
• 各类工具缓存导致旧代码被复用
  • 构建类工具的编译缓存：webpack、vite、ts-node这类工具第一次编译时，会把转译后的依赖代码结果存在node_modules/.cache目录下，只要缓存没有失效，哪怕你改了node_modules里的源文件，工具也会直接读取之前存储的编译结果，不会重新解析你修改的内容。
  • 常驻进程的内存缓存：如果是用nodemon、dev server这类持续运行的进程调试，工具默认的文件监听规则通常会忽略node_modules路径的变动，你修改文件之后进程不会触发重载，一直执行内存里第一次加载的旧代码。
• 运行环境与你修改的文件路径不一致
  如果你是在WSL、Docker容器、远程服务器这类独立环境里运行代码，你本地修改的A\node_modules\B\index.js根本没有同步到实际运行的环境中，自然会执行环境里留存的旧版本代码。

快速排查技巧：在你的业务代码里导入包B之后，直接执行console.log(require.resolve('B'))，就能拿到实际被加载的包B文件的完整绝对路径，对比你修改的文件路径，1分钟就能定位是否改错了位置。

需要明确的是，npm本身在运行代码时，不会跳过项目node_modules下的文件、主动从全局安装缓存读取依赖，不存在这类运行时缓存逻辑。

内容的提问来源于stack exchange，提问作者luca.vercelli