359 lines
13 KiB
Markdown
359 lines
13 KiB
Markdown
# 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. 若修改了代码,需开源全部修改后的源码(包括构建脚本、配置文件)。 |