Lightpanda：用Zig写的轻量级无头浏览器

为 AI agents 和自动化从头构建的无头浏览器。不是 Chromium fork。不是 WebKit patch。一个用 Zig 编写的全新浏览器。

在 AWS EC2 m5.large 实例上请求 933 个真实网页。查看基准测试详情。

安装

Homebrew 最新每日构建

brew install lightpanda-io/browser/lightpanda

Arch Linux 用户仓库最新每日构建

yay -S lightpanda-nightly-bin

从每日构建下载

你可以从每日构建中下载最新的二进制文件，支持 Linux 和 MacOS，包括 x86_64 和 aarch64。

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 也可用

注意：Linux 发行版二进制文件链接到了 glibc。在基于 musl 的发行版（Alpine 等）上，二进制文件会因为缺少 glibc 动态链接器而失败，错误为 "cannot execute: required file not found"。使用基于 glibc 的基础镜像（例如 FROM debian:bookworm-slim 或 FROM ubuntu:24.04）或从源代码构建。

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

MacOS x86_64 也可用

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:nightly

使用

fetch 命令

./lightpanda fetch --obey-robots --dump html --log-format pretty  --log-level info https://demo-browser.lightpanda.io/campfire-commerce/

你可以使用 --dump markdown 直接转换成 markdown。--wait-until、--wait-ms、--wait-selector 和 --wait-script 可用于调整 dump 前的等待时间。

serve 命令

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

CDP 服务器启动后，你可以通过配置 browserWSEndpoint 来运行 Puppeteer 脚本。

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

Agent

lightpanda agent 让你用原生 agent 驾驶浏览器。用纯英文或斜杠命令描述你想要的，它就会控制浏览器：导航页面、点击流程、填充表单、提取结构化数据。可以把它看作你指挥它使用网络的机器人，而不是你聊天的对话框。

因为 agent 与浏览器运行在同一进程中，每次工具调用都是直接操作，你保留了 Lightpanda 的速度和内存优势。

agent 会话的输出是一个 PandaScript：使用 Lightpanda 内置的一小组原生浏览器原语的纯 JavaScript。运行 /save 从你的当前会话导出一个，然后用 lightpanda agent <script>.js 重放它。脚本是确定性的且不需要 token，所以你可以用 LLM 原型化然后在生产中使用输出而无需在运行时使用模型。

它支持 Anthropic、OpenAI、Gemini、Google Vertex AI、Hugging Face 和通过 Ollama 的本地模型。你也可以用 --no-llm 运行而不使用 LLM，这会把你放入 REPL。详见 agent 文档了解完整参考。

./lightpanda agent                                    # auto-detects API key from env
./lightpanda agent --task "top story on news.ycombinator.com?"
./lightpanda agent --no-llm                           # basic REPL, no LLM
./lightpanda agent session.js                         # run a recorded script
./lightpanda agent --provider gemini --task "..."     # force a specific provider
VERTEX_API_KEY=... ./lightpanda agent --provider vertex             # Vertex AI, express mode
GOOGLE_CLOUD_PROJECT=my-proj ./lightpanda agent --provider vertex   # Vertex AI, token via gcloud auth

MCP 服务器

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

添加到你的 MCP 配置：

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

为了从一个进程服务多个 agent，通过给它一个端口（添加 --host x.x.x.x 来指定要监听的接口）来在 HTTP 上启动 MCP 服务器：

lightpanda mcp --port 9223

客户端 POST JSON-RPC 到 http://host:9223/mcp。每个连接被路由到它自己的浏览会话——它自己的页面、cookies 和内存——所以 agent 不再互相干扰：

一个初始化时没有 Mcp-Session-Id 头的客户端会被分配一个新会话；id 在响应的 Mcp-Session-Id 头中返回。在后续请求中发送它以保持在该会话中（隔离）。

两个发送相同 Mcp-Session-Id 的 agent 共享一个浏览上下文（共享——例如一个多个 agent 工作同一页面的工作流）。

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

阅读完整文档

lightpanda-io/agent-skill 中提供了一个 skill。

隐私和配置

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

设置 LIGHTPANDA_DISABLE_CORE_DUMP（任何值）来通过在启动时将 soft RLIMIT_CORE 归零来抑制崩溃核心转储。

当前状态

Lightpanda 处于 Beta 阶段，目前仍在开发中。稳定性和覆盖范围正在改进，许多网站现在可以工作。你可能仍然会遇到错误或崩溃。如果是这样，请开一个 issue 并提供具体信息。

以下是我们实现的关键特性：

HTTP loader（Libcurl）

HTML parser（html5ever）

Javascript 支持（v8）

Ajax、XHR API、Fetch API

CDP/websockets 服务器

使用 --obey-robots 选项尊重 robots.txt

注意：有数百个 Web API。开发一个浏览器（即使仅用于无头模式）也是一项巨大的任务。覆盖范围会随时间增长。

构建

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

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 系统

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

nix develop

MacOS

在 MacOS 上，你需要 cmake 和 Rust。

brew install cmake

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

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

Lightpanda 使用 v8 snapshot。默认情况下，它在启动时创建，但你可以通过使用以下命令来嵌入它：

生成 snapshot。

zig build snapshot_creator -- src/snapshot.bin

使用 snapshot 二进制构建。

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

详见 issue #1279。

测试

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

make test                                       # Run all tests
make test F="server"                            # Filter by substring
TEST_FILTER="WebApi: #selector_all" make test   # Filter main + subtest (separator: #)
TEST_VERBOSE=true make test
TEST_FAIL_FIRST=true make test
METRICS=true make test                          # Capture allocation/duration metrics as JSON

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

你必须安装演示的 node 依赖项

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

make end2end

Web Platform Tests

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

我们使用一个包含自定义 testharnessreport.js 的 fork。

作为参考，你可以通过 wpt.live 轻松执行任何 WPT 测试用例。

要运行测试，你必须克隆仓库、配置自定义主机并生成 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 设置指南。

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

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

./wpt serve

运行一个 Lightpanda 浏览器

zig build run -- --insecure-disable-tls-host-verification

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

cd wptrunner && go run .

或一个特定的测试：

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

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

⚠️ 运行整个测试套件将花费很长时间。在这种情况下，用 ReleaseFast 模式构建会更有用以加快测试速度。

zig build -Doptimize=ReleaseFast run

贡献

详见 CONTRIBUTING.md 了解指南。你必须在 pull request 过程中签署我们的 CLA。

为什么 Lightpanda

JavaScript 执行对现代网络至关重要

简单的 HTTP 请求曾经足够用于网络自动化。现在不再是这样了。JavaScript 现在驱动大部分网络：

Ajax、Single Page App、无限加载、即时搜索

JS 框架：React、Vue、Angular 和其他

Chrome 不是正确的工具

在服务器上运行完整的桌面浏览器可以工作，但在规模上不能很好地扩展。数百或数千个 Chrome 实例很昂贵：

难以在规模上打包、部署和维护

许多特性对无头模式来说并不必要

Lightpanda 为性能而构建

用真实的性能支持 JavaScript 意味着从头构建而不是 fork Chromium：

不基于 Chromium、Blink 或 WebKit

用 Zig 编写，一种具有显式内存控制的低级语言

没有图形渲染引擎