lightpanda-browser

Lightpanda 浏览器 — 快速无头自动化

使用 Lightpanda 作为后端引擎进行无头浏览器自动化，并通过 CDP（Chrome DevTools Protocol）使用 agent-browser CLI 控制。

何时选择它，而不是 agent-browser：

使用 Lightpanda	使用 agent-browser（Chromium）
网页抓取 / 数据提取	屏幕截图、PDF、视觉测试
表单自动化 / 提交	视频录制 / 视觉调试
API 响应检查	CSS 布局验证
DOM 遍历 / 内容解析	移动设备模拟（iOS）
RAM 有限的 CI 环境	完整的浏览器扩展支持
大规模并行会话	需要完整渲染的网站

触发词：

• “lightpanda”、“轻量级浏览器”、“快速无头”
• “低内存抓取”、“无头抓取”
• “无需渲染的浏览器”、“仅 DOM 浏览器”
• “快速浏览器自动化”、“高效抓取”
• “lightpanda 比 chromium 快吗？”、“哪个无头浏览器占用的内存更少？”
• “如何在不使用 chromium 的情况下抓取？”、“能否用更少的 RAM 运行浏览器？”
• 任何不需要视觉输出的浏览器任务

---

前提条件

安装 Lightpanda

# macOS (Apple Silicon)
curl -fsSL https://github.com/nichochar/install-lightpanda/raw/main/install.sh | bash

# Or build from source
git clone https://github.com/lightpanda-io/browser.git
cd browser && zig build -Doptimize=ReleaseSafe

安装 agent-browser（如果尚未安装）

brew install agent-browser

验证安装

lightpanda --version
agent-browser --version

---

核心工作流

每个会话都遵循以下生命周期：

1. Start Lightpanda daemon (CDP server)
2. Connect agent-browser via --cdp
3. Navigate, snapshot, interact
4. Stop daemon when done

步骤 1 — 启动 Lightpanda

# Start Lightpanda CDP server on port 9222 (background)
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!

# Wait for CDP to be ready
sleep 1

步骤 2 — 连接并自动化

# All agent-browser commands work via --cdp flag
agent-browser --cdp 9222 open https://example.com
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "search query"
agent-browser --cdp 9222 click @e2
agent-browser --cdp 9222 snapshot -i  # Re-snapshot after navigation

步骤 3 — 清理

agent-browser --cdp 9222 close
kill $LIGHTPANDA_PID 2>/dev/null

---

支持的命令

以下所有命令均以 agent-browser --cdp <port> <command> 的形式调用。

导航

agent-browser --cdp 9222 open <url>
agent-browser --cdp 9222 back
agent-browser --cdp 9222 forward
agent-browser --cdp 9222 reload
agent-browser --cdp 9222 close

快照（DOM 分析）

agent-browser --cdp 9222 snapshot -i         # Interactive elements with refs
agent-browser --cdp 9222 snapshot -i -C      # Include cursor-interactive elements
agent-browser --cdp 9222 snapshot -s "#main"  # Scope to CSS selector
agent-browser --cdp 9222 snapshot -i --json   # JSON output for parsing

交互（使用快照中的 @refs）

agent-browser --cdp 9222 click @e1
agent-browser --cdp 9222 dblclick @e1
agent-browser --cdp 9222 fill @e2 "text"
agent-browser --cdp 9222 type @e2 "text"
agent-browser --cdp 9222 press Enter
agent-browser --cdp 9222 select @e1 "option"
agent-browser --cdp 9222 check @e1
agent-browser --cdp 9222 hover @e1
agent-browser --cdp 9222 scroll down 500
agent-browser --cdp 9222 drag @e1 @e2
agent-browser --cdp 9222 upload @e1 file.pdf

获取信息

agent-browser --cdp 9222 get text @e1        # Element text
agent-browser --cdp 9222 get html @e1        # innerHTML
agent-browser --cdp 9222 get value @e1       # Input value
agent-browser --cdp 9222 get attr @e1 href   # Attribute
agent-browser --cdp 9222 get title           # Page title
agent-browser --cdp 9222 get url             # Current URL
agent-browser --cdp 9222 get count ".item"   # Count elements

等待

agent-browser --cdp 9222 wait @e1                     # Wait for element
agent-browser --cdp 9222 wait 2000                    # Wait milliseconds
agent-browser --cdp 9222 wait --text "Success"        # Wait for text
agent-browser --cdp 9222 wait --url "**/dashboard"    # Wait for URL
agent-browser --cdp 9222 wait --load networkidle      # Wait for network idle
agent-browser --cdp 9222 wait --fn "window.ready"     # Wait for JS condition

Cookie 和存储

agent-browser --cdp 9222 cookies
agent-browser --cdp 9222 cookies set name value
agent-browser --cdp 9222 cookies clear
agent-browser --cdp 9222 storage local
agent-browser --cdp 9222 storage local set key value

网络拦截

agent-browser --cdp 9222 network route <url>              # Intercept
agent-browser --cdp 9222 network route <url> --abort      # Block
agent-browser --cdp 9222 network route <url> --body '{}'  # Mock response
agent-browser --cdp 9222 network requests                 # View tracked
agent-browser --cdp 9222 network requests --filter api    # Filter

JavaScript 执行

agent-browser --cdp 9222 eval "document.title"
agent-browser --cdp 9222 eval -b "<base64>"
cat script.js | agent-browser --cdp 9222 eval --stdin

语义定位器

agent-browser --cdp 9222 find text "Sign In" click
agent-browser --cdp 9222 find label "Email" fill "[email protected]"
agent-browser --cdp 9222 find role button click --name "Submit"
agent-browser --cdp 9222 find testid "submit-btn" click

标签页

agent-browser --cdp 9222 tab                 # List tabs
agent-browser --cdp 9222 tab new [url]       # New tab
agent-browser --cdp 9222 tab 2               # Switch tab
agent-browser --cdp 9222 tab close           # Close tab

框架

agent-browser --cdp 9222 frame "#iframe"     # Enter iframe
agent-browser --cdp 9222 frame main          # Back to main

状态管理

agent-browser --cdp 9222 state save auth.json    # Save session state
agent-browser --cdp 9222 state load auth.json    # Restore session state

---

不支持的命令

Lightpanda 没有渲染引擎。以下命令会失败或产生空输出：

命令	原因	替代方案
screenshot	不支持视觉渲染	使用 get text / get html 获取内容
pdf	没有 CSS 布局引擎	使用 get html 并在外部转换
record start/stop	没有可供录制的视觉输出	使用网络请求日志
highlight	不支持视觉渲染	使用 snapshot -i 识别元素
set device	不支持视口模拟	通过 set headers 设置 user-agent
set media	不支持 CSS 媒体查询	不适用
get styles	无法获取计算后的样式	解析原始 HTML/CSS
get box	无法计算布局	不适用
is visible	无法计算可见性	改为检查 DOM 中是否存在

---

常见模式

大规模抓取

# Start Lightpanda — uses ~60MB vs ~550MB for Chromium
lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

URLS=("https://site.com/page/1" "https://site.com/page/2" "https://site.com/page/3")
for url in "${URLS[@]}"; do
  agent-browser --cdp 9222 open "$url"
  agent-browser --cdp 9222 wait --load networkidle
  agent-browser --cdp 9222 get text body >> output.txt
  echo "---" >> output.txt
done

kill $LIGHTPANDA_PID 2>/dev/null

表单自动化

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

agent-browser --cdp 9222 open https://example.com/form
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "Jane Doe"
agent-browser --cdp 9222 fill @e2 "[email protected]"
agent-browser --cdp 9222 select @e3 "California"
agent-browser --cdp 9222 check @e4
agent-browser --cdp 9222 click @e5
agent-browser --cdp 9222 wait --load networkidle
agent-browser --cdp 9222 snapshot -i  # Verify result

kill $LIGHTPANDA_PID 2>/dev/null

已认证会话

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Login and save state
agent-browser --cdp 9222 open https://app.example.com/login
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 fill @e1 "$USERNAME"
agent-browser --cdp 9222 fill @e2 "$PASSWORD"
agent-browser --cdp 9222 click @e3
agent-browser --cdp 9222 wait --url "**/dashboard"
agent-browser --cdp 9222 state save auth.json

# Reuse state later (new session)
agent-browser --cdp 9222 state load auth.json
agent-browser --cdp 9222 open https://app.example.com/dashboard
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

API 响应检查

lightpanda serve --host 127.0.0.1 --port 9222 &
LIGHTPANDA_PID=$!
sleep 1

# Intercept API calls
agent-browser --cdp 9222 open https://app.example.com
agent-browser --cdp 9222 network requests --filter "/api/"

# Or mock API responses for testing
agent-browser --cdp 9222 network route "**/api/users" --body '{"users": []}'
agent-browser --cdp 9222 open https://app.example.com/users
agent-browser --cdp 9222 snapshot -i

kill $LIGHTPANDA_PID 2>/dev/null

在不同端口上运行并行会话

# Launch multiple Lightpanda instances for true parallelism
lightpanda serve --host 127.0.0.1 --port 9222 &
PID1=$!
lightpanda serve --host 127.0.0.1 --port 9223 &
PID2=$!
sleep 1

agent-browser --cdp 9222 open https://site-a.com &
agent-browser --cdp 9223 open https://site-b.com &
wait

agent-browser --cdp 9222 get text body > site-a.txt
agent-browser --cdp 9223 get text body > site-b.txt

kill $PID1 $PID2 2>/dev/null

---

环境变量

LIGHTPANDA_HOST="127.0.0.1"    # Bind address (default: 127.0.0.1)
LIGHTPANDA_PORT="9222"          # CDP port (default: 9222)

---

故障排除

Lightpanda 无法启动

# Check if port is in use
lsof -i :9222
# Kill existing process
kill $(lsof -t -i :9222) 2>/dev/null

CDP 连接被拒绝

# Verify Lightpanda is listening
curl -s http://127.0.0.1:9222/json/version
# Expected: JSON with browser info

命令失败，并提示“not supported”

Lightpanda 目前处于 beta 阶段。如果某个 CDP 方法尚未实现：

1. 查看 Lightpanda 状态页面，了解支持的 API
2. 针对该操作改用 agent-browser（Chromium）
3. 在 https://github.com/lightpanda-io/browser/issues 提交问题

JavaScript 执行错误

Lightpanda 使用 V8，但尚未实现所有 Web API。如果 eval 执行失败：

1. 检查该 API 是否列在 Lightpanda 的支持功能中
2. 使用更简单的 DOM 操作（get text、get html），而非复杂的 JS

---

性能基准

用于在 Lightpanda 和 Chromium 之间进行选择的参考数据。数据基于典型的抓取工作负载测得。

指标	Lightpanda	Chromium (Playwright)	适用场景
每个页面的内存占用	~60MB	~550MB	并行会话、CI 运行器、资源受限的环境
冷启动	<100ms	~2s	短生命周期脚本、无服务器、高频调用
仅 DOM 页面加载	~50ms	~300ms	批量抓取（抓取数百个页面时，差异会累积）
二进制文件大小	~15MB	~300MB	Docker 镜像、CI 缓存、磁盘空间受限的主机
JS 执行（V8）	相当	相当	没有差异——使用相同的引擎
完整页面渲染	N/A	~500ms	Lightpanda 无法渲染——请使用 Chromium

决策阈值

场景	建议
< 10 个页面，需要截图	Chromium——开销可以忽略不计
10-100 个页面，仅提取文本	Lightpanda——可节省 5-50GB RAM
100 个以上页面，并行会话	Lightpanda——Chromium 会达到内存限制
CI 的内存限制为 2GB	Lightpanda——可处理 30 个以上页面，Chromium 只能处理 3 个
视觉回归测试	Chromium——Lightpanda 无法生成图像
提交表单并验证响应	两者均可——Lightpanda 更快，但两者都能胜任

---

校准规则

1. 始终先启动 Lightpanda，再执行 agent-browser 命令。 如果守护进程未运行，CDP 连接会静默失败——继续操作前，请使用 curl -sf http://127.0.0.1:9222/json/version 验证。
2. 每次导航后都要重新创建快照。 页面发生变化时，引用（@e1、@e2）会失效——这是从 agent-browser 继承的行为，并非 Lightpanda 特有。
3. 提取内容时，优先使用 get text，而非 eval。 Lightpanda 支持的 Web API 尚不完整——document.querySelector 可以使用，但复杂 API（IntersectionObserver、getComputedStyle）无法使用。
4. 并行会话应使用不同端口，而不是 --session。 Lightpanda 实例采用单线程——使用多个端口可实现真正的并行；--session 则是在同一个实例上进行多路复用。
5. 明确切换到 Chromium，不要静默处理。 如果命令失败并提示“not supported”，请针对该操作切换到 agent-browser（不带 --cdp 标志）。不要重试或隐藏错误。
6. 退出时终止守护进程。 在脚本中使用 trap cleanup EXIT，避免遗留的 Lightpanda 进程占用端口 9222。
7. 升级前查看 Lightpanda 发布说明。 这是 beta 软件——不同版本的 CDP 方法覆盖范围会有所变化。更新后，在已知页面上运行 agent-browser --cdp 9222 snapshot -i，进行冒烟测试。

---

深入文档

参考	适用场景
references/commands.md	完整的命令参考，包含 CDP 标志用法
references/lightpanda-setup.md	安装、配置和从源代码构建
references/compatibility.md	支持和不支持的 CDP 方法及 Web API

开箱即用的模板

模板	描述
templates/scrape-session.sh	启动守护进程、抓取页面并清理
templates/form-submit.sh	填写并提交表单，同时进行验证
templates/parallel-extract.sh	多端口并行提取数据