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