Lightpanda：从零用 Zig 构建的 AI 专用无头浏览器

为 AI Agent 和自动化从零打造的无头浏览器。不是 Chromium 分支，不是 WebKit 补丁。是一台全新的浏览器，使用 Zig 编写。

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

安装

Homebrew（最新 nightly 版）

brew install lightpanda-io/browser/lightpanda

Arch Linux User Repository（最新 nightly 版）

yay -S lightpanda-nightly-bin

二进制下载

可从 nightly builds 下载 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 二进制。在 WSL 内按上述 Linux 步骤安装。

没有安装 WSL？以管理员身份运行 wsl --install，然后重启并打开 wsl。参见微软的 WSL 安装指南。

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

Docker

Lightpanda 提供官方 Docker 镜像，支持 Linux amd64 和 arm64 架构。以下命令拉取镜像并启动新容器，将 Lightpanda 的 CDP server 暴露在 9222 端口。

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，或用 --dump png > page.png / --dump pdf > page.pdf 获取纯文本质的页面渲染。支持 --wait-until、--wait-ms、--wait-selector 和 --wait-script 调整抓取前的等待时间。

serve：启动 CDP Server

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

CDP server 启动后，可通过配置 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();

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：自然语言驱动浏览器

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

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

agent 会话的输出是一份 PandaScript：基于 Lightpanda 原生浏览器原语的纯 JavaScript。用 /save 从当前会话导出一份，然后用 lightpanda run <script>.js 回放。脚本是确定性的且不消耗 token，你可以在开发时用 LLM 原型验证，然后无需在生产环境运行模型即可交付。

支持 Anthropic、OpenAI、Gemini、Google Vertex AI、Mistral、Hugging Face、Vercel AI Gateway（一个 key 访问数百个模型）、任何通过 OPENAI_BASE_URL 的 OpenAI 兼容端点，以及通过 Ollama 或 llama.cpp 的本地模型。也可以用 --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 run session.js                           # run a recorded script
./lightpanda agent --provider gemini --task "..."     # force a specific provider
./lightpanda agent --list-models                      # models available for the detected 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
AI_GATEWAY_API_KEY=... ./lightpanda agent --provider vercel --model moonshotai/kimi-k2   # any model behind Vercel AI Gateway
OPENAI_BASE_URL=https://my-gateway/v1 OPENAI_API_KEY=... ./lightpanda agent            # any OpenAI-compatible server

MCP Server

MCP server 通过 stdio 上的 MCP JSON-RPC 2.0 通信。

添加到你的 MCP 配置：

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

要为多个 Agent 从一个进程提供服务，可通过指定端口启动基于 HTTP 的 MCP server（加 --host x.x.x.x 指定监听接口）：

lightpanda mcp --port 9223

客户端向 http://host:9223/mcp 发送 JSON-RPC。每个连接会被路由到自己的浏览会话——独立的页面、cookie 和内存——所以 Agent 之间不会互相干扰：

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

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

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

阅读完整文档

A skill is available in lightpanda-io/agent-skill.

遥测

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

设置 LIGHTPANDA_DISABLE_CORE_DUMP（任意值）可在启动时通过将软 RLIMIT_CORE 置零来禁止崩溃 core dump。

已实现的核心特性

完整详情见 Web Platform Tests 结果。

• CORS（通过 --experimental-features cors 启用）
• HTTP loader（Libcurl）
• HTML parser（html5ever）
• JavaScript 支持（v8）
• Ajax XHR
• API Fetch
• DOM 和 Markdown dump
• CDP/WebSocket server
• 通过 --obey-robots 遵循 robots.txt
• CDP 和 Webdriver Bidi

从源码构建

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

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，debug 环境用 make build-dev。

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

v8 snapshot

Lighpanda 使用 v8 snapshot。默认在启动时创建，但可以通过以下命令嵌入：

生成 snapshot：

zig build snapshot_creator -- src/snapshot.bin

使用 snapshot 二进制构建：

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

更多细节见 #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

运行端到端测试需要先 clone demo 仓库到 ../demo 目录。

需要安装 demo 的 node 依赖，还需要安装 Go > v1.24。

make end2end

Web Platform Tests

Lightpanda 基于标准化的 Web Platform Tests 进行测试。

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

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

要运行测试，需要 clone 仓库、配置自定义 hosts 并生成 MANIFEST.json。

用 fork 分支 clone 仓库：

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/ 目录。需要先 clone 该项目。

首先从你的 wpt/ clone 目录启动 WPT 的 HTTP server：

./wpt serve

运行 Lightpanda 浏览器：

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

然后从 demo 的 clone 目录启动 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、单页应用、无限加载、即时搜索
• JS 框架：React、Vue、Angular 等

Chrome 不是合适的工具

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

• 难以打包、部署和大规模维护
• 无头模式下许多特性并不必要

Lightpanda 为性能而生

要真正高性能地支持 JavaScript，意味着要从零构建而非 fork Chromium：

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