使用Parcel本地启动网站时遭遇_BundleGraph.default断言错误

1. 先做基础排查（避免直接深入调试） #

• 清除Parcel缓存：删除项目根目录下的.parcel-cache文件夹，重新运行parcel serve index.html --port 3001，很多Parcel的异常错误都是缓存过期导致的。
• 重置依赖：删除node_modules文件夹和package-lock.json/yarn.lock文件，重新执行npm install或yarn install，确保所有依赖版本兼容。

2. 让调试器能捕获Parcel的子进程 #

错误出在Parcel的worker子进程里，直接加debugger不会生效，需要让Node.js调试器监控所有子进程：

• 用这个命令启动项目：node --inspect-brk node_modules/parcel/lib/cli.js serve index.html --port 3001，主进程会在启动时暂停，等待调试器连接。
• 打开Chrome浏览器，输入chrome://inspect，点击「Configure」添加localhost:9229，就能看到待调试的Node.js进程，点击「Inspect」打开DevTools。
• 找到报错文件node_modules/@parcel/core/lib/worker.js，定位到第176行的断言位置，点击行号添加断点，再继续执行，就能触发断点查看变量。

3. 查看bundleGraph的具体信息 #

在断点处，用DevTools控制台执行以下命令排查：

• console.log(bundleGraph)：打印变量的所有属性，确认它的实际结构。
• console.log(typeof bundleGraph)：查看变量类型，判断是对象、null还是其他值。
• console.log(Object.getPrototypeOf(bundleGraph))：对比它的原型链和_BundleGraph.default的原型，看是否因模块重复加载导致实例判断失败。

4. 命令行调试替代方案 #

如果不想用浏览器调试，可使用Node.js内置调试器：

• 执行node inspect node_modules/parcel/lib/cli.js serve index.html --port 3001进入命令行调试模式。
• 输入setBreakpoint('node_modules/@parcel/core/lib/worker.js', 176)设置断点，输入c继续执行，触发断点后输入repl进入交互模式，直接查看变量信息。

5. 深层排查方向 #

如果发现是模块重复加载问题（比如@parcel/core存在多个版本），执行npm ls @parcel/core查看依赖树，确认是否有嵌套的不同版本依赖，若有则手动统一版本。

内容的提问来源于stack exchange，提问作者Tommaso Bendinelli