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

GitHub 每日趋势，GitHub 各编程语言每日趋势汇总。关注

Lightpanda：专为人工智能和自动化设计的无头浏览器

光熊猫浏览器

这款为AI代理和自动化从零开始打造的无头浏览器。
不是 Chromium 分支。不是 WebKit 补丁。是用 Zig 编写的新浏览器。

基准测试

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

度规	光熊猫	无头铬	区别
记忆（最高，100页）	123MB	2GB	~少16
执行时间（100页）	5	46转	~快9倍

快速入门

安装

包管理器

Homebrew最新夜刊：

brew install lightpanda-io/browser/lightpanda

Arch Linux 用户仓库最新夜间动态：

yay -S lightpanda-nightly-bin

从夜间版本下载

你可以从夜间建造适用于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 也可用

注：Linux 发布的二进制文件是通过链接对抗 glibc 的。在基于 musl 的发行版（如 Alpine 等）上，二进制文件会以cannot execute: required file not found因为缺少 glibc 动态链接器。使用基于 glibc 的基图（例如，FROM debian:bookworm-slim或FROM ubuntu:24.04）或从源头构建.

适用于 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没安装？跑wsl --install从管理员 shell 重启，然后打开wsl.参见Microsoft 的 WSL 安装指南细节。

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

从 Docker 安装

光熊猫提供官方 Docker 镜像适用于Linux amd64和arm64架构。以下命令获取Docker映像并启动一个新容器，将Lightpanda的CDP服务器暴露在端口上9222.

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

转储一个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用于纯文本渲染页面。--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

一旦CDP服务器启动，你可以通过配置browserWSEndpoint.

木偶师脚本示例

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支持。你可以同时启动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

代理模式

lightpanda agent让你用原生代理驱动浏览器。用通俗易懂的英语或斜杠命令描述你想要的内容，它就能控制浏览器：浏览页面、点击流程、填写表单、提取结构化数据。

把它看作你引导它使用网络的机器人，而不是你对话的聊天机器人。

由于代理运行在与浏览器相同的进程中，每次工具调用都是直接操作，同时保持了 Lightpanda 的速度和内存优势。

代理会话的输出是熊猫脚本：原版JavaScript，内置了一小部分原生浏览器原语，直接内置在Lightpanda中。运行/save从当前会话导出一个，然后用lightpanda run .脚本是确定性的且无标记的，所以你可以用LLM做原型，并在运行时无需模型就将输出交付生产环境。

它支持 Anthropic、OpenAI、Gemini、Google Vertex AI、Mistral、Hugging Face 等Vercel AI 网关（每个主要实验室数百个模型的一键），任何兼容 OpenAI 的端点都通过以下方式实现OPENAI_BASE_URL以及通过 Ollama 或 llama.cpp 的本地模型。

你也可以不使用大型语言模型，使用--no-llm这会让你进入REPL。参见代理文档完整参考资料。

./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与技能

MCP服务器通过MCP JSON-RPC 2.0通过stdio进行通信。

添加到你的MCP配置中：

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

HTTP 传输与独立会话

对于从一个进程服务多个代理，可以通过HTTP启动MCP服务器，而不是通过stdio，给它一个端口（add--host x.x.x.x指定监听接口）：

lightpanda mcp --port 9223

Clients POST JSON-RPC TOhttp://host:9223/mcp.每个连接都被路由到自己的连接浏览会话——独立页面、Cookie和内存——这样代理们就不会再互相打扰对方的页面：

一个客户initializes 没有Mcp-Session-Id首部被分配一个新的会话;ID 会返回响应的Mcp-Session-Id首部。在后续请求中发送该地址以保持在该会话中（隔离).
两个代理人会发送我也是 Mcp-Session-Id共享一个浏览上下文（共享——例如，多个代理在同一页面工作的工作流）。
该session_new,session_list以及session_close工具明确管理会话。发送DELETE /mcp带有Mcp-Session-Id结束了那场游戏。

阅读完整文档

一个技能可以在光熊猫-IO/特工技能.

遥测

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

核心转储

赛场LIGHTPANDA_DISABLE_CORE_DUMP（任意值）通过归零软数据来抑制崩溃核心的转储RLIMIT_CORE在启动时。

现状

以下是我们已实现的关键功能。详情请参见我们的网络平台测试结果.

CORS（使使得--experimental-features cors)
HTTP 加载器（利库尔)
HTML 解析器（HTML5Ever)
DOM树
JavaScript 支持（V8)
DOM API
阿贾克斯
- XHR API
- Fetch API
DOM 和 Markdown 导出
CDP/websockets 服务器
咔哒
输入形式
饼干
自定义 HTTP 头部
代理支持
网络拦截
敬意robots.txt附选权--obey-robots
CDP和Webdriver Bidi
广告拦截器

从源头构建

前提条件

Lightpanda 的书写为之字形 0.15.2.你必须用正确的版本安装它才能构建项目。

光熊猫还依赖于V8,利库尔以及HTML5Ever.

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

对于基于Debian/Ubuntu的Linux:

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

你还需要安装Rust.

对于什么都没有你可以使用devShell：

nix develop

对于macOS，你需要 cmake 和半场休息.

brew install cmake

建造与运行

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

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

嵌入v8快照

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

生成快照。

zig build snapshot_creator -- src/snapshot.bin

使用快照二进制来构建。

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

参见#1279更多细节请阅读。

测试

单元测试

你可以通过运行来测试Lightpandamake test.

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是。

你必须安装demo 节点要求

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

make end2end

网络平台测试

Lightpanda通过标准化测试网络平台测试.

我们使用一把叉子包括一个习俗testharnessreport.js.结果如下已发布每天。

供参考，你可以用浏览器轻松执行WPT测试用例，通过以下方式wpt.live.

配置WPT HTTP服务器

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

外部走跑者由github.com/lightpanda-io/demo/存储库，位于wptrunner/主任。你得先克隆项目。

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

./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作为指导方针。你必须在我们的CLA在拉取请求过程中。

Discord

为什么选择光熊猫？

JavaScript 执行是现代网络的必不可少

过去简单的HTTP请求就足以实现网络自动化。现在情况已不同。现在大部分网络都是由JavaScript驱动的：

Ajax，单页应用，无限加载，即时搜索
JS框架：React、Vue、Angular等

Chrome 不是合适的工具

在服务器上运行完整的桌面浏览器是可以的，但扩展性不佳。Chrome在数百甚至数千实例中运行成本很高：

内存和CPU占用量很大
难以大规模打包、部署和维护
许多功能在无头制造中并非必需

Lightpanda专为性能设计

真正支持Javascript意味着从零开始构建，而不是分支Chromium：

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

添加评论

点踩

分享查看原文

参与讨论