Puppeteer 报 “Cannot find module ‘puppeteer-core/internal/...‘“ 怎么处理

Puppeteer 报 "Cannot find module 'puppeteer-core/internal/...'" 怎么处理

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer

在 Node.js 项目里import 'puppeteer'（或加载依赖了 Puppeteer 的脚本）时，如果抛出Cannot find module 'puppeteer-core/internal/...'，说明模块解析环节出了问题。根据 docs/troubleshooting.md 中的说明，这个报错只有两类原因：Node.js 版本过低，或者项目中使用了自定义的模块解析器（custom resolver，例如jest-resolve）。下面的步骤帮你判断属于哪种情况并分别处理。

先判断是哪一类原因

两种原因的解决方式完全不同，先确认自己的环境属于哪一种。

第一步，检查 Node.js 版本：

node --version

• 文档指出该报错会出现在 Node.js 版本低于 14 的环境中，并且 Puppeteer 明确不支持已废弃的 Node.js 版本（"we do not support deprecated versions of Node.js"）。
• 另外，本仓库当前源码中 packages/puppeteer/package.json 的engines字段声明为"node": ">=22.12.0"，也就是说如果你跟随仓库最新代码使用 Puppeteer，运行环境的 Node 版本要求比文档提到的 14 更高。以你实际安装/构建版本对应的要求为准。

第二步，检查是否使用了自定义模块解析器。典型场景是用 Jest 跑 Puppeteer 测试时，项目里配置了jest-resolve一类的自定义 resolver（通过 Jest 的resolver选项等）。如果你没有配置任何自定义解析器，基本可以排除这类原因。

情况一：Node.js 版本过低

如果你确认 Node 版本低于上述要求，处理方式就是升级 Node.js 到受支持的版本（不低于 14，按当前仓库源码要求则应不低于 22.12.0）。Puppeteer 不提供对废弃 Node.js 版本的支持，文档没有给出其他替代方案，因此升级运行环境是唯一路径。

升级完成后，重新安装项目依赖（Node 大版本变化后建议重装，让node_modules与新环境一致）：

npm install

情况二：使用了自定义 resolver（如 jest-resolve）

如果你的 Node 版本符合要求，但项目中使用了自定义模块解析器（文档举的例子是jest-resolve），文档给出的处理方式是：升级 resolver 本身，或升级它的父模块。

例如在 Jest 场景中，升级jest这类父模块通常就能解决（文档引用了 Puppeteer 官方 issue #9121 作为佐证）。也就是说：

npm install jest@latest

如果 resolver 是独立安装的包（如jest-resolve），则升级该包。文档原文表述为 "usually upgrading the resolver (or its parent module such asjest) will work"，即这是通常有效的做法。

验证是否修复

修复的验证方式就是重跑之前触发报错的代码路径：

node <你的脚本.js> # 或 npx jest <你的测试文件>

判断标准只有一个：之前抛出Cannot find module 'puppeteer-core/internal/...'的那次加载/执行不再报这个错，Puppeteer 可以正常加载。如果升级后仍然报同样的错，回到第一步重新确认 Node 版本和是否存在自定义 resolver 配置。

限制说明

• 该报错的成因文档中只列了这两类：Node.js 版本过低、使用自定义 resolver。如果两者都不符合，文档没有覆盖你的情况，建议直接向 Puppeteer 项目提交 issue，而不是继续按本文猜测。
• Node.js 版本要求以你安装的 Puppeteer 版本对应的声明为准（本仓库当前源码声明>=22.12.0），不要仅按 troubleshooting 文档中提到的"14"来设定下限。

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer