Distroless 贡献指南：从 Bazel 构建、测试到提交补丁的完整工作流
2026/10/1 2:12:26
前阵子接了个活，客户要求在Windows桌面上做一个带内嵌浏览器的管理端，页面里有大量的H5动画、WebGL展示，还要能跟本地Delphi业务逻辑互相传数据。项目一开始我脑子里蹦出来的还是老一套：TWebBrowser套IE内核。结果一调试，WebGL直接白屏，ES6语法半残，页面频繁卡死。后来换成Edge浏览器组件（WebView2）配合Delphi的TEdgeBrowser，问题迎刃而解。这篇就专门聊聊怎么在Delphi项目里把Edge浏览器组件用起来，包括环境准备、界面集成、JS双向交互、下载拦截、常见坑排查，以及我实际跑项目的一些体会。
1. 为什么在Delphi项目里选Edge浏览器组件
1.1 从TWebBrowser到TEdgeBrowser的演进
早些年做Delphi桌面端内嵌网页，用的都是TWebBrowser。这组件本质上是IE内核的OLE容器，系统装的是什么IE，它就渲染成什么样。在XP、Win7时代还能忍，但放到今天，问题已经藏不住了：
- 页面用了ES6、CSS Grid、Flexbox等现代Web技术时，IE内核渲染经常错乱
- WebGL、Canvas 3D这些能力基本是残废状态，地图类、模型展示类需求直接没戏
- 每次系统更新或IE被禁用，组件行为就可能变化，排查起来一头雾水
我有一次被客户现场反馈"页面按钮点了没反应"，远程一看，系统是精简版Win10，IE组件被精简掉了，TWebBrowser直接白板。这种问题靠代码很难兜底，因为底层内核不由你控制。
Delphi从10.4版本开始正式引入TEdgeBrowser组件，底层走的是WebView2 Runtime。WebView2以微软Edge（Chromium内核）为渲染引擎，独立于IE，也不会被系统精简影响，只要你把运行时安装包带上，程序行为就非常稳定。对Delphi开发者来说，等于是在VCL里直接拿到了一套现代浏览器核心，体验和Chrome保持一致。
1.2 WebView2与Edge组件的核心优势对照
很多人会问：既然是要Chromium内核，那我用CEF（Chromium Embedded Framework）不是也可以？确实可以，但两者取舍很不一样。
| 对比项 | TEdgeBrowser + WebView2 | CEF |
|---|---|---|
| 安装包体量 | 运行时约100多MB，可引导安装，程序本身不用打包内核 | 需要随程序分发完整Chromium，动辄200MB以上 |
| 系统集成度 | 与系统Edge共享运行时，更新由微软统一推送 | 依赖自己分发的内核版本，需自己追踪升级 |
| 内存占用 | 多进程模型，已优化，相同页面通常比CEF表现更稳 | 可定制性强，但需要自己做进程管理和内存回收 |
| 编译依赖 | Delphi 10.4+自带组件，无需额外引入 | 需要下载CEF的Delphi封装库并自己编译 |
| JS与本地交互 | 官方提供WebMessage机制，封装比较完整 | 一般通过自定义Scheme或扩展，工作量大一些 |
我自己的体感是：如果是产品原型、企业管理系统、内部工具，TEdgeBrowser在交付效率和维护成本上完胜；如果是要做白标浏览器、深度定制下载协议、Modify内核行为，CEF的灵活度更高。但这个项目情况很简单：页面和JS都是现成的，我需要的是稳定加载和通信，所以直接选了TEdgeBrowser。
2. 环境准备与运行时依赖
2.1 安装Delphi对应版本与WebView2运行时
先说版本，TEdgeBrowser不是所有Delphi版本都有。我查过，从RAD Studio 10.4（Sydney）开始，VCL里才提供了TEdgeBrowser组件，后续的11.x、12.x都一直维护。如果你的Delphi还停留在10.3或者更老的XE系列，很遗憾，需要升级IDE才能直接用这个组件。不想升级的话，也可以手工引用RAD Studio安装目录里的WebView2相关单元（Winapi.WebView2、Vcl.Edge），但配置起来比较折腾，不推荐。
代码层面，需要引用的单元是：
uses Winapi.WebView2, Vcl.Edge;然后还要确认目标机器装了WebView2 Runtime。这里有个关键点：Windows 11是自带WebView2 Runtime的，而Windows 10大多数情况已经通过Windows Update推送过，但总有个别环境没有。所以我建议在安装包制作时就把WebView2 Runtime的常青版引导安装程序带上，大约一两MB，它会在用户机器上自动下载匹配架构的运行时并静默安装。安装参数里面最常用的就是：
MicrosoftEdgeWebview2Setup.exe /silent /install如果你不想用引导程序，也可以直接下载固定的完整运行时安装包（evergreen standalone installer），随程序一起分发。两种方式我都试过，引导安装包体积小、逻辑省心，推荐优先考虑。
2.2 区分32位与64位目标平台的坑
这块坑特别多，先记结论：WebView2运行时分32位和64位两个版本，你编译出的Delphi程序是什么位数的，它就得加载对应位数的运行时组件。
比如程序是32位编译，跑在64位系统上，WebView2会自动使用32位运行时；你单独去装一个64位运行时，不会给32位程序带来任何提升，反而可能出现组件状态不匹配的假象。反过来，64位程序只装了32位运行时，运行时会直接初始化失败，表现为TEdgeBrowser.CreateBrowser接口返回错误码。
我在实际项目中遇到过同样的问题：开发机64位系统、64位运行时，平时调试没问题，结果打包给客户的时候因为安装了精简版系统，WebView2 Runtime没装上，程序一启动就黑屏。后来我把检查逻辑写在启动流程里，避免了后面所有类似问题：
function IsWebView2RuntimeInstalled: Boolean; var Version: string; begin Result := GetAvailableCoreWebView2BrowserVersionString('', Version) = S_OK; end;这个函数来自Winapi.WebView2单元，它查询的是WebView2运行时在系统注册表里的存在性。如果发现没装，直接弹窗提示并调用引导安装程序，而不是让用户在程序里看到一个莫名其妙的空窗口。
另外UserDataFolder也要单独设置，这个目录存放浏览器缓存、Cookies、LocalStorage等数据。不设置的话，TEdgeBrowser会用默认目录，临时目录一清理，你的登录态就全丢了。我通常这样设置：
EdgeBrowser1.UserDataFolder := IncludeTrailingPathDelimiter( GetEnvironmentVariable('LOCALAPPDATA')) + 'MyApp_EdgeData';注意：UserDataFolder必须在CreateBrowser之前设置，否则不生效。
3. TEdgeBrowser的首次落地
3.1 从工具箱拖放组件到初始化
工具使用很直观：在VCL表单设计器里把TEdgeBrowser从Tool Palette拖到窗体上，它跟其他VCL组件一样，有Name、Align、Visible等常规属性。但有几个属性是它特有的，设置顺序很重要。
- UserDataFolder：用户数据目录，指定后浏览器缓存和状态都会写入这个文件夹
- DefaultURL：组件创建并加载页面时使用的默认地址，可以是https地址，也可以是本地HTTP地址
- ResizeBitmapScale：在高DPI环境下控制渲染缩放比例，一般设成系统DPI缩放值
从工具箱拖到窗体只是第一步，真正让浏览器内核初始化的动作发生在CreateBrowser方法里。你可以显式调用CreateBrowser，也可以在设置DefaultURL后让它内部自动初始化。我建议显式调用，方便捕获错误：
procedure TForm1.FormCreate(Sender: TObject); begin EdgeBrowser1.UserDataFolder := EdgeDataFolder; try EdgeBrowser1.CreateBrowser; except on E: Exception do ShowMessage('浏览器内核初始化失败：' + E.Message); end; end;CreateBrowser接口会校验运行时是否存在、UserDataFolder是否可写、用户Token是否有效，任何一个环节出问题都会抛异常。把这一步放在FormCreate里最合适，因为页面导航之前必须保证内核已经准备就绪。
3.2 加载本地页面与远程页面
页面加载有三种常见方式，我一个个来说：
加载远程页面
EdgeBrowser1.Navigate('https://www.example.com');这是最直接的用法。需要注意，Navigate本身不等待页面加载完成，它只是发起一个导航请求。如果你紧接着执行JS，页面可能还没准备好，就会拿到空的执行结果。
加载本地页面
本地页面路径最好通过file://协议来组织，否则转义很容易出问题：
EdgeBrowser1.Navigate('file:///' + StringReplace(APath, '\', '/', [rfReplaceAll]));有些资料建议直接把本地路径传给Navigate，实测在某些版本会触发导航失败，因为底层解析不了Windows路径。统一转成file:///协议后稳定得多。
加载内置HTML字符串
如果页面比较小，不想落地成文件，可以直接用NavigateToString：
EdgeBrowser1.NavigateToString( '<html><body><h1>Hello Delphi</h1>' + '<button id="btn">点我</button></body></html>');这个方式很适合做纯前端的配置界面，代码都在Delphi里，后续维护就是改字符串。
实际开发中遇到一个容易被忽视的问题：地址栏输入的中文参数没有URL编码。比如Navigate('https://api.example.com/search?keyword=测试')，底层可能会抛错或者返回空页面。正确做法是先编码再导航：
uses System.NetEncoding; var Keyword: string; begin Keyword := TNetEncoding.URL.Encode('测试'); EdgeBrowser1.Navigate('https://api.example.com/search?keyword=' + Keyword); end;这个小细节帮你省掉不少白屏排查时间。
4. 与JavaScript的双向交互
4.1 ExecuteScript调用JS函数
TEdgeBrowser提供了ExecuteScript方法，可以直接在页面上下文中执行JavaScript。它是异步的，返回值不是直接给Delphi变量，而是通过回调函数返回。
EdgeBrowser1.ExecuteScript( 'document.getElementById(''username'').value = ''admin'';' + 'document.getElementById(''loginBtn'').click();');执行后，页面里的input会被赋值并触发登录按钮点击。由于操作的是DOM，执行时机的把握很关键。页面还没加载完就执行，可能拿到一个空的元素引用。常见做法是在NavigationCompleted事件里做首次执行，之后再由Delphi逻辑按需调用。
如果JS返回的是JSON字符串或对象，ExecuteScript的回调参数其实是JSON格式的字符串，需要自己解析。Delphi 10.4及以上版本有System.JSON可用，直接JSONObject.ParseJSONValue就能拿到对应字段。
4.2 从JS侧回传数据给Delphi
反向通信更符合WebView2的设计思路。页面里可以通过内置的window.chrome.webview对象给宿主程序发消息：
window.chrome.webview.postMessage( JSON.stringify({ type: 'loginResult', username: 'admin', token: 'abc123' }) );Delphi这边需要设置WebMessageReceived事件：
procedure TForm1.EdgeBrowser1WebMessageReceived(Sender: TObject; const WebMessageAsJson: string); begin // WebMessageAsJson就是页面postMessage传入的字符串 HandlePageMessage(WebMessageAsJson); end;这里有个优先级很高的经验：postMessage到达Delphi事件时的线程不一定是UI线程。WebView2底层是多进程架构，网页进程向宿主进程发送消息时，Delphi事件可能会在工作线程里触发。如果你在这个事件里直接操作UI控件（比如给Label赋值、弹ShowMessage），极大概率遇到"Canvas does not allow drawing"或者控件状态不一致的错误。正确的姿势是用TThread.Queue把UI操作切回主线程：
procedure TForm1.EdgeBrowser1WebMessageReceived(Sender: TObject; const WebMessageAsJson: string); begin TThread.Queue(nil, procedure begin Label1.Caption := WebMessageAsJson; end); end;页面侧也可以通过postMessage发送非字符串数据吗？规范上postMessage是可以传对象的，但WebView2在回传宿主时，Delphi事件拿到的WebMessageAsJson已经是序列化后的JSON字符串。如果JS直接传对象，这个JSON是浏览器自动序列化的；如果JS自己先JSON.stringify再传，那Delphi收到的就多了一层字符串。我在项目里统一约定：JS侧无论传什么，都用JSON.stringify之后再postMessage，Delphi这边收到后直接当JSON处理，两边都不需要额外的兼容逻辑。
5. 下载文件与外部协议处理
5.1 拦截下载事件并把文件存到指定目录
桌面程序里经常会遇到"点一个按钮就下载文件"的需求。默认情况下，TEdgeBrowser碰到下载动作会唤起WebView2默认下载栏，下载路径由浏览器设置决定，对用户来说体验还行，但放到企业内部管理端里，我们往往更希望文件统一存到指定目录，甚至配合后端校验权限。
WebView2本身有一套下载事件机制，CoreWebView2有DownloadStarting事件，可以拦截下载、设置目标路径。在Delphi的TEdgeBrowser里，这个事件被封装成可以处理的接口。我自己做的时候是先通过NavigationStarting判断请求链接，再把下载任务转成业务逻辑：
procedure TForm1.EdgeBrowser1NavigationStarting(Sender: TObject; const NavigationStartingEventArgs: ICoreWebView2NavigationStartingEventArgs); var Url: string; begin Url := NavigationStartingEventArgs.Uri; if IsDownloadUrl(Url) then begin // 记录下载地址，用Delphi自己的HTTP组件下载 // 或者引入WebView2的ICoreWebView2DownloadStartingHandler处理。 end; end;这里要区分两种场景：一种是普通网页里的超链接下载，另一种是页面通过JavaScript发起Blob下载。前者可以用导航拦截处理，后者用NavigationStarting是拦不住的，因为在WebView2的视角里它不是一次导航。遇到Blob下载需求，建议让页面把数据内容以postMessage的方式回传给Delphi，由Delphi侧自行保存文件，这样最可控。
5.2 处理下载时的进度反馈
进度反馈我踩过几次坑。理想状态下，应该有类似OnDownloadProgress的事件，但Delphi封装里没有直接暴露这个事件。常规做法是监听CoreWebView2的DownloadStateChanged和BytesReceivedChanged事件，这些是WebView2 Runtime在发消息给宿主，Delphi侧要通过ICoreWebView2DownloadOperation接口手动维护状态。
直接操作COM接口确实麻烦，所以我更推荐一个现实方案：WebView2页面里的下载由前端自己控制进度条，下载动作通过postMessage告诉Delphi，Delphi负责发起真正的HTTP请求并保存文件，然后把进度反馈回页面。这样进度条展示、取消下载、断点续传都变得非常清晰，不需要跟COM接口纠缠。
这算是经验之谈：TEdgeBrowser能做的事情很多，但"让WebView2管下载"并不是它的强项。能用前端分下载任务，就别硬塞给浏览器内核。
6. 常见异常与排查
6.1 CreateBrowserFailed问题
这是每次让我同事最头疼的问题。TEdgeBrowser在CreateBrowser的时候，如果抛出"CreateBrowserFailed"或者错误码为负数的情况，我一般按下面的链路排查：
- 是否装了WebView2 Runtime。打开cmd执行
reg query "HKLM\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}"，如果键不存在，说明没装运行时。 - UserDataFolder目录是否被其他进程占用。曾经遇到杀毒软件锁定了Data目录，导致初始化失败，换个目录就正常。
- 系统环境变量是否异常。WebView2初始化需要读取系统目录，如果PATH被改坏，也可能导致组件加载失败。
- 确认程序位宽与运行时位宽匹配。32位程序配32位运行时，64位程序配64位运行时。
我自己的处理方式：在FormCreate里做一次运行时检测，发现异常时直接引导用户修复，不进入主界面。
6.2 加载白屏、无法打开DevTools
白屏是第二大高频问题。遇到白屏先别怀疑组件坏了，按概率从高到低排查：
- URL没编码，尤其是带中文和特殊符号的情况
- HTTPS页面的证书有问题，WebView2默认拒绝加载
- 页面里混合内容被浏览器拦截，比如HTTPS页面里引用了HTTP资源
- 后端接口没有正确的CORS头，页面JS获取数据失败导致界面空白
调试方面，一个很好用的技巧是给WebView2加上远程调试参数。在程序启动时设置环境变量：
SetEnvironmentVariable('WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS', '--remote-debugging-port=9222');运行程序后，打开Chrome或Edge浏览器访问http://localhost:9222，就能看到TEdgeBrowser里加载的页面DOM、Network请求和Console日志。这个调试方式能省下大量时间，尤其是页面渲染异常时，你可以在DevTools里逐条看报错。
还有一点容易被忽略：当操作系统的用户账户是普通权限时，WebView2内部的一些浏览器特性（比如本地数据存储）可能受到限制。表现就是页面加载正常，但功能不完整。这里没有完美的代码解法，只能建议尽量以普通用户权限运行，并确保UserDataFolder目录对当前用户可写。
6.3 会话Cookie丢失与登录态失效
管理端一般都需要登录。用TEdgeBrowser打开登录页，成功后页面里的Cookie、LocalStorage会自动写入UserDataFolder。但如果你换了一个UserDataFolder，或者程序被360/电脑管家清理了临时目录，登录态就丢了。解决办法很直接：把UserDataFolder指定到安装目录下的固定子目录，并在卸载时删除。
还有一个细节，某些页面在iframe里嵌入第三方登录（比如微信扫码），需要给WebView2开启第三方Cookie支持。这个在TEdgeBrowser里没有界面开关，但可以通过设置额外浏览器参数--enable-features=ThirdPartyStoragePartitioning之类的方式控制，具体的特性开关要根据WebView2 Runtime版本查阅文档。实测下来，多数登录场景默认配置就能跑通，不需要额外配置。
7. 一些真实体验与性能建议
7.1 内存释放与页面切换优化
TEdgeBrowser一个实例就是一个浏览器进程组，包含主进程、渲染进程、GPU进程等。在主界面里开一个实例没大问题，但如果开多个TEdgeBrowser实例（比如Tab页风格），内存消耗会比较明显。每个实例都有自己的渲染进程、GPU进程和网络进程，10个Tab就是10组进程，再大的内存也会被吃掉。
我实际测试过一个中等复杂度的H5管理后台，单个TEdgeBrowser实例空闲时大约占用80MB内存，打开几个动态页面后能涨到200MB甚至更高。如果是多个实例，内存不释放会成为主要矛盾。所以项目里如果要做多标签页，尽量别开多个TEdgeBrowser实例，而是用一个实例配合前端路由切换页面，或者关闭当前内容后再Navigate到新页面。
组件复用还有一个坑：Navigate到一个新页面后，之前的JS上下文就失效了。如果你用全局变量保存了页面里的某些状态，切换页面再回来，状态已经没了。解决办法是维持一个"页面状态管理"机制，在Navigate完成后重新注入状态数据。
7.2 与JS交互的异步线程模型
TEdgeBrowser的ExecuteScript是异步的，它的回调有可能是工作线程里触发的。虽然大多数时候回调会在UI线程，但严谨的产品代码不能依赖这一点。凡是回调里要操作VCL控件的，一律用TThread.Queue包一层。
反过来，JS给Delphi发消息也是异步的，也可能不在UI线程。我见过有同事在WebMessageReceived事件里直接调用业务模块读写数据库，结果偶发异常。正确的做法是：这个事件里只做数据解析和记录，然后TThread.Queue把具体业务调度到主线程执行。
7.3 混合渲染模式的选择心得
项目里如果既有原生VCL控件又有网页内容，布局和层级会成为麻烦。TEdgeBrowser本质是一个窗口句柄，它天然会盖住其他普通控件。在一个Panel里放TEdgeBrowser和几个按钮，如果不做处理，按钮很可能被浏览器窗口遮挡。解决办法有几个：
- 把按钮放在TEdgeBrowser之外的区域，避免重叠
- 需要悬浮覆盖时，使用置顶特性的小窗体或自定义控件
- 尽量把需要交互的页面元素放到HTML内部，让前端承担交互
我最终选择了"所有交互都在页面内"的方案，Delphi只负责底层能力和业务调度，页面交互全部由HTML/CSS控制。这样VCL控件和浏览器重叠的问题就彻底不存在了，代码也清爽很多。
至于性能优化，如果页面里有定时器或者WebSocket频繁推送，CPU占用会明显上升。建议前端做好节流，后端推送只推变化数据，不要整页刷新。Delphi侧也可以监控NavigationCompleted和WebMessageReceived之间的时间差，评估页面处理的耗时。
最后分享几个值得养成的习惯
- 所有浏览器初始化相关的属性设置，比如UserDataFolder、DefaultURL，建议都放到CreateBrowser之前完成。
- CreateBrowser最好放在FormCreate，别等用户点按钮再创建，否则首次打开会有一段白屏等待。
- 退出程序时调用EdgeBrowser1.Shutdown，否则偶尔会有WebView2子进程残留。
- 发布给客户前，做一次全新机器测试：不装任何运行库，只有操作系统，验证安装包能否自动把WebView2 Runtime装好。
- Debug版本里常驻远程调试端口，Release版本务必移除，避免无关人员通过DevTools调试你的应用。
TEdgeBrowser这组件我用了大半年，从最开始被各种运行时问题折磨，到后来基本能稳定预估行为，整体的感受是：它比IE时代的TWebBrowser靠谱太多，也比CEF省心太多。如果你的Delphi版本在10.4以上，又正好需要现代浏览器能力，我建议直接忘掉过去那些WebBrowser封装的偏方，把TEdgeBrowser作为首选方案。