Files
Obsidian/MyArticles/Lightpanda Browser CDP 完整解析与使用指南.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

359 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# lightpanda-io/browser 完整解析与使用指南
## 一、项目核心定位
该项目是基于 **Zig 语言** 开发的轻量级浏览器内核实现,核心目标是兼容 Chrome DevTools Protocol(CDP,Chrome 开发者工具协议),为自定义浏览器/自动化场景提供基础的 CDP 协议交互能力。项目目前处于**早期开发阶段**,大部分 CDP 方法仅做协议层兼容(返回空结果/硬编码值),尚未实现完整的浏览器功能,但可作为 CDP 协议适配、Zig 语言开发浏览器内核的基础框架。
## 二、核心技术细节
### 1. 代码架构分层
```Plain
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` 返回硬编码值:
```Plain
// 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/](https://ziglang.org/download/);
- **CDP 客户端**:用于测试协议交互,可选:
- Chrome 浏览器(自带 DevTools);
- Puppeteer(Node.js 库);
- curl(手动发送 JSON-RPC 请求)。
### 2. 编译与运行
#### 步骤 1:克隆代码库
```Bash
git clone https://github.com/lightpanda-io/browser.git
cd browser
```
#### 步骤 2:编译项目
- 调试模式(保留脚本日志功能):
```Bash
zig build -Dmode=debug
```
- 发布模式:
```Bash
zig build -Dmode=release-fast
```
  编译产物输出到 `zig-out/bin/` 目录(可执行文件名随系统不同,如 `browser`(Linux/macOS)、`browser.exe`(Windows))。
#### 步骤 3:启动 CDP 服务
项目核心是运行 CDP 协议服务端,启动命令(基于 CDP 服务常规逻辑):
```Bash
./zig-out/bin/browser --cdp-port=9222 # 监听 9222 端口(CDP 标准端口)
```
### 3. 测试 CDP 协议交互
#### 方式 1:使用 Chrome DevTools 连接
1. 启动服务后,打开 Chrome 浏览器,访问 `chrome://inspect`;
2. 点击「Configure」,添加 `localhost:9222`;
3. 浏览器识别到「自定义浏览器」后,点击「Inspect」打开 DevTools;
4. 在 Console 中执行 `navigator.userAgent`,返回项目硬编码的 `CDP_USER_AGENT`(Chrome 124 模拟值);
5. 调用 CDP 方法(如 `Browser.getVersion`),可在 DevTools 的「Protocol Monitor」中查看返回的硬编码版本信息。
#### 方式 2:使用 curl 手动发送请求
```Bash
# 发送 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 连接(兼容测试)
```JavaScript
// 安装 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` 函数
```Plain
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:编译并测试
```Bash
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. 贡献指南
1. **签署 CLA**:首次提交 PR 时,通过 CLA Assistant 签署贡献者协议(项目已配置自动校验流程);
2. **代码规范**:遵循 Zig 官方编码规范([https://ziglang.org/documentation/master/#Style-Guide](https://ziglang.org/documentation/master/#Style-Guide));
3. **提交 PR**:
1. 分支命名:`feature/<功能名>`(如 `feature/implement-setDownloadBehavior`);
2. 包含单元测试:基于 `testing.zig` 编写新增方法的测试用例;
3. 标注修改记录:在源码中注明修改内容和日期(符合 AGPL-3.0 要求);
4. **审核合并**:项目维护者审核代码后合并到主分支。
## 四、使用场景与限制
### 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:
1. 参考 Chrome CDP 官方文档([https://chromedevtools.github.io/devtools-protocol/](https://chromedevtools.github.io/devtools-protocol/))更新协议常量(如 `PROTOCOL_VERSION`);
2. 扩展 `processMessage` 的方法枚举,新增新版 CDP 方法;
3. 实现对应方法的逻辑。
### Q3:调试模式下的脚本日志如何查看?
A:编译后运行服务,执行 CDP 的 `Runtime.evaluate` 方法,脚本会保存到 `.zig-cache/tmp/` 目录,文件名格式为 `id_<请求ID>.js`。
### Q4:商用部署需要注意什么?
A:
1. 若部署为网络服务,需在服务界面提供源码下载链接;
2. 保留所有版权声明和 AGPL-3.0 协议文本;
3. 若修改了代码,需开源全部修改后的源码(包括构建脚本、配置文件)。