Lightpanda 是一个从头开始构建的Headless浏览器，专为AI代理和自动化任务设计。它不是Chromium或WebKit的分支，而是使用Zig语言编写，旨在提供极高的性能和极低的内存占用。根据官方基准测试，在处理100个页面时，其峰值内存仅为123MB，执行时间为5秒，而Headless Chrome分别为2GB和46秒。

本教程将指导您通过多种方式（包管理器、直接下载、Docker）安装和运行Lightpanda。

1. 系统要求

  • 操作系统：Linux（x86_64/arm64）、macOS（x86_64/arm64）或 Windows + WSL2（无原生Windows二进制）。
  • 依赖：Linux下需确保系统为基于glibc的发行版（如Debian、Ubuntu），不支持musl-based发行版（如Alpine）。

2. 安装方法

2.1 使用包管理器（推荐）

Homebrew (macOS 和 Linux)

安装最新的nightly版本：

1
brew install lightpanda-io/browser/lightpanda

Arch Linux AUR

1
2
3
yay -S lightpanda-nightly-bin
# 或使用 paru
paru -S lightpanda-nightly-bin

2.2 直接下载二进制（适用于 Linux 和 macOS）

您可以直接从GitHub的nightly builds下载可执行文件。

Linux (x86_64)

1
2
3
4
5
6
# 下载二进制
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
# 添加执行权限
chmod a+x ./lightpanda
# 验证安装
./lightpanda version

注意：Linux ARM64版本也提供下载。如使用基于musl的发行版，请使用glibc基础镜像（如debian:bookworm-slim）或从源码构建。

macOS (aarch64/Apple Silicon)

1
2
3
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos
chmod a+x ./lightpanda
./lightpanda version

注意：macOS x86_64版本也提供下载。

Windows

需通过 WSL2 (Windows Subsystem for Linux) 使用。在PowerShell（管理员）中运行 wsl --install 安装WSL，然后在WSL中按照Linux步骤操作。

2.3 使用Docker

官方提供了Docker镜像，适用于Linux amd64/arm64：

1
2
# 拉取并运行容器，暴露CDP服务器端口9222
docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:nightly

3. 基本使用

安装后，您可以通过命令行直接使用或启动CDP服务供自动化库调用。

3.1 直接抓取网页内容

获取一个URL的HTML或Markdown内容：

1
2
3
4
5
6
7
8
# 获取HTML
./lightpanda fetch --dump html https://example.com

# 获取Markdown
./lightpanda fetch --dump markdown https://example.com

# 更多选项：等待网络空闲、等待指定选择器等
./lightpanda fetch --obey-robots --dump html --wait-until networkidle0 https://example.com

3.2 启动CDP服务器（供Puppeteer等使用）

启动一个兼容Chrome DevTools Protocol (CDP) 的服务器：

1
./lightpanda serve --host 127.0.0.1 --port 9222

然后，您可以使用 puppeteer-core 连接到它：

1
2
3
4
5
6
7
8
9
10
11
import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: "ws://127.0.0.1:9222",
});

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

3.3 Agent模式（AI驱动）

Lightpanda内置Agent模式，允许您用自然语言描述任务，由AI驱动浏览器操作：

1
2
3
4
5
6
7
8
# 自动检测API Key（需设置ANTHROPIC_API_KEY, OPENAI_API_KEY等）
./lightpanda agent --task "top story on news.ycombinator.com?"

# 指定提供商
./lightpanda agent --provider gemini --task "..."

# 使用本地Ollama模型
./lightpanda agent --provider ollama --task "..."

Agent会话可以保存为 PandaScript 脚本，供后续无需LLM地回放：

1
2
3
# 在agent会话中使用 /save 命令保存脚本
# 然后运行脚本
./lightpanda run session.js

3.4 MCP (Model Context Protocol) 服务器

Lightpanda可作为MCP服务器运行，供支持MCP的客户端调用：

1
2
3
4
5
# stdio模式
./lightpanda mcp

# HTTP模式（端口9223），支持独立会话隔离
./lightpanda mcp --port 9223

客户端可向 http://host:9223/mcp 发送JSON-RPC请求。

4. 高级配置与运维

4.1 配置选项

  • 日志格式：使用 --log-format json 或 pretty。
  • 遵守robots.txt：使用 --obey-robots 标志。
  • 代理支持：通过环境变量 HTTP_PROXY / HTTPS_PROXY 配置。

4.2 遥测与核心转储

  • 禁用遥测：设置环境变量 LIGHTPANDA_DISABLE_TELEMETRY=true。
  • 禁用Core Dump：设置环境变量 LIGHTPANDA_DISABLE_CORE_DUMP（任意值）。

5. 从源码构建（可选）

如需从源码构建，请参考以下步骤。

5.1 前提条件

  • Zig：版本 0.15.2。
  • 依赖：v8、libcurl、html5ever、Rust。
  • Linux (Debian/Ubuntu)：
    1
    sudo apt install xz-utils ca-certificates pkg-config libglib2.0-dev clang make curl git rustc
  • macOS：
    1
    brew install cmake rust

5.2 构建命令

1
2
3
4
5
6
7
8
9
10
11
12
# 克隆仓库
git clone https://github.com/lightpanda-io/browser.git
cd browser

# 使用Make构建
make build

# 或使用Zig命令直接构建并运行
zig build run

# 构建优化版本（ReleaseFast）
zig build -Doptimize=ReleaseFast run

6. 测试（开发者参考）

6.1 单元测试

1
2
make test                      # 运行所有测试
make test F="server"           # 按名称过滤测试

6.2 端到端测试

需克隆 demo 仓库并安装Go：

1
make end2end

6.3 Web平台测试 (WPT)

Lightpanda通过Web Platform Tests进行标准化测试。详细运行方式请参考仓库文档。

7. 常见问题排查

问题 可能原因 解决方案
cannot execute: required file not found Linux二进制依赖glibc，在musl系统上运行 使用glibc基础镜像（如Debian）或从源码构建。
无法连接到CDP服务器 服务器未启动或端口被占用 确认 ./lightpanda serve 正在运行，检查 --host 和 --port 参数。
Agent模式提示API Key错误 未设置正确的环境变量 根据提供商设置 ANTHROPIC_API_KEY, OPENAI_API_KEY, VERTEX_API_KEY 等。
某些网站无法正常加载 浏览器仍在Beta阶段，部分Web API未实现 查看项目状态和已实现功能列表，或提交Issue。

8. 总结

Lightpanda 是一个高性能、资源友好的Headless浏览器，特别适合AI代理、自动化脚本和大规模数据抓取场景。

核心部署路径：

  1. 选择安装方式：包管理器（推荐）、直接下载或Docker。
  2. 启动CDP服务：./lightpanda serve，供Puppeteer/Playwright连接。
  3. 或直接使用：./lightpanda fetch 获取内容，或 ./lightpanda agent 进行AI驱动浏览。
  4. （可选） 从源码构建以获取最新特性或定制。

建议先通过 ./lightpanda version 验证安装，再尝试简单的 fetch 命令来熟悉其工作方式。

项目地址：https://github.com/lightpanda-io/browser