lightpanda-io / browser
本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。
lightpanda-io / browser
Lightpanda Browser is a headless browser built from scratch for AI agents and automation. It is not a Chromium fork or a WebKit patch, but a new browser written in Zig. It is 16x lighter and 9x faster than Chromium.
Lightpanda Browser 是专为 AI 智能体和自动化构建的无头浏览器。它并非 Chromium 的分支，也不是 WebKit 的补丁，而是一款用 Zig 语言编写的全新浏览器。其内存占用比 Chromium 轻 16 倍，运行速度快 9 倍。
Benchmarks
Requesting 933 real web pages over the network on a AWS EC2 m5.large instance. See benchmark details.
基准测试
在 AWS EC2 m5.large 实例上通过网络请求 933 个真实网页。查看基准测试详情。
| Metric | Lightpanda | Headless Chrome | Difference |
|---|---|---|---|
| Memory (peak, 100 pages) | 123MB | 2GB | ~16x less |
| Execution time (100 pages) | 5s | 46s | ~9x faster |
| 指标 | Lightpanda | Headless Chrome | 差异 |
|---|---|---|---|
| 内存（峰值，100 页） | 123MB | 2GB | 约少 16 倍 |
| 执行时间（100 页） | 5s | 46s | 约快 9 倍 |
Quick start
Install Package Managers. Latest nightly from Homebrew: brew install lightpanda-io/browser/lightpanda. Latest nightly from Arch Linux User Repository: yay -S lightpanda-nightly-bin.
快速入门
安装包管理器。Homebrew 最新每日构建版：brew install lightpanda-io/browser/lightpanda。Arch Linux 用户仓库最新每日构建版：yay -S lightpanda-nightly-bin。
Download from the nightly builds
You can download the last binary from the nightly builds for Linux and MacOS for both x86_64 and aarch64. For Linux:
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod a+x ./lightpanda
Verify the binary before running anything: ./lightpanda version. Linux aarch64 is also available.
从每日构建版下载
您可以下载适用于 Linux 和 MacOS（x86_64 和 aarch64 架构）的最新二进制文件。Linux 用户请执行：
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod a+x ./lightpanda
运行前请验证二进制文件：./lightpanda version。同时提供 Linux aarch64 版本。
If you use Nix, you can run Lightpanda directly from the flake without downloading a binary: nix run github:lightpanda-io/browser -- --help. Or pin it as an input in your own flake: { inputs.lightpanda.url = "github:lightpanda-io/browser"; }.
如果您使用 Nix，可以直接从 flake 运行 Lightpanda，无需下载二进制文件：nix run github:lightpanda-io/browser -- --help。或者将其作为输入固定在您自己的 flake 中：{ inputs.lightpanda.url = "github:lightpanda-io/browser"; }。
Note: The Linux release binaries are linked against glibc. On musl-based Linux distributions (Alpine, etc.) the binary fails with cannot execute: required file not found because the glibc dynamic linker is missing. Use a glibc-based base image: the current release binaries need glibc 2.35 (x86_64) or 2.38 (arm64).
注意：Linux 发行版二进制文件链接至 glibc。在基于 musl 的 Linux 发行版（如 Alpine 等）上，由于缺少 glibc 动态链接器，二进制文件会报错 cannot execute: required file not found。请使用基于 glibc 的基础镜像：当前的发行版二进制文件需要 glibc 2.35 (x86_64) 或 2.38 (arm64)。
Android / Termux: there is no native Android build. The Linux aarch64 binary needs the glibc loader (/lib/ld-linux-aarch64.so.1), which Android’s Bionic libc does not provide, so it fails with the same cannot execute: required file not found error.
Android / Termux：目前没有原生 Android 构建版本。Linux aarch64 二进制文件需要 glibc 加载器 (/lib/ld-linux-aarch64.so.1)，而 Android 的 Bionic libc 不提供该加载器，因此会报同样的 cannot execute: required file not found 错误。
For MacOS:
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && chmod a+x ./lightpanda
MacOS x86_64 is also available.
MacOS 用户请执行：
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && chmod a+x ./lightpanda
同时提供 MacOS x86_64 版本。
For Windows + WSL2: Lightpanda has no native Windows binary. Install it inside WSL following the Linux steps above. WSL not installed? Run wsl --install from an administrator shell, restart, then open wsl. See Microsoft’s WSL install guide for details. Your automation client (Puppeteer, Playwright, etc.) can run either inside WSL or on the Windows host. WSL forwards localhost:9222 automatically.
Windows + WSL2：Lightpanda 没有原生 Windows 二进制文件。请按照上述 Linux 步骤在 WSL 中安装。尚未安装 WSL？请在管理员 shell 中运行 wsl --install，重启后打开 wsl。详情请参阅微软的 WSL 安装指南。您的自动化客户端（Puppeteer、Playwright 等）既可以在 WSL 内部运行，也可以在 Windows 主机上运行。WSL 会自动转发 localhost:9222。
Install from Docker
Lightpanda provides official Docker images for both Linux amd64 and arm64 architectures. The following command fetches the Docker image and starts a new container exposing Lightpanda’s CDP server on port 9222.
docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest
通过 Docker 安装
Lightpanda 为 Linux amd64 和 arm64 架构提供官方 Docker 镜像。以下命令将拉取 Docker 镜像并启动一个新容器，将 Lightpanda 的 CDP 服务器暴露在 9222 端口。
docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest
Dump a URL
./lightpanda fetch --obey-robots --dump html --log-format pretty --log-level info https://demo-browser.lightpanda.io/campfire-commerce/
You can use --dump markdown to convert directly into markdown, or --dump png > page.png or --dump pdf > page.pdf for a text-only rendering of the page. --dump structured_data prints the page’s JSON-LD, OpenGraph, Twitter card, meta and link tags as JSON, like the MCP structuredData tool. --wait-until, --wait-ms, --wait-selector and --wait-script are available to adjust waiting time before dump.
转储 URL
./lightpanda fetch --obey-robots --dump html --log-format pretty --log-level info https://demo-browser.lightpanda.io/campfire-commerce/
您可以使用 --dump markdown 直接转换为 markdown，或使用 --dump png > page.png 或 --dump pdf > page.pdf 获取页面的纯文本渲染。--dump structured_data 会像 MCP structuredData 工具一样，以 JSON 格式打印页面的 JSON-LD、OpenGraph、Twitter 卡片、meta 和 link 标签。--wait-until、--wait-ms、--wait-selector 和 --wait-script 可用于调整转储前的等待时间。
Start a CDP server
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222
To listen on a Unix-domain socket (owner-only, mode 0600) instead of TCP:
./lightpanda serve --unix-socket /run/user/1000/lightpanda.sock
启动 CDP 服务器
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222
若要监听 Unix 域套接字（仅限所有者，模式 0600）而非 TCP：
./lightpanda serve --unix-socket /run/user/1000/lightpanda.sock
Once the CDP server started, you can run a Puppeteer script by configuring the browserWSEndpoint. Example Puppeteer script:
import puppeteer from 'puppeteer-core';
// use browserWSEndpoint to pass the Lightpanda's CDP server address.
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://127.0.0.1:9222", });
// The rest of your script remains the same.
const context = await browser.createBrowserContext();
const frame = await context.newPage();
// Dump all the links from the frame.
await frame.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle0"});
const links = await frame.evaluate(() => {
return Array.from(document.querySelectorAll('a')).map(row => { return row.getAttribute('href'); });
});
console.log(links);
await frame.close();
await context.close();
await browser.disconnect();CDP 服务器启动后，您可以通过配置 browserWSEndpoint 来运行 Puppeteer 脚本。Puppeteer 脚本示例：
import puppeteer from 'puppeteer-core';
// 使用 browserWSEndpoint 传递 Lightpanda 的 CDP 服务器地址。
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://127.0.0.1:9222", });
// 脚本其余部分保持不变。
const context = await browser.createBrowserContext();
const frame = await context.newPage();
// 转储框架中的所有链接。
await frame.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle0"});
const links = await frame.evaluate(() => {
return Array.from(document.querySelectorAll('a')).map(row => { return row.getAttribute('href'); });
});
console.log(links);
await frame.close();
await context.close();
await browser.disconnect();Start a webdriver Bidi server
Use --protocol webdriver to enable Bidi support. You can start both, CDP and Bidi, with --protocol webdriver --protocol cdp.
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222 --protocol webdriver
启动 webdriver Bidi 服务器
使用 --protocol webdriver 启用 Bidi 支持。您可以同时启动 CDP 和 Bidi，使用 --protocol webdriver --protocol cdp。
./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222 --protocol webdriver
Agent mode
lightpanda agent lets you drive the browser with a native agent. Describe what you want in plain English or with slash commands, and it controls the browser: navigating pages, clicking through flows, filling forms, extracting structured data. Think of it as a robot you’re directing to use the web, more than a chatbot you’re having a conversation with.
智能体模式
lightpanda agent 允许您使用原生智能体驱动浏览器。用简单的英语或斜杠命令描述您的需求，它即可控制浏览器：导航页面、点击流程、填写表单、提取结构化数据。将其视为一个您指挥其使用网络的机器人，而不是一个与您对话的聊天机器人。
Because the agent runs inside the same process as the browser, every tool call is a direct operation and you retain Lightpanda’s speed and memory advantage. The output of an agent session is a PandaScript: vanilla JavaScript with a small set of native browser primitives built directly into Lightpanda. Run /save to export one from your current session, then replay it with lightpanda run <script>.js.
由于智能体与浏览器运行在同一进程中，每次工具调用都是直接操作，因此您保留了 Lightpanda 的速度和内存优势。智能体任务的输出是 PandaScript：一种包含少量直接内置于 Lightpanda 的原生浏览器原语的纯 JavaScript。运行 /save 可从当前会话导出脚本，然后使用 lightpanda run <script>.js 重放它。
Scripts are deterministic and token-free, so you can prototype with the LLM and ship the output to production without a model at runtime. It supports Anthropic, OpenAI, Gemini, Google Vertex AI, Mistral, Hugging Face, the multi-lab gateways Vercel AI Gateway and OpenRouter (one key for hundreds of models), any OpenAI-compatible endpoint via OPENAI_BASE_URL, and local models via Ollama, llama.cpp or LLMD.
脚本是确定性的且无需 Token，因此您可以使用 LLM 进行原型设计，并在运行时无需模型即可将输出部署到生产环境。它支持 Anthropic、OpenAI、Gemini、Google Vertex AI、Mistral、Hugging Face、多实验室网关 Vercel AI Gateway 和 OpenRouter（一个密钥对应数百个模型）、通过 OPENAI_BASE_URL 连接的任何 OpenAI 兼容端点，以及通过 Ollama、llama.cpp 或 LLMD 运行的本地模型。