Puppeteer需显式配置--load-extension等参数并禁用安全限制才能启用插件；Playwright需复用Chrome用户数据目录；Browserless可通过WebSocket注入扩展；均需验证runtime.id或页面响应确认生效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 Puppeteer 或 Playwright 进行自动化操作时，发现浏览器插件（如自定义扩展、拦截器、Cookie 管理工具等）无法启用，则可能是由于默认启动模式禁用了扩展加载机制或路径配置错误。以下是解决此问题的步骤：
一、启用 Chromium 扩展支持（Puppeteer）
Puppeteer 默认以无扩展模式启动 Chromium，需显式指定加载路径并禁用安全限制，才能使插件生效。该方法适用于本地调试含插件的自动化流程。
1、将插件目录（如 unpacked extension 文件夹）复制到项目根目录下，确保路径不含中文与空格。
2、在 launch 配置中添加 --load-extension 参数，并设置 --disable-extensions-except 指向该路径。
3、同时必须加入 --disable-web-security 和 --user-data-dir 参数，否则扩展可能因沙箱策略被拒绝加载。
4、完整启动代码示例：
const browser = await puppeteer.launch({
args: [
'--load-extension=./my-extension',
'--disable-extensions-except=./my-extension',
'--disable-web-security',
'--user-data-dir=/tmp/puppeteer-user-data'
],
headless: false
});
二、Playwright 中加载 unpacked 扩展（Chromium）
Playwright 原生不支持直接加载 unpacked 扩展，但可通过复用已配置好扩展的 Chrome 用户配置目录实现等效效果。该方式绕过 Playwright 的纯净启动限制，保留真实用户环境中的插件状态。
1、手动启动一次 Chrome 浏览器，安装所需插件并确认其在 chrome://extensions 页面中显示为“已启用”。
2、记录当前 Chrome 的用户数据目录路径：
Windows：C:\Users\[用户名]\AppData\Local\Google\Chrome\User Data
macOS：~/Library/Application Support/Google/Chrome
Linux：~/.config/google-chrome
3、在 Playwright 脚本中使用 launchPersistentContext 并指定 userDataDir 为上述路径。
4、关键提示：必须关闭所有正在运行的 Chrome 实例，否则 userDataDir 将被锁定，Playwright 启动失败。
三、使用 Browserless 服务托管带插件的浏览器实例
当本地环境受限（如 CI/CD、Docker 容器、权限隔离）时，可借助 Browserless 服务统一管理含插件的浏览器。Browserless 支持通过 WebSocket 注入扩展配置，实现远程可控的插件启用能力。
1、启动支持多浏览器的 Browserless multi 镜像：
docker run -p 3000:3000 ghcr.io/browserless/multi
2、向 /chromium/launch 接口发送 POST 请求，body 中包含 extensions 字段，值为 base64 编码的 .crx 文件内容或指向可访问 URL 的数组。
3、在 Puppeteer 客户端中使用 connect() 替代 launch()，并传入 wsEndpoint 值，例如 ws://localhost:3000/chromium
4、注意：Browserless 默认不启用插件支持，需在启动命令中添加 --enable-extensions 标志。
四、验证插件是否实际注入成功
仅配置参数不足以确保插件运行，必须通过页面上下文检查其 DOM 注入痕迹或后台脚本执行状态。该步骤用于排除配置生效但功能未触发的问题。
1、在 Page 实例中执行 evaluate()，检查 window.chrome?.runtime?.id 是否存在。
2、访问 chrome-extension://[extension-id]/popup.html 页面，捕获响应状态码，200 表示插件资源可访问。
3、监听 console 消息，过滤包含插件名称或 background.js 输出的日志，确认后台脚本已启动。
4、若插件依赖特定网页权限（如 activeTab、scripting），需在 manifest.json 中声明且在 runtime.requestPermissions 中动态申请。
五、规避常见权限与路径陷阱
操作系统级限制和文件系统权限常导致插件加载静默失败。该方法聚焦于排查底层环境障碍，而非代码逻辑问题。
1、在 Linux/macOS 上检查插件目录权限，确保浏览器进程拥有 read+execute 权限：
chmod -R 755 ./my-extension
2、Windows 用户需禁用 Windows Defender 实时保护，某些插件文件（尤其是 background.js）会被误判为潜在威胁并拦截。
3、避免使用相对路径 ./ 或 ../ 加载扩展；Puppeteer/Playwright 在不同工作目录下解析行为不一致，应使用 path.resolve(__dirname, 'my-extension') 获取绝对路径。
4、Puppeteer v22+ 与 Playwright v1.40+ 已废弃 --load-extension 对 headless=new 模式的兼容性，必须搭配 headless: false 使用。
