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

13 KiB
Raw Permalink Blame History

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 连接

  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 手动发送请求

# 发送 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. 贡献指南

  1. 签署 CLA:首次提交 PR 时,通过 CLA Assistant 签署贡献者协议(项目已配置自动校验流程);

  2. 代码规范:遵循 Zig 官方编码规范(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/)更新协议常量(如 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. 若修改了代码,需开源全部修改后的源码(包括构建脚本、配置文件)。