使用Puppeteer启动Chrome时提示‘manifest文件缺失或无法读取’

问题概述 #

启动有头Chrome时，持续出现扩展加载失败错误，提示「Failed to load extension from: [路径]. Manifest file is missing or unreadable.」
错误截图：

当前使用代码：

//....
let pathToExtension = require('path').join(__dirname, 'ext'); // 无效
// pathToExtension 尝试过以下路径均无效：应用目录、Chrome扩展目录、Chrome用户数据目录...
pathToExtension = `E:/ext`
browser = await puppeteer.launch({
  headless: false, //true,
  executablePath: executablePath, 
  args: [`--disable-extensions-except=${pathToExtension}'`,
      `--load-extension=${pathToExtension}`,
     // ignoredDefaultArgs: ['--disable-extensions'], 
     // 本以为该配置可允许所有扩展，但无效果
    })
//....

已尝试操作：

• 使用未打包的扩展源码目录
• 同时配置--disable-extensions-except和--load-extension参数
• 参考Puppeteer官方扩展加载文档

特殊情况：切换为headless: true后错误消失，但业务需要有头模式，官方文档明确说明Chrome扩展支持非无头（有头）模式和实验性无头模式，因此有头模式应可正常工作。

解决方案 #

1. 修复参数语法错误 #

代码中--disable-extensions-except参数末尾多了一个单引号'，这会直接导致路径解析失败，修正后参数：

args: [
  `--disable-extensions-except=${pathToExtension}`,
  `--load-extension=${pathToExtension}`
]

2. 确认扩展路径有效性 #

• 路径必须指向直接包含manifest.json的未打包扩展根目录，不能是嵌套目录
• Windows路径建议用path.resolve生成标准绝对路径，避免转义问题：

const path = require('path');
const pathToExtension = path.resolve(__dirname, 'ext'); // 确保ext目录下直接有manifest.json

3. 禁用默认的扩展禁用参数 #

Puppeteer默认会添加--disable-extensions参数，需显式忽略该默认配置：

browser = await puppeteer.launch({
  headless: false,
  executablePath: executablePath,
  ignoredDefaultArgs: ['--disable-extensions'],
  args: [
    `--disable-extensions-except=${pathToExtension}`,
    `--load-extension=${pathToExtension}`
  ]
})

4. 关于「实验性Chrome无头模式」的说明 #

官方提到的实验性无头模式是Chrome 96+支持的headless: "new"模式，该模式行为更接近有头Chrome，也支持扩展加载，若有需求可尝试：

browser = await puppeteer.launch({
  headless: "new", // 实验性无头模式
  executablePath: executablePath,
  args: [
    `--disable-extensions-except=${pathToExtension}`,
    `--load-extension=${pathToExtension}`
  ]
})

5. 额外排查点 #

• 检查扩展目录的读取权限，确保运行Puppeteer的用户有权访问该目录
• 确认Chrome/Chromium版本与Puppeteer版本兼容，优先使用Puppeteer自动下载的Chromium，避免本地Chrome版本不匹配问题

内容的提问来源于stack exchange，提问作者marko-36