在浏览器中运行 Puppeteer浏览器端连接远程浏览器的完整指南【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本指南讲解如何在网页客户端浏览器中直接运行 Puppeteer API利用打包器产出浏览器兼容的构建产物再通过 WebSocket 连接一个已开启调试端口的远程浏览器实例从而在纯前端环境下完成页面管理、脚本执行、截图与 PDF 生成、Cookie 与网络控制等自动化任务。读完本文你将掌握浏览器端专用入口的导入方式、rollup 打包配置、WebSocket 端点获取方法并理解为什么在浏览器中运行不等于在浏览器中启动浏览器。概念与架构Puppeteer 为何能在浏览器中运行Puppeteer 通常被视为 Node.js 专属的浏览器自动化工具但它的 API 设计实际上分层清晰puppeteer-core的核心价值在于协议客户端——通过与浏览器建立调试连接、收发 CDPChrome DevTools Protocol或 WebDriver BiDi 消息来驱动浏览器。而真正依赖 Node.js 的部分仅仅是启动浏览器进程launch、下载浏览器、读写本地文件这些需要操作系统能力的环节。因此当任务不涉及 Node.js 特有功能时Puppeteer API 完全可以运行在浏览器自身环境中从浏览器内发起puppeteer.connect({ browserWSEndpoint })通过 WebSocket 协议连上另一个独立的浏览器进程浏览器环境原生自带WebSocket与fetch恰好能满足协议通信需求见 BrowserWebSocketTransport 源码其中直接使用全局WebSocket对象建立连接依赖 Node.js 的启动、下载能力在浏览器端不可用也无法被 polyfill。:::note 需要特别澄清的是虽然 Puppeteer API 可以从一个客户端网页上运行但自动化指令是发送给另一个开启了调试端口的独立浏览器的并非在承载该网页的浏览器里进行自自动化。 :::浏览器端支持的完整功能列表在浏览器中运行时Puppeteer 提供的功能与原文档一致主要包括以下六类WebSocket 连接Supported通过 WebSocket 连接已存在的浏览器实例。由于launch()与浏览器下载依赖 Node.js API在浏览器端不被支持。脚本求值Supported在远端浏览器的页面上下文中执行 JavaScript 代码即page.evaluate()、evaluateHandle()等能力。文档处理Supported对远端浏览器页面生成 PDF 与截图。页面管理Supported在远端浏览器中创建、关闭页面并在页面间导航。Cookie 处理Supported在远端浏览器中检查、修改与管理 Cookie。网络控制Supported监听并拦截远端浏览器发起的网络请求。简言之凡是与已连接浏览器交互的能力都完整保留凡是需要本机进程管理的能力launch、download、trimCache、默认浏览器查找等都会缺失这从浏览器端入口的源码结构可以推断——puppeteer-core-browser.ts 以isPuppeteerCore: true构造Puppeteer实例仅导出connect一个顶层方法而浏览器下载、启动相关的默认浏览器逻辑不在该入口导出范围。在浏览器中运行 Puppeteer 的完整步骤整体流程分三步导入浏览器端专用入口 → 用打包器产出浏览器兼容 bundle → 将 bundle 引入网页。以下是每一步的详细说明。第一步导入浏览器专用入口当导入 Puppeteer 时必须使用puppeteer-core的浏览器专用入口文件而不是默认的 Node.js 入口import puppeteer from puppeteer-core/lib/puppeteer/puppeteer-core-browser.js; const browser await puppeteer.connect({ browserWSEndpoint: wsUrl, }); alert(Browser has (await browser.pages()).length pages); browser.disconnect();该入口被声明在 puppeteer-core/package.json 的browser字段中指向./lib/puppeteer/puppeteer-core-browser.js打包器rollup/webpack 等可以据此自动解析出浏览器版本。入口源码位于 packages/puppeteer-core/src/puppeteer-core-browser.ts其核心是const puppeteer new Puppeteer({ isPuppeteerCore: true, }); export const { connect, } puppeteer; export default puppeteer;从源码可见浏览器端实际可获得的核心方法正是connect同时仍以具名与 default 两种方式导出方便不同打包/导入风格。它再转导出 index-browser.ts 中的全部 API 类型与实现CDP、公共 API、工具函数等。第二步使用打包器构建浏览器兼容产物由于puppeteer-core源码使用 Node 风格模块解析与条件导出直接放入script typemodule无法运行必须先用 rollup 或 webpack 之类的打包器处理。以下配置可直接用于 rollup与官方示例 rollup.config.mjs 一致import {nodeResolve} from rollup/plugin-node-resolve; export default { input: main.mjs, output: { format: esm, dir: out, }, // 如果不需要使用 WebDriver BiDi 协议 // 排除 chromium-bidi/lib/bidiMapper/BidiMapper.js 以最小化打包体积。 external: [chromium-bidi/lib/bidiMapper/BidiMapper.js], plugins: [ nodeResolve({ // 声明目标是浏览器环境。 browser: true, // 除 puppeteer-core 外不解析任何其他依赖。 // 如有需要执行 npm install puppeteer-core 安装。 resolveOnly: [puppeteer-core], }), ], };配置中的三个关键点值得展开browser: true告诉rollup/plugin-node-resolve优先使用依赖包中面向浏览器的导出条件即上面提到的package.jsonbrowser字段这是打包出可运行 bundle 的前提。resolveOnly: [puppeteer-core]限制只解析puppeteer-core及其内部依赖避免把 Node.js 生态的无关依赖误打入浏览器包。external剔除chromium-bidipuppeteer-core同时支持 CDP 与 WebDriver BiDi 两种协议。若你的连接只走 CDP即connect({ browserWSEndpoint })默认场景WebDriver BiDi 的映射逻辑不会被用到可在打包时将其声明为 external从而显著缩小产物体积。:::note 连接远端浏览器实例时不要忘记提供有效的浏览器 WebSocket 端点即browserWSEndpoint。 :::第三步将产物引入网页打包完成后把生成的 bundle 以script typemodule引入页面。官方完整示例的页面结构如下见 index.html!doctype html script typemodule srcout/main.min.js /script label spanWebSocket URL/span input idws / /label button onclickonConnectClick()Connect/button配合的入口脚本 main.mjs 会在点击按钮时读取输入框中的 WebSocket URL、连接浏览器并弹出当前页数后断开import puppeteer from puppeteer-core/lib/puppeteer/puppeteer-core-browser.js; async function onConnectClick() { const wsUrl document.querySelector(#ws).value; const browser await puppeteer.connect({ browserWSEndpoint: wsUrl, }); alert(Browser has (await browser.pages()).length pages); browser.disconnect(); } globalThis.onConnectClick onConnectClick;官方示例的完整工程位于 examples/puppeteer-in-browser其中 package.json 给出了实用的生产构建脚本scripts: { build: rm -rf out rollup -c terser out/main.js --compress --mangle --output out/main.min.js gzip -k --best -r -f out }该脚本依次完成清空旧产物 → rollup 打包 ESM → terser 压缩混淆 → 对产物做 gzip 预压缩便于部署到静态服务器后由支持压缩的 Web 服务器直接提供服务。开发依赖为rollup/plugin-node-resolve、rollup与terser若尚未安装puppeteer-core需先执行npm install puppeteer-core才能被resolveOnly解析。获取远端浏览器的 WebSocket 端点浏览器端只能连接而无法启动浏览器因此你需要事先在一个支持远程调试的浏览器上获得 WebSocket 端点常见途径以远程调试模式启动 Chrome/Chromium 后从http://localhost:PORT/json/version的webSocketDebuggerUrl字段读取或使用--remote-debugging-pipe/--remote-debugging-port9222等参数若被连接方是 Firefox则对应 WebDriver BiDi 的 WebSocket 端点连接方需保证网络可达且服务端允许跨域 WebSocket 连接涉及 CORS/混合内容等限制详见仓库 webdriver-bidi 指南 与 browser-management 指南。获取到端点后将其填入页面的#ws输入框并点击 Connect 即可验证连接是否成功。底层原理与工程注意点浏览器端依赖原生 WebSocket在浏览器运行时连接传输层直接使用浏览器内置的全局WebSocket对象。这一点可通过 BrowserWebSocketTransport.ts 的实现得到印证它并不引入 Node.js 的ws库而是监听open、message、close、error事件完成双向消息收发因此天然适配浏览器环境。两种协议的可选性影响打包体积index-browser.ts同时导出 CDP 与公共 API而 BiDi 依赖则通过 rollup 的external按需排除。可以推断若你的自动化链路使用 CDP默认排除 BiDi 是控制 bundle 体积的有效手段。connect是浏览器端主入口connect是连接的核心 API支持传入browserWSEndpointWebSocket 地址或transport自定义连接传输层参考 ConnectOptions.ts 的类型定义。浏览器端通常使用前者后者适合需要自定义消息封装的场景。安全与部署提醒让任意网页连接你的调试端口存在安全风险生产环境务必通过鉴权、内网隔离或临时调试令牌等手段保护该端口浏览器端构建还会受混合内容策略限制——若你的页面是 HTTPS则 WebSocket 端点也必须是wss://加密地址。保持仓库内示例的一致性文中所有代码片段与 examples/puppeteer-in-browser 目录下的官方示例一一对应可作为可运行参照若想深入了解connect的完整连接流程与协议握手细节可进一步阅读 BrowserConnector 相关测试 与 ConnectOptions 类型定义。小结在浏览器中运行 Puppeteer 的价值在于将协议驱动的自动化能力嵌入 Web 前端免去 Node.js 服务端的部署开销适用于网页内触发的远程浏览器管理场景。记住三个硬性约束必须使用浏览器专用入口puppeteer-core/lib/puppeteer/puppeteer-core-browser.js必须经由打包器产出浏览器兼容构建只能connect而无法launch/下载浏览器。六类核心能力WebSocket 连接、脚本求值、文档处理、页面管理、Cookie、网络控制在浏览器端均完整可用而启动浏览器等 Node.js 专属能力不在支持范围。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考