Browserless：一行 Docker 命令起一个无头浏览器服务｜部署与使用全指南

Browserless 把「在服务器上跑 Chrome / Firefox」这件破事封装成一个 Docker 容器：你只管写 Puppeteer 或 Playwright 脚本，通过 ws:// 连过来用，字体、依赖、崩溃重启、并发队列、调试查看器它都帮你管好了。开源版自托管免费，云版与企业版额外提供反检测、住宅代理、Session 回放等高级能力。

1. 项目简介与定位

官方一句话：Deploy headless browsers in Docker. Run on our cloud or bring your own. 它解决的是「在 CI / 服务器上跑 Chrome 总是缺字体、随机崩溃、依赖地狱、Lambda 超时」这类问题。

1.1 核心信息一览

1.2 适用场景

• 已经有 Puppeteer / Playwright 脚本，想把浏览器从本地开发机搬到服务器。
• 在 CI 里跑端到端测试或 PDF / 截图任务，不想每个 runner 都装一遍 Chrome。
• 需要在一个常驻服务里集中管理并发、队列、超时，而不是每个任务起一个 Chrome。
• 想给内部团队一个「浏览器即服务」端点，脚本直接 puppeteer.connect({browserWSEndpoint}) 就能用。

1.3 能力边界（官方口径）

• 开源版提供核心浏览器自动化能力：并发与队列、调试查看器、字体与 emoji、超时配置、Chrome 崩溃不影响服务、ARM64 支持。
• BrowserQL 反检测、住宅代理、Session 回放、Chrome 扩展、MCP Server、/smart-scrape /crawl /map /search REST API 这些是 Cloud / Enterprise 专属，开源镜像里没有。
• 商用闭源系统内置 Browserless 需要购买商业许可。

2. 开源协议

仓库原文：SPDX-License-Identifier: SSPL-1.0 OR Browserless Commercial License。

• SSPL-1.0：MongoDB 那一套 Server Side Public License。如果你只是把它当内部浏览器服务用、不对外卖「Browserless 即服务」，一般不触发开源义务；但如果你想把它打包成自己的云产品卖给客户，必须开源整个服务栈或购买商业许可。
• 商业许可：允许闭源商用、企业内网部署、修改源码、使用新版管理后台，并获得官方优先级支持。

3. 官方仓库与链接

• 仓库：https://github.com/browserless/browserless
• 文档：https://docs.browserless.io
• Docker Hub：https://hub.docker.com/r/browserless/chrome
• 云服务：https://browserless.io
• 状态页：https://status.browserless.io
• 联系方式：support@browserless.io

4. 前置要求

• 一台装了 Docker 的机器（Linux / macOS / Windows 均可）。
• 内存建议 ≥ 2GB（每个浏览器实例会占用 300–500MB）。
• 开放 3000 端口（或你 -p 映射的端口）。
• 写脚本的一侧：Node.js ≥ 18，并安装 puppeteer-core 或 playwright-core（注意是 core 版，不需要再下 Chromium）。

5. 安装部署

5.1 一行命令起 Chromium（README 原文）

docker run -p 3000:3000 ghcr.io/browserless/chromium

启动后：

• 文档：http://localhost:3000/docs
• WebSocket 端点：ws://localhost:3000

5.2 跑 Firefox 或多浏览器镜像

README 原文：Use ghcr.io/browserless/firefox or ghcr.io/browserless/multi for Firefox/Webkit support.

# 仅 Firefox
docker run -p 3000:3000 ghcr.io/browserless/firefox

# Chromium + Firefox + WebKit 三合一
docker run -p 3000:3000 ghcr.io/browserless/multi

5.3 守护化运行（生产建议）

docker run -d \
  --name browserless \
  --restart unless-stopped \
  -p 3000:3000 \
  ghcr.io/browserless/chromium

反向代理（Nginx / Caddy）把 3000 套上 HTTPS；如果对公网开放，务必加鉴权（详见官方文档 Auth 章节），否则任何人都能用你的服务器开浏览器。

6. 最小示例代码

6.1 Puppeteer 接入（README 原文）

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://localhost:3000',
});

const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

输出：

Example Domain

6.2 Playwright 接入（README 原文）

import pw from 'playwright-core';

const browser = await pw.firefox.connect(
  'ws://localhost:3000/firefox/playwright',
);

const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

注意：用 Chromium 镜像时连 ws://localhost:3000；用 multi 镜像时按浏览器走对应子路径（/chromium/playwright、/firefox/playwright、/webkit/playwright）。

6.3 脚本一侧的依赖安装

npm install puppeteer-core
# 或
npm install playwright-core

不要再 npx puppeteer browsers install chrome —— 浏览器跑在容器里，本地不需要 Chrome。

7. 配置项说明

README 提到的可配置项（完整环境变量表见 LEARN_MORE.md 与官方文档）：

启动时挂载：

docker run -p 3000:3000 \
  -e CONCURRENT=10 \
  -e TOKEN=your-secret-token \
  ghcr.io/browserless/chromium

带 token 后，客户端连接串变成 ws://localhost:3000?token=your-secret-token。

8. 常见问题

Q1：连接报 ECONNREFUSED？ 确认容器在跑（docker ps）、端口映射对（docker port browserless）、防火墙放通 3000。

Q2：页面截图缺中文字体 / emoji？ README 明示开源镜像「All system fonts and emoji support out-of-the-box」。如果还是缺，多半是你自己在脚本里 page.screenshot() 渲染的页面字体依赖网络下载，被浏览器无网络模式挡了。

Q3：ARM Mac 上能跑吗？ README：ARM64 architecture support — Full support for ARM64 platforms including Apple Silicon; some browsers (Edge, Chrome) have limited ARM64 compatibility. Chromium / Firefox 没问题。

Q4：Chrome 崩了会把服务带崩吗？ README：If Chrome crashes, Browserless won't. 单页崩溃只影响当前会话。

Q5：能直接 REST 拿 HTML / PDF / 截图吗？ 开源镜像提供基础 /function、/screenshot、/pdf、/content 等 HTTP 路由；/smart-scrape /crawl /map /search 是企业版。

Q6：SSPL 到底能不能商用？ 只在公司内部当浏览器服务用、不对外售卖「浏览器云」，通常没问题；要做成对外产品请购买商业许可。

9. 与同类工具对比

10. 许可

SSPL-1.0 或 Browserless Commercial License 二选一。SSPL copyleft 范围覆盖整个服务栈；商用闭源请购买商业许可。

11. 责任使用声明

用 Browserless 起的浏览器去做自动化时，请遵守：

1. 尊重目标站点 robots.txt 与服务条款，不要用无头浏览器伪装真人绕过反爬声明。
2. 合理设置并发与延时，不要把容器当成批量压测机。
3. 不绕过登录墙、付费墙、验证码去获取付费内容。
4. 不批量采集个人隐私数据（评论、私信、通讯录等）。
5. 仅将自动化用于公开数据、合法测试与个人学习研究。
6. 尊重原网站内容版权，截图 / 抓取结果二次发布时遵守原站点授权要求。