13 KiB
lightpanda-io/browser 完整解析与使用指南
一、项目核心定位
该项目是基于 Zig 语言 开发的轻量级浏览器内核实现,核心目标是兼容 Chrome DevTools Protocol(CDP,Chrome 开发者工具协议),为自定义浏览器/自动化场景提供基础的 CDP 协议交互能力。项目目前处于早期开发阶段,大部分 CDP 方法仅做协议层兼容(返回空结果/硬编码值),尚未实现完整的浏览器功能,但可作为 CDP 协议适配、Zig 语言开发浏览器内核的基础框架。
二、核心技术细节
1. 代码架构分层
browser/
├── src/
│ ├── cdp/ # CDP 协议核心实现层
│ │ ├── domains/ # 按 CDP 域划分的方法实现
│ │ │ ├── browser.zig # 浏览器基础能力(版本、窗口、权限)
│ │ │ ├── runtime.zig # JS 运行时(执行、函数调用)
│ │ │ ├── emulation.zig # 设备/媒体模拟
│ │ │ ├── css.zig # CSS 能力(仅占位)
│ │ │ ├── performance.zig # 性能监控(仅占位)
│ │ ├── testing.zig # CDP 方法单元测试工具
│ ├── main.zig # 程序入口(未在片段中展示,推测为 CDP 服务启动)
├── LICENSE # AGPL-3.0 协议全文
├── CLA.md # 贡献者许可协议
├── CONTRIBUTING.md # 贡献指南
2. CDP 协议实现细节
-
协议交互流程:
-
接收 CDP 客户端(如 Chrome DevTools、Puppeteer)的 JSON-RPC 格式请求;
-
通过
processMessage函数解析请求的「方法名」(如Browser.getVersion); -
路由到对应域的处理函数(如
getVersion); -
返回符合 CDP 协议格式的 JSON 响应(硬编码值/空值)。
-
-
调试模式特性:
当编译模式为 .Debug 时,runtime.zig 会将执行的 JS 脚本/函数声明保存到 .zig-cache/tmp/id_<请求ID>.js,便于调试脚本执行流程。
- 核心方法实现(browser.zig):
项目中 browser.zig 实现了 Browser 域的核心 CDP 方法,多数方法暂为 noop(仅返回空结果),仅 getVersion/getWindowForTarget 返回硬编码值:
// Copyright (C) 2023-2024 Lightpanda (Selecy SAS)
// 核心硬编码常量
const PROTOCOL_VERSION = "1.3";
const REVISION = "@9e6ded5ac1ff5e38d930ae52bd9aec09bd1a68e4";
const CDP_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
const PRODUCT = "Chrome/124.0.6367.29";
pub fn processMessage(cmd: anytype) !void {
const action = std.meta.stringToEnum(enum {
getVersion, setPermission, setWindowBounds, resetPermissions,
grantPermissions, getWindowForTarget, setDownloadBehavior,
}, cmd.input.action) orelse return error.UnknownMethod;
switch (action) {
.getVersion => return getVersion(cmd),
// 其他方法路由逻辑...
}
}
fn getVersion(cmd: anytype) !void {
return cmd.sendResult(.{
.protocolVersion = PROTOCOL_VERSION,
.product = PRODUCT,
.revision = REVISION,
.userAgent = CDP_USER_AGENT,
.jsVersion = JS_VERSION,
}, .{ .include_session_id = false });
}
- 测试能力:
内置 testing.zig 提供 CDP 方法测试上下文,可验证方法是否返回预期的硬编码值(如 Browser.getVersion 返回指定的 Chrome 版本信息)。
3. 协议与许可约束
(1)AGPL-3.0 协议核心条款
该项目采用 GNU Affero General Public License v3.0(AGPL-3.0)协议,核心约束如下:
-
源码开放义务:
-
传播修改后的源码时,需标注修改信息、保留协议声明,且整体作品必须按 AGPL-3.0 授权;
-
若将软件部署为网络服务(如云端浏览器),需通过「显眼方式」(如页面“Source”链接)提供完整源码,且源码格式需公开可文档化(无需特殊密码/密钥解压);
-
若嵌入消费类/住宅集成产品(User Product),分发目标代码时需附带「安装信息」(如修改后源码的安装步骤),除非代码固化在 ROM 中无法修改。
-
-
传播非源码形式(如二进制)的要求:
可通过物理介质、网络服务、P2P 传输等方式传播,但需满足:
-
物理介质传播:附带源码或提供至少 3 年有效的源码获取书面承诺;
-
网络服务传播:提供等效的源码下载渠道,且需长期维护;
-
P2P 传输:告知节点源码的公开获取地址。
-
免责与限责:
软件按「现状」提供,无任何明示/默示担保;除非法律强制或书面约定,版权方不对使用软件造成的任何损失(包括数据丢失、业务中断等)承担责任。
- 版本选择:
若程序未指定 AGPL 版本,可选择任意版本;若指定“v3 或更高版本”,可选择 v3 或后续版本,且新版本仅会增加权限、不会加重义务。
(2)贡献者许可协议(CLA)
项目要求所有贡献者签署 CLA,核心条款:
-
授权范围:贡献者授予 Lightpanda(Selecy SAS)永久、全球、非独占的版权/专利许可,但保留自身使用贡献内容的权利;
-
原创性声明:贡献者需声明提交内容为原创,若为第三方内容需标注来源(如“Submitted on behalf of a third-party: [名称]”),并披露相关专利/许可约束;
-
无担保义务:贡献者无需为提交的代码提供技术支持,按「现状」提交;
-
专利诉讼终止条款:若贡献者/第三方就贡献内容发起专利诉讼,相关专利许可自动终止;
-
签署流程:首次提交 PR 时需通过 CLA Assistant 签署,项目通过 GitHub Action 自动校验(配置文件:
.github/workflows/cla.yml)。
三、环境准备与使用方法
1. 前置依赖
-
Zig 编译器:项目基于 Zig 开发,需安装 Zig 0.11.0+(推荐最新稳定版),下载地址:https://ziglang.org/download/;
-
CDP 客户端:用于测试协议交互,可选:
-
Chrome 浏览器(自带 DevTools);
-
Puppeteer(Node.js 库);
-
curl(手动发送 JSON-RPC 请求)。
-
2. 编译与运行
步骤 1:克隆代码库
git clone https://github.com/lightpanda-io/browser.git
cd browser
步骤 2:编译项目
-
调试模式(保留脚本日志功能):
zig build -Dmode=debug -
发布模式:
zig build -Dmode=release-fast编译产物输出到
zig-out/bin/目录(可执行文件名随系统不同,如browser(Linux/macOS)、browser.exe(Windows))。
步骤 3:启动 CDP 服务
项目核心是运行 CDP 协议服务端,启动命令(基于 CDP 服务常规逻辑):
./zig-out/bin/browser --cdp-port=9222 # 监听 9222 端口(CDP 标准端口)
3. 测试 CDP 协议交互
方式 1:使用 Chrome DevTools 连接
-
启动服务后,打开 Chrome 浏览器,访问
chrome://inspect; -
点击「Configure」,添加
localhost:9222; -
浏览器识别到「自定义浏览器」后,点击「Inspect」打开 DevTools;
-
在 Console 中执行
navigator.userAgent,返回项目硬编码的CDP_USER_AGENT(Chrome 124 模拟值); -
调用 CDP 方法(如
Browser.getVersion),可在 DevTools 的「Protocol Monitor」中查看返回的硬编码版本信息。
方式 2:使用 curl 手动发送请求
# 发送 Browser.getVersion 请求
curl -X POST http://localhost:9222/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"id": 1,
"method": "Browser.getVersion",
"params": {}
}'
# 预期响应(硬编码值)
{
"id": 1,
"result": {
"protocolVersion": "1.3",
"product": "Chrome/124.0.6367.29",
"revision": "@9e6ded5ac1ff5e38d930ae52bd9aec09bd1a68e4",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
"jsVersion": "12.4.254.8"
}
}
方式 3:使用 Puppeteer 连接(兼容测试)
// 安装 Puppeteer:npm install puppeteer
const puppeteer = require('puppeteer');
(async () => {
// 连接到自定义 CDP 服务
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://localhost:9222/devtools/browser/<会话ID>', // 会话ID需从服务端获取
});
const page = await browser.newPage();
// 测试 Browser.getVersion
const version = await page._client.send('Browser.getVersion');
console.log('Version:', version); // 输出硬编码的 Chrome 版本信息
await browser.close();
})();
4. 二次开发(扩展 CDP 方法)
以实现 Browser.setDownloadBehavior 为例(当前为 noop):
步骤 1:修改 browser.zig 的 setDownloadBehavior 函数
fn setDownloadBehavior(cmd: anytype) !void {
// 解析 CDP 请求参数
const params = (try cmd.params(struct {
behavior: []const u8, // "allow" | "deny" | "prompt"
browserContextId: ?[]const u8 = null,
downloadPath: ?[]const u8 = null,
eventsEnabled: ?bool = null,
})) orelse return error.InvalidParams;
// 实现下载行为逻辑(示例:保存下载路径到浏览器上下文)
const bc = cmd.browser_context orelse return error.BrowserContextNotLoaded;
bc.download_behavior = params.behavior;
if (params.downloadPath) |path| {
bc.download_path = path;
}
bc.download_events_enabled = params.eventsEnabled orelse false;
// 返回成功响应
return cmd.sendResult(null, .{});
}
步骤 2:编译并测试
zig build -Dmode=debug
# 启动服务后,用 curl 测试
curl -X POST http://localhost:9222/jsonrpc \
-d '{
"id": 2,
"method": "Browser.setDownloadBehavior",
"params": {
"behavior": "allow",
"downloadPath": "/tmp/downloads"
}
}'
5. 贡献指南
-
签署 CLA:首次提交 PR 时,通过 CLA Assistant 签署贡献者协议(项目已配置自动校验流程);
-
代码规范:遵循 Zig 官方编码规范(https://ziglang.org/documentation/master/#Style-Guide);
-
提交 PR:
-
分支命名:
feature/<功能名>(如feature/implement-setDownloadBehavior); -
包含单元测试:基于
testing.zig编写新增方法的测试用例; -
标注修改记录:在源码中注明修改内容和日期(符合 AGPL-3.0 要求);
-
-
审核合并:项目维护者审核代码后合并到主分支。
四、使用场景与限制
1. 适用场景
-
CDP 协议适配研究:学习 Zig 语言如何实现 CDP 协议,理解浏览器与 DevTools 的交互逻辑;
-
自定义浏览器内核开发:基于该框架扩展完整的浏览器功能(如 JS 引擎集成、渲染引擎对接);
-
自动化测试框架底层:适配 CDP 协议,为自动化测试工具提供轻量级服务端。
2. 核心限制(当前版本)
-
功能缺失:90% 以上的 CDP 方法为 noop(仅返回空值),无实际业务逻辑(如下载管理、权限控制、JS 执行);
-
硬编码值:版本信息、窗口 ID 等核心参数为硬编码,无法动态配置;
-
无渲染/网络层:仅实现 CDP 协议层,无 HTML/CSS 渲染、网络请求处理等浏览器核心能力;
-
AGPL 协议约束:商用/网络部署需开源全部修改代码,成本较高。
五、常见问题
Q1:能否替换为 MIT 协议?
A:不能。项目核心代码采用 AGPL-3.0 协议,修改/分发需遵循该协议,无法单方面更换为宽松协议(如 MIT)。
Q2:如何适配最新的 CDP 协议版本?
A:
-
参考 Chrome CDP 官方文档(https://chromedevtools.github.io/devtools-protocol/)更新协议常量(如
PROTOCOL_VERSION); -
扩展
processMessage的方法枚举,新增新版 CDP 方法; -
实现对应方法的逻辑。
Q3:调试模式下的脚本日志如何查看?
A:编译后运行服务,执行 CDP 的 Runtime.evaluate 方法,脚本会保存到 .zig-cache/tmp/ 目录,文件名格式为 id_<请求ID>.js。
Q4:商用部署需要注意什么?
A:
-
若部署为网络服务,需在服务界面提供源码下载链接;
-
保留所有版权声明和 AGPL-3.0 协议文本;
-
若修改了代码,需开源全部修改后的源码(包括构建脚本、配置文件)。