Brave浏览器源码编译实战：从环境搭建到定制拦截规则

简介Brave浏览器是一款以隐私保护和高效浏览为核心的开源网络浏览器覆盖MacOS、Windows、Linux及Android多平台适合关注在线安全、希望摆脱广告干扰的技术爱好者与普通用户。资源包共52个文件约145KB以JavaScript脚本为主辅以Markdown文档、JSON配置、Python工具、RST说明及PNG、SVG等素材涵盖构建、同步、本地化、补丁更新与测试等模块并附LICENSE、Jenkinsfile、Makefile等工程文件便于理解项目结构与开发流程。目前已有896人学习下载。通过该资源读者可获取Brave浏览器源码的目录组织方式了解广告拦截、隐私模式、跨平台同步等特性的实现线索并借助脚本与文档快速上手构建、调试与二次开发为研究开源浏览器架构提供实用参考。1. 从一份浏览器源码包说起它到底能解决什么如果你正在找一个能直接编译、能改、能塞进自己业务逻辑的浏览器内核而不是只会在设置里点来点去的成品那这份 brave-browser 的源码包值得你花一个下午拆一拆。它覆盖 macOS、Windows、Linux 三个桌面端同时把 Android 端的构建入口也一并放进来了等于把 Chromium 那套庞大又劝退的工程体系重新整理成了一份「能照着跑通」的目录结构。我拿到手的第一反应不是它有多完整而是它把很多原本散落在 Chromium 文档角落里的编译参数、依赖版本、平台差异提前替你踩平了一部分。适合谁适合做客户端定制的、做隐私增强功能的、想研究浏览器广告拦截与追踪防护实现路径的工程师。不适合只想找个浏览器日常用的人那是另一回事。2. 源码包结构拆解从目录到构建入口2.1 顶层目录里哪些是真正要动的打开压缩包第一层通常能看到src/、build/、patches/、scripts/这几类目录。src/是主体里面又按 Chromium 的老规矩分成chrome/、content/、third_party/、components/。很多人一上来就扎进chrome/browser/找功能入口结果编译一次四十分钟改一行等半天。我的习惯是先看patches/因为 brave 的很多差异化能力——广告拦截、追踪防护、Brave Rewards——并不是直接写在src/里而是以补丁形式叠加在 Chromium 之上的。这意味着你如果直接改src/下次同步上游时冲突会非常难受。scripts/目录是这份包最值钱的地方。它通常包含build.sh、sync.sh、package.sh这类脚本把gclient、gn、ninja的调用顺序固定下来。新手最容易翻车的地方就是跳过脚本手动执行gn gen结果参数对不上报一堆undefined symbol。我一般会先读build.sh里的gn args把is_official_build、is_debug、target_cpu、enable_nacl这几个关键开关记下来后面调参才有依据。2.2 构建入口与平台差异桌面端和 Android 端的构建入口是分开的。桌面端走gn gen out/Default然后ninja -C out/Default chromeAndroid 端则要先source build/android/envsetup.sh再gn gen out/Android --argstarget_osandroid target_cpuarm64。这里有个血泪经验Android 构建对 JDK 版本极其敏感JDK 11 和 JDK 17 混用会直接卡在javac阶段报invalid source release。我一般会在~/.bashrc里把JAVA_HOME锁死到脚本里指定的那个版本而不是依赖系统默认。# 桌面端最小构建流程假设已安装 depot_tools export PATH$PWD/depot_tools:$PATH gclient sync --with_branch_heads --with_tags gn gen out/Default --args is_debugfalse is_official_buildtrue target_cpux64 enable_naclfalse blink_symbol_level0 ninja -C out/Default chrome -j 8这段脚本里gclient sync负责拉齐所有第三方依赖--with_branch_heads是为了后续能切分支。gn gen里的is_official_buildtrue会开启 LTO 和更激进的优化编译时间翻倍但产物更小blink_symbol_level0是砍掉 Blink 的调试符号能省下好几个 G 的磁盘。ninja -j 8的并行数别盲目拉满内存 16G 的机器开到 8 已经是上限再高会触发 OOM Killer编译进程直接被系统杀掉日志里只留一个Killed非常玄学。2.3 补丁机制与功能定位brave 的广告拦截核心在components/brave_shields/追踪防护的规则集通常以adblock-rust或类似的 Rust 组件形式存在。如果你要改拦截规则别去改src/chrome/而是找patches/下对应的.patch文件改完再重新应用。应用补丁的命令一般是# 在 src 目录下应用单个补丁 git apply ../patches/brave_shields_custom.patch # 如果冲突先看 reject 文件 find . -name *.rej -exec cat {} \;git apply失败时生成的.rej文件会告诉你哪几行没打上通常是上游 Chromium 改了同名函数签名。这时候要么手动合并要么用patch -p1 --merge走三方合并。我一般会先把补丁按功能分组每次只应用一组编译通过再应用下一组避免一次性炸掉整个构建。3. 从零编译到跑通参数、依赖与排错3.1 依赖安装的版本陷阱Linux 下编译 Chromium 系浏览器官方文档列了一长串apt install但真正会卡住你的是版本。比如libc的 ABI 版本、clang的版本必须和buildtools/里自带的那个一致。我见过最典型的翻车是系统装了clang-14但源码要求clang-16链接阶段报undefined reference to std::__1::...。解决办法不是升级系统 clang而是直接用depot_tools里的clang在gn args里加clang_use_chrome_pluginsfalse和use_custom_libcxxtrue。Windows 端则是另一套坑。必须用depot_tools自带的python3和ninjaVisual Studio 的版本要严格对应比如vs2019和vs2022的toolchain路径不同。我一般会在gn args里显式写visual_studio_version2019而不是让它自动探测。自动探测在装了多个 VS 版本的机器上经常选错报msvc_toolchain not found。3.2 编译参数怎么调才不翻车gn args里几个关键参数直接决定你能不能编过参数推荐值作用翻车点is_debugfalse关闭调试开启优化设 true 编译慢且产物巨大is_component_buildfalse静态链接产物独立设 true 在 Linux 下容易缺 sosymbol_level0砍符号省磁盘设 2 会多占 20Genable_naclfalse关掉已废弃的 NaCl设 true 会拉一堆旧依赖target_cpux64 / arm64目标架构和主机不一致时需交叉编译工具链我一般会先跑一次gn gen不带任何自定义参数看默认值是什么再逐项覆盖。直接抄网上的参数列表很容易因为源码版本不同导致某个参数已废弃gn直接报unknown argument。3.3 编译失败时先看什么编译报错别急着搜先看日志最后 50 行。ninja的报错通常分三类依赖缺失fatal error: xxx.h: No such file、链接错误undefined reference、工具链错误clang: error: unknown argument。依赖缺失多半是gclient sync没跑完重新跑一次并加--force。链接错误先确认is_component_build和use_custom_libcxx是否匹配。工具链错误直接检查gn args里的clang_version和visual_studio_version。# 查看完整编译日志并过滤错误 ninja -C out/Default chrome -j 8 21 | tee build.log grep -E error:|fatal error:|undefined reference build.log | head -30tee是为了保留完整日志grep过滤出关键错误行。如果错误行超过 30 条说明是系统性问题别逐条修先回退到上一个能编过的参数组合。4. 避坑与常见问题排查4.1 现象gclient sync卡在Fetching不动原因默认走的是git协议拉取某些网络环境下会超时但gclient不会主动报错只是无限重试。解决在.gclient文件里把solutions的url改成https开头并设置GIT_HTTP_LOW_SPEED_LIMIT和GIT_HTTP_LOW_SPEED_TIME环境变量让 git 快速失败而不是挂死。4.2 现象编译到一半报Killed没有其他错误原因ninja -j并行数过高内存耗尽被系统 OOM Killer 杀掉。解决把-j降到 4 或 6或者加交换分区。我一般会在编译前用free -h看可用内存按每核 1.5G 估算并行数。4.3 现象Android 端gn gen报no such file: build/android/envsetup.sh原因gclient sync没有拉取 Android 相关依赖或者target_os没设对。解决先确认.gclient里target_os [android]再跑gclient sync最后source build/android/envsetup.sh。顺序错了就会找不到文件。4.4 现象补丁应用后编译报redefinition of ...原因补丁和当前源码版本不匹配同一个函数被定义了两次。解决先git checkout -- .回退所有改动再逐个补丁应用每应用一个就编译一次定位到具体是哪个补丁冲突。别一次性全打上。4.5 现象Windows 下ninja报CreateProcess failed原因路径里有空格或中文ninja对路径非常敏感。解决把源码放到纯英文无空格的路径下比如D:\dev\brave\别放在C:\Users\某某\Desktop\。5. 进阶定制拦截规则与验证方法5.1 改拦截规则并验证生效brave 的拦截规则通常以adblock-rust的Engine形式加载。如果你想加一条自定义规则别直接改src/里的默认列表而是在components/brave_shields/browser/下找到规则加载入口通过Engine::from_rules追加。改完编译后验证方法是打开开发者工具在 Console 里执行// 检查当前页面的拦截规则是否包含自定义条目 const rules await chrome.braveShields.getRules(); console.log(rules.filter(r r.includes(your-custom-rule)));如果返回空数组说明规则没加载上检查gn args里brave_shields_enabled是否为 true以及规则文件路径是否被正确打包进resources.pak。5.2 用--enable-logging看拦截日志编译出的浏览器启动时加--enable-loggingstderr --v1可以在终端看到拦截引擎的详细日志。我一般会过滤adblock关键字./out/Default/chrome --enable-loggingstderr --v1 21 | grep -i adblock日志里会显示每条规则匹配了哪个请求如果某条规则一直不生效先看日志里有没有rule parsed没有就是规则语法写错了。5.3 跨平台产物验证清单编译完成后别急着打包先按这个清单过一遍平台验证项命令/操作Linux可执行文件依赖ldd out/Default/chrome看有无 missingWindows签名与版本右键属性看版本号是否和gn args一致macOS公证与权限codesign -dv out/Default/Chromium.appAndroidAPK 安装adb install out/Android/apks/Brave.apk我吃过一次亏Linux 下编译通过但ldd显示缺libnss3.so拿到另一台机器上直接跑不起来。从那以后我每次编译完都强制走一遍ldd和codesign不管多急。希望帮到你。本文还有配套的精品资源点击获取