Lightpanda 源码深度解析 · Zig 无头浏览器

§ 02 / CDP SERVER

CDP 协议层

Chrome DevTools Protocol 的 Zig 实现。兼容 Puppeteer/Playwright，但只实现了一个子集。路由用 bit-cast 加速。

巧思：cdp/CDP.zig:200-262 的分派器按域名字符数分组，对每一组用 @bitCast(domain[0..N].*) 把字符串整体转成整数，再在整数上 switch，省掉字符串比较，O(1) 路由。

// 伪代码示意（实际在 CDP.zig:200-262）
switch (domain.len) {
    2 => switch (@bitCast(u16, domain[0..2].*)) { "LP" => ... },
    3 => switch (@bitCast(u24, domain[0..3].*)) { "DOM", "Log", "CSS" => ... },
    4 => ..., 5 => ..., 6 => ..., 7 => ...,
}

已实现的 CDP 域

Target

目标发现/附加

cdp/domains/target.zig

Page

导航、脚本求值、生命周期

cdp/domains/page.zig

DOM

树查询、quads、节点搜索

cdp/domains/dom.zig

Runtime

JS 求值、属性读取、调用栈

cdp/domains/runtime.zig

Network

网络事件、请求/响应捕获

cdp/domains/network.zig

Fetch

请求拦截、响应改写

cdp/domains/fetch.zig

Input

鼠标、键盘、触摸

cdp/domains/input.zig

Log

Console 日志

cdp/domains/log.zig

Storage

Cookie、LocalStorage

cdp/domains/storage.zig

CSS

规则读取（部分）

cdp/domains/css.zig

Browser

版本、窗口边界（多为桩）

cdp/domains/browser.zig

Inspector

状态（桩）

cdp/domains/inspector.zig

Security

安全信息

cdp/domains/security.zig

Emulation

设备模拟（桩——无布局）

cdp/domains/emulation.zig

Accessibility

AXNode 可访问性树

cdp/domains/accessibility.zig

Performance

性能指标

cdp/domains/performance.zig

LP (自扩)

Markdown dump 等

cdp/domains/lp.zig

关键约束：cdp/CDP.zig:270-281 强制只允许一个 BrowserContext 同时存在—— Lightpanda 任何时刻只有一个活动上下文、一个 Session、一个活动 Page。 不支持多页面并发。这是为了简化状态管理，但比 Chrome 的标签架构弱。

§ 03 / BROWSER CORE

浏览器核心三件套

Browser / Session / Page 三层结构，加上 Runner 事件循环。

Browser

持有 V8 环境，创建 Session

Browser.zig:43-119

└─ Session

cookie jar / history / origins / Page 生命周期

Session.zig:109-187

└─ Page

DOM 树 + frame 层级（iframes）

Page.zig:200-600+

Runner

事件循环: tick HttpClient → runMacrotasks → runMicrotasks

Runner.zig:57-150

导航流程

Client 调 Page.navigate(url)（CDP 或直接 API）
Page 入队导航
Runner.wait() 驱动事件循环直到满足等待条件
HTTP 进度 → Parser → JS 任务队列 → 微任务
Page 发出 load / DOMContentLoaded / networkidle
通知 CDP 的 Page.navigated

Arena 策略

Session 持有两个 Arena：

page_arena — 每次导航重建，销毁快
arena — Session 生命周期

Session.zig:116-117 代价：无跨页面复用，但换来干净快速的 teardown

§ 04 / HTML PARSING

HTML 解析 · Zig ↔ Rust FFI

直接用 Mozilla 的 html5ever（Rust 写的 HTML5 spec 实现），通过 C FFI 被 Zig 调用。

为什么不自己写？ html5ever 是 Mozilla Firefox 的产线级 HTML parser，实现了 adoption agency、template 内容模型、script insertion point 等所有奇葩边缘情况。从零复刻一个正确的 HTML parser 是多人年级别的工程，Lightpanda 直接用就对了。

构建集成

build.zig:235-265 跑 cargo build 编译 src/html5ever/Cargo.toml
产出 liblitefetch_html5ever.a
Zig 侧 mod.addObjectFile(obj) 静态链入
Cargo.toml + lib.rs 作为 input 追踪，变化自动重编

C API（Zig 侧声明）

html5ever_parse_document()
html5ever_parse_document_with_encoding() — charset aware
html5ever_parse_fragment() — innerHTML
html5ever_streaming_parser_create/feed/finish()
browser/parser/html5ever.zig:21-90

Rust → Zig 回调列表

// browser/parser/html5ever.zig:21-40
extern fn createElementCallback(ctx: *Parser, tag: *const u8, attrs: *const Attr, n: usize) *Node;
extern fn appendCallback(ctx: *Parser, parent: *Node, child: *Node) void;
extern fn popCallback(ctx: *Parser, node: *Node) void;
extern fn createCommentCallback(ctx: *Parser, text: *const u8, len: usize) *Node;
extern fn createProcessingInstruction(ctx: *Parser, target: [], data: []) *Node;
extern fn appendDoctypeToDocument(ctx: *Parser, name: [], publicId: [], systemId: []) void;
extern fn getTemplateContentsCallback(ctx: *Parser, node: *Node) *Node;
extern fn reparentChildrenCallback(ctx: *Parser, old: *Node, new: *Node) void;
extern fn addAttrsIfMissingCallback(ctx: *Parser, node: *Node, attrs: []Attr) void;

每个回调在 Zig 端实现为 callconv(.c) fn (ctx: *Parser, ...) Parser.zig:42-176。 ParsedNode 包装 Node* 加可选 element 数据。错误通过 Parser.err union 和源码位置归属。

DOM 节点表示（browser/webapi/Node.zig）：tagged union 包含 Document、DocumentFragment、Element、Text、Comment、PI、DocumentType、CDATA。 Element 带 qualified name、懒创建的 Attribute 节点、双向链表子节点、cached namespace URI。

§ 05 / JS RUNTIME

JS 运行时 · V8 绑定

用 V8 跑 JS，通过代码生成为每个 WebAPI 类型自动产出绑定。Zig 对象和 V8 对象通过 internal field 指针互映。

V8 集成

build.zig:213-233 --prebuilt-v8-path 优先，否则从 zig-v8 包从源码编译（~1 小时）
browser/js/js.zig:19-72 导出 V8 C API、TypedArray wrapper
browser/js/Platform.zig 平台初始化，快照加载
browser/js/Env.zig 每页多 Context（支持同源隔离），Global = Window

绑定桥

browser/js/bridge.zig 是代码生成式绑定，对每个 WebAPI 类型自动产出：

Constructor（new Element(...)）
Property accessor（getter/setter）
Method
Callback dispatch

JS 对象在 V8 internal field 存 Zig 指针，identity 稳定：同一个 Zig 对象永远映射到同一个 V8 对象。

类型转换规则（Value.zig）

Zig 类型	V8 类型
`bool`	Boolean
`i32 / u32 / f64`	Number
`[]const u8`	String
`*MyType`	Object with internal field = 指针
`?T`	null / Object
`error!T`	JS 异常 / 值

调用回传（browser/js/Caller.zig）：JS 调 Zig 方法 → 从 V8 internal field 取 Zig 指针 → 从 V8 参数数组取参数并转 Zig 类型 → 调 Zig 函数 → 返回值转 V8 value。 Zig error 直接 throw 成 JS 异常。

§ 06 / WEB API

Web API 实现矩阵

src/browser/webapi/ 下 217 个 .zig 文件。完整、半实现、缺失三档。

✓ 完整实现

△ 桩实现

webapi/canvas/OffscreenCanvas.zig:74-77 convertToBlob() 返回空 Blob

webapi/canvas/OffscreenCanvas.zig:80 transferToImageBitmap() 返回 null

✗ 完全缺失

语义警告：webapi/IntersectionObserver.zig 因为没有布局引擎，所有元素一律视为完全可见。任何依赖"滚动到视口才触发加载"的脚本（懒加载、无限列表）都会一次性全触发—— 这通常对爬虫来说是好事，因为页面一上来就全展开了，但对 A/B 测试脚本是错误行为。

§ 07 / NETWORK

网络栈 · libcurl 中心化

libcurl + BoringSSL + nghttp2 + brotli + zlib。关掉所有非 HTTP 协议。

libcurl

HTTP/HTTPS/WebSocket（关掉 FTP/IMAP/LDAP）

build.zig:439-600+

TLS

BoringSSL (Google OpenSSL fork)

build.zig:296-437

HTTP/2

nghttp2

build.zig:296-437

压缩

brotli + zlib + zstd

build.zig:296-437

事件循环

CurlM multi handle + epoll/kqueue + wakeup pipe

network/Network.zig:52-150

HTTP 客户端

browser/HttpClient.zig
持久连接池（configurable）
并发限流: --http-max-concurrent, --http-max-host-open
超时: 连接 + 传输分开
响应大小上限: --http-max-response-size
最多 10 次重定向

安全相关

SSRF 防护: network/IpFilter.zig --block-private-networks 屏蔽 RFC 1918 + IPv6 ULA，在 DNS 解析后执行
自定义 CIDR: --block-cidrs
Robots.txt: network/Robots.zig --obey-robots
WebBot Auth: network/WebBotAuth.zig Ed25519 签名

缓存

network/cache/Cache.zig + FsCache.zig
可选文件系统缓存 --http-cache-dir
尊重 HTTP 缓存头（Cache-Control / ETag / Last-Modified）
按 URL + request headers 为 key

请求拦截

cdp/domains/fetch.zig
CDP Fetch 域可拦截/改写任何请求
Pending transfer 挂在 BrowserContext.intercept_state
客户端可 abort / allow / mock response

§ 08 / MCP

MCP 集成（独特卖点）

Model Context Protocol 服务器，面向 Claude / Cursor / Cline 这类 AI Agent 工具。大部分浏览器只暴露 CDP 或 WebDriver，Lightpanda 把 MCP 当一等公民。

// 启动流
$ lightpanda mcp [--cdp-port 9223]
    ↓
main() 起 mcpThread()                       // main.zig:179-194
    ↓
mcp.Server.init(browser, session, http)     // mcp/Server.zig:27-54
    ↓
mcp.router.processRequests()                // 读 stdin / 写 stdout
    ↓
JSON-RPC 2.0 请求 → 路由 → handler → 响应

协议方法

initialize — 握手，返回协议版本
ping — 心跳
resources/list — 枚举资源
resources/read — 读资源

资源（2 种）

mcp://page/html — 完整序列化 DOM
mcp://page/markdown — token-efficient Markdown
mcp/resources.zig:9-22

给 AI Agent 的工具（20+）

类别	工具
导航	`goto(url, timeout, waitUntil)`, `navigate()`
提取	`markdown(url)`, `links(url)`, `semantic_tree(url, maxDepth)`, `interactiveElements(url)`, `structuredData(url)`, `detectForms(url)`
交互	`click(backendNodeId)`, `fill(backendNodeId, text)`, `hover`, `press(key)`, `scroll(x, y)`
检查	`nodeDetails(backendNodeId)` — tag/role/name/interactivity/value/href/checked/options
JS	`evaluate(script, url, timeout, waitUntil)`, `eval()`
等待	`waitForSelector(selector, timeout)`

mcp/tools.zig:48-300+

为什么有价值？ 用 Puppeteer 驱动 Chrome 时，AI 要学 CDP 协议 + 自己管 nodeId。用 Lightpanda MCP，Claude 直接用 click(5) / fill(3, "hello") 这类语义化 tool call， 不需要学协议细节。markdown(url) 还把 DOM 降维成 LLM 友好的 token 密集型文本。

§ 09 / BUILD

构建系统

build.zig 34 KB，非平凡。把 V8 / Rust crate / libcurl + 依赖链全串起来。

外部依赖（build.zig.zon）

v8 — 预编译或源码（源码 ~1h）
curl — 加 boringssl + nghttp2 + brotli + zlib + zstd
html5ever — Rust crate，仓内自带

产物

lightpanda — 主程序
lightpanda-snapshot-creator — V8 snapshot 生成
legacy_test — 集成测试 runner

主要步骤

build.zig:213-233 V8 链接 + ASAN/TSAN 选项
build.zig:235-265 跑 cargo build 编译 html5ever → .a → addObjectFile
build.zig:439-600+ 编译 libcurl（HTTP/2 + WebSocket + HTTPS + IPv6，关掉 FTP/IMAP/LDAP）
build.zig:296-437 编译 zlib/brotli/nghttp2/BoringSSL

常用命令

zig build             # 编译
zig build test        # 测试
zig build fmt         # 格式化
zig build -Doptimize=ReleaseSafe

§ 10 / LIMITS & TRADE-OFFS

已知限制与架构权衡

从代码里读出来的真实状况，不看营销。TODOs、桩方法、unreachable 都是一手线索。

有意为之的设计取舍

零渲染

Canvas 桩、CSS 解析但不布局、无盒模型、无计算样式。
代价：截图、视觉校验、依赖元素位置的反爬全部失效。
收益：11× 速度来源。

无布局引擎

IntersectionObserver 永远"可见"，媒体查询被忽略，@font-face 注册但不加载。
影响：懒加载一次全展开（爬虫友好），但 A/B 脚本可能出错。

单页上下文

cdp/CDP.zig:270-281 BrowserContext 唯一、Session 唯一、Page 唯一活动。
影响：没有真正的多标签并发，需要并发时必须多进程。

Fetch body 常驻内存

cdp/CDP.zig:384 捕获的响应 body 不流到磁盘。
影响：抓巨型文件会内存爆炸，典型页面无忧。

代码里的 TODO 线索

位置	TODO / 桩
cdp/domains/page.zig	缺 `transitionType`、`referrerPolicy` 枚举
cdp/domains/dom.zig	quads 即使元素应隐藏也照填
cdp/domains/network.zig	子 frame 没进 `Network.getCertificateDetails`
cdp/domains/fetch.zig	跨页面请求回复可能跨 context 泄漏
cdp/domains/emulation.zig	Device emulation 是 no-op（本来就没布局）
cdp/domains/browser.zig	窗口尺寸硬编码
cdp/AXNode.zig	Accessibility tree 在 label_element / label_wrap 有 TODO
webapi/selector/Parser.zig	复杂选择器 `:has()` 等可能桩

最终判断表

场景	Lightpanda	说明
批量抓静态/半动态页面	✓ 强烈推荐	比 Chrome 省 9× 内存
SSR 测试	✓ 合适	DOM 正确性为一等公民
给 AI Agent 当"浏览器臂"	✓ 原生支持	MCP 一等公民，20+ 语义工具
跑 Playwright/Puppeteer 脚本	△ 大部分能跑	兼容 CDP，但不支持需要截图/布局的 API
需要截图或像素校验	✗ 不行	没有渲染管线
重 SPA（依赖可见性懒加载）	△ 语义偏差	所有元素"可见"，懒加载一次全触发
WebRTC / WebGL / ServiceWorker	✗ 不行	全部未实现
多标签并发	✗ 不行	单 BrowserContext 约束
公司 SaaS 后端（AGPL）	△ 注意	自托管可能触发源码披露义务

§ 13 / FIELD MANUAL · 实战用法

什么时候用它，什么时候别用

前面 12 段讲"它是什么、怎么实现"。这一段讲"你该不该用、怎么组合"。技术解析的闭环。

🧠

一句话定位

Lightpanda 不是给你用的，是给你的脚本用的。就像你不会直接打开 MySQL，你写代码去查 MySQL——Lightpanda 也一样，你写代码让它去"读"网页。你平时上网继续用 Chrome；写脚本批量抓 1000 个页面——用 Lightpanda。

心智模型对比

	你用 Chrome	脚本用 Lightpanda
谁在操作	人（鼠标点击）	代码（goto/click/eval）
目的	看、购物、娱乐	提取数据 / 监控 / 自动化
速度	人速	每秒几十页
规模	1 个页面	1000 个页面
产出	脑子里的记忆	JSON / CSV / 数据库
界面	有窗口看得到	完全无 UI，看不到渲染

🚫 三个常见误解

✗ 不是搜索引擎

不索引互联网。你给一个 URL，它只处理这一个页面。想搜索得先有 URL 列表。

✗ 不是下载器

默认不存任何文件，结果流到 stdout。要留下必须自己重定向到文件或写数据库。

✗ 不是"批量下原始文件"

它是"批量读网页 → 提取结构化数据"。保存的不是 HTML 本身，是从 HTML 里挖出来的字段。

🎯 场景判断表

场景	能不能用	备注
新闻 / 博客 / Wiki	✅ 完美	纯文字，token 友好 Markdown
API 文档、技术站	✅ 完美	结构化强
论坛（HN / Reddit / V2EX）	✅ 完美	纯文字内容
SPA 后台管理系统	✅ 大多行	DOM 驱动，需要配合登录态
企业官网 / SaaS 介绍页	🟡 部分	标题在文字，卖点常在海报
电商商品详情页	❌ 瞎	规格、材质、使用说明全在长图
小红书 / Instagram	❌ 瞎	核心信息载体是图文笔记
PDF-as-webpage	❌ 瞎	很多文档站把 PDF 转成图嵌入
视频站	❌	视频内容根本不是 DOM

核心限制：Lightpanda 对"信息在图里"的站是瞎子。它能看到 <img src="xxx.jpg"> 的 URL，但不下载图片字节、不做 OCR、不做视觉理解。这是设计取舍——为了 11× 速度砍掉的能力，不是 bug。

🏗️ 正确的组合拳 · Lightpanda + VLM 管道

单 Lightpanda 覆盖 60% 的场景，剩下 40%（中文电商、小红书、海报站）必须靠视觉大模型（VLM）补。分层调度后，总成本比 "真 Chrome + 整页截图 + VLM" 便宜 5-10 倍。

① 抓取层

Lightpanda 抓页面 → DOM + 文字 + 图片 URL 列表

快 · 省钱

② 下载层

普通 curl / wget 下载需要的图片字节（非 Lightpanda）

按需精挑

③ 视觉层

VLM 读图：Claude Sonnet Vision / GPT-4V / Qwen-VL-Max / PaddleOCR

智能 · 贵

④ 合并层

Lightpanda 抽到的文字字段 + VLM 从图读到的字段 → 完整结构化数据

→ PostgreSQL / JSON

分工原则：Lightpanda 负责"快省地扒骨架"，VLM 负责"贵但能看懂图"。加起来比用真 Chrome 方案便宜数倍——因为 Chrome 会加载一堆你不需要的字体、CSS、JS 资源，还要先渲染才能截屏；Lightpanda 直接给你 <img src> URL，你精确挑要看的图交给 VLM。

📂 典型项目的场景映射

✓ 单跑 Lightpanda 就够

法条/题库补抓 — 大多是纯文字
新闻监控 / 技术文档同步
Wiki / Gitea / 文档站搜索
论坛社区数据采集
SaaS 后台 API 数据导出

✗ 必须配 VLM 组合拳

电商供应商批量采购 — 80% 信息在长图
淘宝/京东对标比价 — 价格、规格、活动规则全在图
汽修维修手册 — 接线图、爆炸图必须视觉理解
小红书爆款挖掘 — 核心是图文笔记
营销活动页抓取 — 海报里写满减规则

🛠️ 实战命令速查

一次性抓 + 转 Markdown（最快路径）

ssh root@VPS '/opt/lightpanda/lightpanda fetch \
  --dump markdown \
  --wait-until networkidle \
  --wait-ms 3000 \
  https://目标站.com'

适合：一次性抓一个 URL，把结果直接喂给 LLM 做摘要/问答

要完整 HTML（图片 URL + 主推文案 + 所有 DOM）

ssh root@VPS '/opt/lightpanda/lightpanda fetch \
  --dump html \
  --wait-until networkidle \
  --wait-ms 5000 \
  --with-base \
  https://目标站.com'

适合：要图片 URL 列表、要页面所有内容。注意：--dump markdown 会省略 hero/图片区块，想拿到产品主推文案必须用 html 自己 parse。

脚本化（需要登录态 / JS 交互 / 多步操作）

# 本机开 SSH 隧道
ssh -N -L 9222:127.0.0.1:9222 root@VPS

# 另一个终端跑 Python（Playwright connectOverCDP）
browser = await p.chromium.connect_over_cdp("http://127.0.0.1:9222")
context = await browser.new_context()
await context.add_cookies(cookies)  # 从本机 Chrome 导的登录态
page = await context.new_page()
await page.goto("https://后台.com/订单")
data = await page.eval_on_selector_all("...", "...")

适合：需要保持登录态的后台管理系统、多步表单交互、抓取分页列表

⚠️ 三个坑必须记住

坑 1 · wait 时机

默认 --wait-until=done，SPA 内容可能还没渲染就 dump 了。

解法：重页面加 --wait-until networkidle --wait-ms 3000。 Apple 首页就是这样才拿到 hero 主推产品。

坑 2 · markdown 省略

--dump markdown 是"语义精简"模式，会跳过图片为主的 hero 区块、产品卡片。

解法：想拿到所有内容用 --dump html，自己写 parser 提取 H2/H3/class。

坑 3 · UA 反爬

默认 UA 是 Lightpanda/1.0，很容易被反爬识别封 IP。

解法：加 --user-agent-suffix 或自建 UA。注意代码禁止含 "Mozilla" 的伪装 UA。

💡 铁律：Lightpanda 是抓取管道的"第一道工序"，不是全流程方案。启动任何项目前先想清楚下一道工序是什么——直接入库？给 VLM 看图？给 LLM 做摘要？触发告警？ 没想清楚下游就别用它——它只是个"不渲染的 Chrome"，不是银弹。

Lightpanda从源码读懂这只"快 11 倍"的无头熊猫

不是噱头，但有明确边界

入口与进程模型

内存策略

默认参数

CDP 协议层

已实现的 CDP 域

Target

Page

DOM

Runtime

Network

Fetch

Input

Log

Storage

CSS

Browser

Inspector

Security

Emulation

Accessibility

Performance

LP (自扩)

浏览器核心三件套

导航流程

Arena 策略

HTML 解析 · Zig ↔ Rust FFI

构建集成

C API（Zig 侧声明）

Rust → Zig 回调列表

JS 运行时 · V8 绑定

V8 集成

绑定桥

类型转换规则（Value.zig）

Web API 实现矩阵

✓ 完整实现

△ 桩实现

✗ 完全缺失

网络栈 · libcurl 中心化

HTTP 客户端

安全相关

缓存

请求拦截

MCP 集成（独特卖点）

协议方法

资源（2 种）

给 AI Agent 的工具（20+）

构建系统

外部依赖（build.zig.zon）

产物

主要步骤

常用命令

已知限制与架构权衡

有意为之的设计取舍

零渲染

无布局引擎

单页上下文

Fetch body 常驻内存

代码里的 TODO 线索

最终判断表

什么时候用它，什么时候别用

一句话定位

心智模型对比

🚫 三个常见误解

✗ 不是搜索引擎

✗ 不是下载器

✗ 不是"批量下原始文件"

🎯 场景判断表

🏗️ 正确的组合拳 · Lightpanda + VLM 管道

📂 典型项目的场景映射

✓ 单跑 Lightpanda 就够

✗ 必须配 VLM 组合拳

🛠️ 实战命令速查

一次性抓 + 转 Markdown（最快路径）

要完整 HTML（图片 URL + 主推文案 + 所有 DOM）

脚本化（需要登录态 / JS 交互 / 多步操作）

⚠️ 三个坑必须记住

坑 1 · wait 时机

坑 2 · markdown 省略

Lightpanda
从源码读懂这只"快 11 倍"的无头熊猫