Heidi Labs
GitHub TrendingGitHub Trending 项目约 23 分钟9,084 字

Lightpanda：为 AI 与自动化打造的无头浏览器

本文目录

Lightpanda 浏览器（Lightpanda Browser）#

从零打造、面向 AI 智能体（AI agents）与自动化的无头浏览器（headless browser）。

不是 Chromium 的分支，也不是 WebKit 的补丁。一个用 Zig 编写的新浏览器。

比 Chromium 轻 16 倍、快 9 倍。

基准测试#

在 AWS EC2 m5.large 实例上通过网络请求 933 个真实网页。详见基准测试详情。

指标LightpandaHeadless Chrome差异
内存（峰值，100 个页面）123MB2GB约少 16 倍
执行时间（100 个页面）5s46s约快 9 倍

快速开始#

安装#

包管理器

Homebrew 提供的最新 nightly：

brew install lightpanda-io/browser/lightpanda

Arch Linux User Repository 提供的最新 nightly：

yay -S lightpanda-nightly-bin

从 nightly 构建下载

你可以从 nightly builds 下载适用于 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 版本。

如果你使用 Nix，可以直接从 flake 运行 Lightpanda，无需下载二进制文件：

nix run github:lightpanda-io/browser -- --help

或将它固定为你自己 flake 的输入：

{
  inputs.lightpanda.url = "github:lightpanda-io/browser";
}

注意：Linux 发行版二进制文件链接的是 glibc。在基于 musl 的 Linux 发行版（Alpine 等）上，由于缺少 glibc 动态链接器，二进制文件会失败并报错 cannot execute: required file not found。请使用基于 glibc 的基础镜像：当前发行版二进制在 x86_64 上需要 glibc 2.35，在 arm64 上需要 2.38，所以 debian:bookworm-slim（2.36）在 x86_64 上没问题，但在 arm64 上太旧——那里请使用 FROM ubuntu:24.04、FROM debian:trixie-slim 或 FROM debian:forky-slim——或者从源码构建。

Android / Termux：没有原生 Android 构建。Linux aarch64 二进制需要 glibc 加载器（/lib/ld-linux-aarch64.so.1），而 Android 的 Bionic libc 不提供该加载器，因此会以同样的 cannot execute: required file not found 错误失败。

MacOS 版本：

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
chmod a+x ./lightpanda

也提供 MacOS x86_64 版本。

Windows + WSL2 版本：

Lightpanda 没有原生 Windows 二进制。请按照上述 Linux 步骤在 WSL 内安装。

未安装 WSL？请在管理员 shell 中运行 wsl --install，重启，然后打开 wsl。详见 Microsoft 的 WSL 安装指南。

你的自动化客户端（Puppeteer、Playwright 等）既可以运行在 WSL 内，也可以运行在 Windows 主机上。WSL 会自动转发 localhost:9222。

从 Docker 安装

Lightpanda 为 Linux amd64 和 arm64 架构提供官方 Docker 镜像。以下命令获取 Docker 镜像并启动一个新容器，在 9222 端口暴露 Lightpanda 的 CDP 服务器。

docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:latest

导出 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 会以 JSON 形式打印页面的 JSON-LD、OpenGraph、Twitter card、meta 和 link 标签，类似 MCP 的 structuredData 工具。--wait-until、--wait-ms、--wait-selector 和 --wait-script 可用于调整导出前的等待时间。

启动 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

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();

// 导出 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();

启动 WebDriver Bidi 服务器#

使用 --protocol webdriver 启用 Bidi 支持。你可以通过 --protocol webdriver --protocol cdp 同时启动 CDP 和 Bidi。

./lightpanda serve --obey-robots --log-format pretty --log-level info --host 127.0.0.1 --port 9222 --protocol webdriver

智能体模式（Agent mode）#

lightpanda agent 让你用一个原生智能体来驱动浏览器。用自然语言或斜杠命令描述你想要什么，它就会控制浏览器：导航页面、点击流程、填写表单、提取结构化数据。可以把它想成你指挥去使用网络的一个机器人，而不是与之对话的聊天机器人。

由于智能体与浏览器运行在同一进程中，每次工具调用都是直接操作，你仍然享有 Lightpanda 的速度和内存优势。

智能体会话的输出是一个 PandaScript：原生 JavaScript，加上一组直接内置于 Lightpanda 的少量原生浏览器原语。运行 /save 从当前会话导出，然后用 lightpanda run <script>.js 重放。脚本是确定性的，且不消耗 token，因此你可以用大语言模型（LLM）做原型，把输出交付到生产环境而无需在运行时使用模型。

它支持 Anthropic、OpenAI、Gemini、Google Vertex AI、Mistral、Hugging Face，多实验室网关 Vercel AI Gateway 和 OpenRouter（一个 key 用数百个模型），通过 OPENAI_BASE_URL 支持任意 OpenAI 兼容端点，以及通过 Ollama、llama.cpp 或 LLMD 使用本地模型。你也可以通过 --no-llm 在没有 LLM 的情况下运行，这会直接进入 REPL。完整参考见智能体文档。

./lightpanda agent # 从环境变量自动检测 API key
./lightpanda agent --task "top story on news.ycombinator.com?"
./lightpanda agent --no-llm # 基础 REPL，不使用 LLM
./lightpanda run session.js # 运行录制的脚本
cat session.js | ./lightpanda run - # ……或通过 stdin 管道传入
./lightpanda agent --provider gemini --task "..." # 强制指定 provider
./lightpanda agent --list-models # 检测到的 provider 可用的模型
VERTEX_API_KEY=... ./lightpanda agent --provider vertex # Vertex AI，express 模式
GOOGLE_CLOUD_PROJECT=my-proj ./lightpanda agent --provider vertex # Vertex AI，通过 gcloud auth 获取 token
AI_GATEWAY_API_KEY=... ./lightpanda agent --provider vercel --model moonshotai/kimi-k2 # Vercel AI Gateway 背后的任意模型
OPENROUTER_API_KEY=... ./lightpanda agent --provider openrouter --model anthropic/claude-sonnet-5 # OpenRouter 背后的任意模型
OPENAI_BASE_URL=https://my-gateway/v1 OPENAI_API_KEY=... ./lightpanda agent # 任何 OpenAI 兼容服务器

原生 MCP 与 skill#

MCP 服务器通过 stdio 上的 MCP JSON-RPC 2.0 通信。

添加到你的 MCP 配置：

{
  "mcpServers": {
    "lightpanda": {
      "command": "/path/to/lightpanda",
      "args": ["mcp"]
    }
  }
}

HTTP 传输与独立会话

要从一个进程服务多个智能体，请通过 HTTP 而不是 stdio 启动 MCP 服务器，为其提供端口（添加 --host x.x.x.x 指定要监听的接口）：

lightpanda mcp --port 9223

客户端向 http://host:9223/mcp POST JSON-RPC。每个连接都路由到自己的浏览会话——自己的页面、cookie 和内存——因此智能体不再互相覆盖页面：

  • 不带 Mcp-Session-Id 头初始化的客户端会被分配一个新会话；该 id 会在响应的 Mcp-Session-Id 头中返回。在后续请求中发送它即可停留在该会话上（隔离）。
  • 两个发送相同 Mcp-Session-Id 的智能体共享一个浏览上下文（共享——例如多个智能体处理同一个页面的工作流）。

session_new、session_list 和 session_close 工具可显式管理会话。发送带 Mcp-Session-Id 的 DELETE /mcp 会关闭该会话。

run 工具在调用者的会话中运行 PandaScript，与 lightpanda run 一样，并返回其控制台输出及其返回值。它接收源代码作为 script，或接收 save 写出的文件路径。脚本打开的页面在结束时关闭；cookie 和存储会保留，因此一次登录会延续到下一次运行。可选的毫秒级 timeout（默认 60000）会停止卡住的脚本。后端可以通过一次 POST 驱动 Lightpanda：

curl -s http://127.0.0.1:9223/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "run", "arguments": { "script":
  "const page = new Page();\nawait page.goto(\"https://example.com\");\nreturn page.extract({ title: \"title\", links: [\"a\"] });" } }
}'

阅读完整文档。

一个 skill 可在 lightpanda-io/agent-skill 中获取。

Shell 补全#

lightpanda completion <bash | fish | zsh> 会为命令、标志及其值打印补全脚本：

lightpanda completion fish > ~/.config/fish/completions/lightpanda.fish
lightpanda completion bash > ~/.local/share/bash-completion/completions/lightpanda
lightpanda completion zsh > ~/.zfunc/_lightpanda # 在 compinit 之前设置 fpath=(~/.zfunc $fpath)

遥测#

默认情况下，Lightpanda 会收集并发送使用遥测数据。可以通过设置环境变量 LIGHTPANDA_DISABLE_TELEMETRY=true 禁用。你可以在以下地址阅读 Lightpanda 的隐私政策：https://lightpanda.io/privacy-policy。

核心转储#

设置 LIGHTPANDA_DISABLE_CORE_DUMP（任意值）可在启动时将软 RLIMIT_CORE 置零，从而抑制崩溃核心转储。

状态#

以下是我们已经实现的关键特性。完整细节见我们的 Web Platform Tests 结果。

  • CORS
  • HTTP 加载器（Libcurl）
  • HTML 解析器（html5ever）
  • DOM 树
  • JavaScript 支持（v8）
  • DOM API
  • Ajax
  • XHR API
  • Fetch API
  • DOM 与 Markdown 导出
  • CDP/WebSockets 服务器
  • 点击
  • 输入表单
  • Cookie
  • 自定义 HTTP 头
  • 代理支持
  • 网络拦截
  • 使用 --obey-robots 选项遵守 robots.txt
  • CDP 与 WebDriver Bidi
  • 广告拦截器

从源码构建#

前提条件

Lightpanda 使用 Zig 0.17.0 编写。你必须安装正确版本才能构建项目。

Lightpanda 还依赖 v8、Libcurl 和 html5ever。

要能构建 v8 引擎，你需要安装一些库：

对于基于 Debian/Ubuntu 的 Linux：

sudo apt install xz-utils ca-certificates \
    pkg-config libglib2.0-dev \
    clang make curl git

你还需要安装 Rust。

对于有 Nix 的系统，你可以使用 devShell。

nix develop

对于 MacOS，你需要 cmake 和 Rust。

brew install cmake

构建并运行

你可以用 make build 构建整个浏览器，或用 make build-dev 构建调试环境。

但你也可以直接使用 zig 命令：zig build run。

嵌入 v8 快照

Lightpanda 使用 v8 快照。默认情况下，它会在启动时创建，但你可以使用以下命令嵌入它：

生成快照。

zig build snapshot_creator -- src/snapshot.bin

使用快照二进制构建。

zig build -Dsnapshot_path=../../snapshot.bin

更多细节见 #1279。

测试

单元测试：

你可以通过运行 make test 测试 Lightpanda。

make test # 运行所有测试
make test F="server" # 按子串过滤
TEST_FILTER="WebApi: #selector_all" make test # 过滤主测试 + 子测试（分隔符：#）
TEST_VERBOSE=true make test
TEST_FAIL_FIRST=true make test
METRICS=true make test # 以 JSON 捕获分配/持续时间指标
TEST_JOBS=1 make test # 在单个进程中运行（默认：最多 4 个，过滤时为 1）

端到端测试：

要运行端到端测试，你需要将 demo 仓库克隆到 ../demo 目录。

你必须安装 demo 的 node 依赖。

你还需要安装 Go > v1.24。

make end2end

Web Platform Tests：

Lightpanda 针对标准化的 Web Platform Tests 进行测试。

我们使用一个包含自定义 testharnessreport.js 的分支。结果每天发布。

作为参考，你可以通过 wpt.live 用你的浏览器执行一个 WPT 测试用例。

配置 WPT HTTP 服务器：

要运行测试，你必须克隆仓库、配置自定义 hosts 并生成 MANIFEST.json 文件。

用 fork 分支克隆仓库。

git clone -b fork --depth=1 git@github.com:lightpanda-io/wpt.git

进入 wpt/ 目录。

在你的 /etc/hosts 中安装自定义域名

./wpt make-hosts-file | sudo tee -a /etc/hosts

生成 MANIFEST.json

./wpt manifest

细节见 WPT 的设置指南。

运行 WPT 测试套件：

外部 Go 运行器由 github.com/lightpanda-io/demo/ 仓库提供，位于 wptrunner/ 目录。你需要先克隆该项目。

首先从你的 wpt/ 克隆目录启动 WPT 的 HTTP 服务器。

./wpt serve

运行一个 Lightpanda 浏览器

zig build -Dwpt_extensions run -- serve \
  --ws-max-concurrent 64 \
  --insecure-disable-tls-host-verification \
  --load-resources iframe \
  --load-resources image \
  --load-resources worker \
  --load-resources stylesheet

然后你可以从 demo 的克隆目录启动 wptrunner：

cd wptrunner && go run .

或运行一个特定测试：

cd wptrunner && go run . Node-childNodes.html

wptrunner 命令接受 --summary 和 --json 选项来修改输出。--concurrency 定义并发限制。

要在没有运行器的情况下检查单个测试用例，fetch --dump wpt 会以 JSON 打印其结果：harness 状态、通过/失败摘要以及未通过的用例。它依赖分支的 testharnessreport.js。

zig build -Dwpt_extensions run -- fetch \
  --insecure-disable-tls-host-verification \
  --load-resources worker \
  --load-resources iframe \
  --dump wpt \
  --wait-script "window.report && report.complete" \
  "http://web-platform.test:8000/dom/nodes/Node-childNodes.html"

⚠️ 运行整个测试套件会耗费很长时间。在这种情况下，以 releaseFast 模式构建以使测试更快会很有用。

zig build -Dwpt_extensions -Doptimize=fast run -- serve ...

贡献#

见 CONTRIBUTING.md 了解指南。你必须在拉取请求（pull request）过程中签署我们的 CLA。

Discord#

为什么选择 Lightpanda？#

JavaScript 执行是现代 Web 的必需品#

简单的 HTTP 请求过去足以应对 Web 自动化。但这已不再是事实。JavaScript 现在驱动着大部分 Web：

  • Ajax、单页应用（SPA）、无限加载、即时搜索
  • JS 框架：React、Vue、Angular 及其他

Chrome 不是正确的工具#

在服务器上运行完整的桌面浏览器可行，但扩展性不佳。Chrome 在数百或数千个实例时成本高昂：

  • 对 RAM 和 CPU 消耗大
  • 难以大规模打包、部署和维护
  • 许多功能在无头模式（headless mode）下并不必要

Lightpanda 为性能而构建#

支持 JavaScript 并实现真正的性能，意味着要从零构建而不是分叉 Chromium：

  • 不基于 Chromium、Blink 或 WebKit
  • 用 Zig 编写，一种具有显式内存控制的低级语言
  • 没有图形渲染引擎