简介CEF4Delphi 86.0.23.0版组件包是面向Delphi和Lazarus/FPC开发者的开源集成方案用于在桌面应用中嵌入Chromium内核。压缩包共1383个文件以pas源码、dcu编译单元、dproj工程文件、inc头文件及dll运行库为主并附带win32/win64支持包包体约143.74MB可配合Delphi开发环境直接安装使用。已有1282人学习下载。内容涵盖完整项目源码、多个示例工程、资源文件与各平台配置适合从入门到进阶的开发者参考或二次开发有助于快速搭建CEF环境、理解组件封装结构并减少环境配置与调试成本。 做Delphi桌面开发这些年遇到需要内嵌网页功能的需求次数远比我预想的多。菜单页要上HTML5大屏报表要出ECharts图表系统帮助文档得塞进本地Web页面更别说那些必须嵌第三方OAuth登录页的场景。Delphi自带的TWebBrowser控件基于老的IE内核打开现代页面要么白屏要么缺功能最终几乎所有人都绕到CEF4Delphi这条路上。这次分享的CEF4Delphi 86.0.23.0版是带支持库的完整发布包解压就能在Delphi工程里跑起Chromium 86内核的嵌入式浏览器适合VCL项目上需要稳定内嵌Web前端的开发者参考。下面从版本解析、配置、代码骨架和实际踩坑四个方面展开尽量把我自己的使用体验说清楚。1. 为什么Delphi项目需要CEF4Delphi从IE控件到Chromium内核1.1 CEF4Delphi是什么它到底做了什么先讲清楚底层逻辑。CEFChromium Embedded Framework是一个开源的内嵌浏览器框架把Chromium浏览器核心封装成一套稳定的C API让原生应用可以在自己的窗口里渲染网页、处理JS、管理Cookie和缓存。CEF4Delphi就是这套C API在Delphi下的封装层把整个浏览器跑起来需要的初始化、多进程调度、事件回调都包装成VCL组件开发时直接拖一个TChromium到窗体上就能用不需要手动维护底层状态机。这个封装不是简单包装一个DLL调用而是把CEF的多进程模型、消息循环、资源加载都整合进了Delphi的Application消息循环。比如CEF要求主进程和子进程互相协作CEF4Delphi会在应用启动时用GlobalCEFApp去初始化再通过StartMainProcess统一处理主进程和子进程的分支。原理上理解清楚这一点后面排查白屏、崩溃类问题会轻松很多。1.2 三类典型的嵌入式浏览器应用场景从我接触过的项目来看CEF4Delphi的应用场景基本能归成三类。第一类是“Web UI 原生壳”模式。界面用HTML/CSS/JS来写Delphi只负责窗口框架、本地文件读写、系统硬件调用。这种组合在数据大屏、报表可视化项目里特别多一套ECharts图表页面可以直接跑不用再调一个WinForms或WebView包装器。第二类是本地离线文档或资料浏览器。把帮助手册、产品说明打包成HTML资源程序里用file协议加载比维护CHM或者自带PDF查看器省事得多。CEF4Delphi对file协议、本地存储的支持很完整目录结构做对就能稳定加载。第三类是集成第三方Web服务。OAuth授权登录、在线支付页面、SaaS平台的嵌入页面这些场景要求浏览器内核不能太旧否则HTML5的API、JSON解析、新的SSL配置都可能出问题。CEF4Delphi的Chromium内核版本跟随更新天然比IE内核的TWebBrowser靠谱。我早期有个项目用的TWebBrowser客户反映页面按钮点不动查下来是页面里用了ES6的Promise、async/await老IE内核直接解析失败。换成CEF4Delphi之后这种兼容性问题基本消失因为Chromium 86对现代Web标准的支持已经是完整水平Promise、fetch、WebSocket、WebGL、WebAssembly都能跑大部分客户端Web需求不用再额外做降级方案。说一句大实话虽然CEF4Delphi新版本已经更新到更新内核但86.0.23.0这个版本在今天不少生产环境里仍然能打原因在于它在功能完整度和资源占用之间平衡得比较好比Chromium 90的版本内存占用明显低开一个嵌入式页面大概多个几十MB对于传统的桌面客户端来说完全能接受。另外CEF4Delphi是开源免费的遵循LGPL相关的使用条款闭源商用项目使用时建议仔细查看对应版本的LICENSE说明避免后续授权踩线。2. 86.0.23.0版本解析版本号逻辑和“带支持库”的含义2.1 版本号到底代表什么CEF4Delphi的版本号是跟随CEF版本走的。86.0.23.0这4段里86对应Chromium 86大版本0.23是CEF的补丁维护版本最后一个0是CEF4Delphi封装层的修复版本。也就是说86.0.23.0这个版本是基于Chromium 86内核做的封装不是“第86次发布”这种意思。理解这个命名规则很重要因为很多新手会把CEF4Delphi的版本号当成自己的发布迭代看到86就觉得“版本太高了”其实86只是Chromium的大版本号。Chromium 86大概在2020年10月发布支持完整的ES2015到ES2020大部分特性、WebGL2、WebAssembly、Service Worker等关键能力。如果项目里需要加载的网页不太新86足够稳定如果页面依赖了2022年以后的浏览器新特性比如某些新的CSS容器查询或者最新的Array方法那就得考虑升级到更新内核的版本。这点在选择版本时一定要先验证目标页面在Chromium 86上的兼容性不要拿到手闷头开发到最后才发现核心页面渲染不出来。2.2 “带支持库”的目录结构“带支持库”意味着发布包中已经包含了CEF运行所需的完整二进制文件解压后无需再去CEF官方下载对应版本的binaries。这一步省掉的是最常见的版本错配坑因为手工下载时如果误用了CEF 85或87的二进制运行时大概率会出现莫名其妙的崩溃、加载失败排查起来很痛苦。支持库目录里这些文件都有明确的作用按经验删不得libcef.dll核心引擎整个Chromium都在里面体积最大少了它程序直接启动失败。icudtl.datICU的Unicode数据处理文件负责字符集、国际化、字符串处理删了会出现乱码和崩溃。v8_context_snapshot.bin和snapshot_blob.binV8 JavaScript引擎的启动快照加速页面脚本初始化。locales目录各语言包资源。swiftshader目录软渲染实现GPU不可用时兜底渲染。resources目录CEF自带的Web资源比如错误页、内置UI。举个例子老有人觉得“我页面只有中文locales里只留zh-CN.pak好省体积”实测删掉英文语言包后有些地址栏输入、右键菜单的默认行为会回退异常甚至触发CEF的断言。所以包里带什么就保留什么不要动。实际部署时这些文件必须跟exe在同一目录或者通过WorkingDir等参数指定正确路径否则CEF初始化时找不到libcef.dll就直接退出。我在使用时习惯把支持库文件以文件拷贝方式放到发布目录避免被IDE的build行为覆盖或者漏拷。3. 从下载到跑通示例完整配置流程3.1 下载、解压和目录规划拿到86.0.23.0带支持库发布包后先解压到一个目录。我通常建议不要解压到带有空格和中文的路径下虽然CEF4Delphi对长路径容忍度比早期好一些但工具链和编译期仍可能出现不可预期的路径问题。我见过有人把项目放到“E:\我的项目\客户端”下编译一切正常但运行时CEF的子进程起不来后来放到纯英文路径就稳定了。目录规划建议是D:\CEF\cef4delphi\ 源码工程目录 D:\CEF\cef4delphi\cef\ 支持库和CEF二进制目录 D:\CEF\myproject\ 你自己的工程目录自带Demo工程可以直接在cef4delphi目录下打开但真正做项目时建议把源码目录视为只读引用单独建工程避免升级组件时把业务代码弄乱。我自己的习惯是源码和Demo单独放一个开发目录业务工程放到另一个位置用Library Path引用组件源码这样升级组件版本时不用动业务工程结构。3.2 Delphi环境设置打开Delphi IDE后在Tools Options Language Delphi Library中把源码目录下的Source路径加入Library Path。CEF4Delphi的源码组织方式一般是根目录下的Source和第三方依赖目录都要加。如果不加打开Demo工程时会有大量找不到单元的报错因为很多公共单元被设计成通过Library Path引用而不是直接放到每个工程里。不同Delphi版本的Library Path配置界面有一点差异但核心都是把“目录”加入搜索路径。另外确认你的Delphi版本在CEF4Delphi支持范围内86.0.23.0官方支持Delphi 10.2、10.3、10.4这些常见版本新一点的Delphi 11、12也能用但如果遇到编译期不兼容优先检查是否缺了官方要求的条件编译符号。我实际使用中会再建一个仅包含当前项目相关单元的顺序列表因为Library Path虽然能解决单元搜索但多个版本的CEF4Delphi如果同时存在于Library Path里IDE会随机命中一个编译出来就不是你预期的API了。这个问题在笔记本上装了多个Delphi版本的开发环境里尤其常见。3.3 编译并运行第一个Demo官方Demo很多最推荐先跑SimpleBrowser。打开dpr后直接编译如果编译通过运行目录下会自动带出支持库文件——前提是输出目录和cef二进制路径配置正确。CEF4Delphi的工程里一般会做后置构建事件或者引用文件拷贝把cef目录里的支持库复制到输出目录。第一次运行时如果闪退多半是支持库没在exe旁边。打开Windows任务管理器如果看不到进程直接去exe所在目录检查libcef.dll、icudtl.dat等文件是否存在。这一步排查其实很简单把发布包里cef目录下的所有文件先完整拷到输出目录再运行基本能解决。跑通SimpleBrowser后可以打开SimpleBrowser2它演示了更完整的页面导航、调试模式、JS执行等交互能力。这个Demo很适合作为新工程的基础模板我在实际项目中经常直接复制SimpleBrowser2的工程结构调整能少踩不少坑尤其是它把初始化参数、缓存目录、日志开关都已经写好了改一改就能用。4. 接入真实项目的核心代码骨架4.1 在工程文件里初始化CEF跑通Demo后接入自己的工程第一步是配置dpr。在Application.CreateForm之前必须先创建并启动CEF。我项目的dpr核心代码大概是这样的program MyClient; uses System.SysUtils, System.IOUtils, Vcl.Forms, uMainForm in uMainForm.pas, uCEFApplication in uCEFApplication.pas; {$R *.res} begin PlatformReportMemoryLeaksOnShutdown : False; GlobalCEFApp : TCefApplication.Create; try GlobalCEFApp.WorkingDir : ExtractFilePath(Application.ExeName); GlobalCEFApp.RootCacheDir : ExtractFilePath(Application.ExeName) CEFCache; GlobalCEFApp.Cache : ExtractFilePath(Application.ExeName) CEFCache; GlobalCEFApp.EnableHighDPISupport : True; GlobalCEFApp.StartMainProcess; if GlobalCEFApp.ProcessType ptBrowser then begin Application.Initialize; Application.CreateForm(TMainForm, MainForm); Application.Run; end; finally GlobalCEFApp.Free; end; end.注意StartMainProcess这个调用是整个初始化中最核心的部分。它做的事情不是简单的启动服务而是判断当前进程是主浏览器进程还是CEF派生的子进程如果是子进程它会直接进入CEF的子进程消息循环不再执行后面的Application.Run只有主浏览器进程才会继续出来创建窗体。所以判断用ProcessType ptBrowser来控制是否创建主窗体比单纯看返回布尔值更严谨。这个细节我抄了很多例程都没写因为在多进程模型下子进程也会进入dpr入口如果你不拦一下程序可能开出一堆窗口。WorkingDir必须设置成exe所在目录否则支持库查找可能失败。RootCacheDir和Cache指定了浏览器缓存位置我建议在自己项目里给一个独立文件夹方便升级版本时清理缓存避免旧缓存影响新页面显示。日志方面如果不需要调试尽量关闭GlobalCEFApp.LogFile和相关的详细日志否则运行一段时间后日志文件会膨胀得很快。4.2 用TChromium加载页面初始化完成之后窗体内放置一个TChromium组件核心设置如下begin Chromium1.DefaultURL : https://example.com; Chromium1.Align : alClient; Chromium1.Parent : PanelMain; Chromium1.CreateBrowser; end;把DefaultURL设置好CreateBrowser之后组件会自动加载页面。TChromium封装了很多事件常用的有OnLoadEnd、OnLoadError、OnBeforeBrowse、OnCertificateError等。我做项目时一般会在OnLoadEnd里做页面就绪判断OnLoadError里做加载失败提示这两个事件对用户感知影响最大是排查问题的一线入口。如果你不想手动管理嵌入窗口的尺寸和位置也可以直接使用TChromiumWindow。这个类把TChromium和承载它的窗口容器封装在一起窗体上放一个TChromiumWindow设置好DefaultURL运行时它会自己处理窗体嵌入。SimpleBrowser3和SimpleBrowser4两个Demo演示的就是这种用法代码量能少三分之一适合快速搭原型。还有一点TChromium本身不是TWinControl标准的可视化控件它内部是CEF提供的原生窗口所以Align、Parent这些属性虽然可以用但在窗体Resize、Dock操作特别频繁时偶尔会出现渲染画面和窗体不同步的问题。实际项目中我会在FormResize后主动延迟刷新一下或者调用与之相关的大小通知方法具体名称以当前版本API为准解决画面撕裂或空白区域的问题。4.3 与网页做JS双向通信浏览器组件最难的部分通常是和页面的数据交互。CEF4Delphi实现JS通信有几种常用方式。第一种是在页面加载时注册JS扩展让网页可以调用原生Delphi函数但实现起来相对重需要理解CEF的扩展注册机制。第二种方式是拦截导航请求用自定义协议跳转。这个方式很实用不依赖完整的JS Binding注册procedure TMainForm.Chromium1BeforeBrowse(Sender: TObject; const browser: ICefBrowser; const frame: ICefFrame; const request: ICefRequest; user_gesture, is_redirect: Boolean; out Result: Boolean); begin if Pos(myapp://, request.Url) 0 then begin DoNativeAction(request.Url); Result : True; // 阻止页面跳转 end; end;页面里点击某个按钮用location.hrefmyapp://openfile?pathxxx触发Delphi侧拦截后调用本地功能。这种方式实现简单逻辑清晰出问题也容易跟踪是我在多个项目里首选的通信方案。第三种方式是执行页面里的JavaScript。通过Chromium1.Browser.MainFrame.ExecuteJavaScript(alert(1);, , 0)可以在页面上下文里执行任意JS适合把Delphi数据推给页面。如果只是做页面和原生数据的双向同步我建议自定义协议和ExecuteJavaScript组合使用够用且维护成本低。完整JS绑定虽然看起来很酷但在86.0.23.0这个版本里写起来绕调试也不够直观除非你有大量高频数据交互否则不建议一上来就用。5. 实测中容易踩的坑和避坑经验5.1 白屏问题CEF4Delphi用起来最常见的现象就是窗口出来了里面一片白。这个问题的原因通常分三类。第一类是GPU渲染问题。Chromium默认启用GPU加速在虚拟机、远程桌面、老旧显卡驱动的机器上GPU进程可能起不来导致白屏。遇到这种情况在初始化时关掉GPU加速GlobalCEFApp.EnableGPU : False;重新编译运行绝大多数白屏能解决。代价是页面滚动、动画的流畅度会降一些但稳定性优先。我甚至遇到过一个金融客户的办公电脑集显驱动有问题只要开了GPU必白屏关掉之后一切正常。第二类是支持库缺失或路径不对。libcef.dll、icudtl.dat、v8_context_snapshot.bin这些文件只要少一个页面就可能静默白屏而不是报错。检查exe目录下文件是否齐全注意发布时别用压缩工具漏打包。第三类是Windows的缩放比例问题。在DPI缩放较高的屏幕上嵌入式页面渲染区域会出现大片空白。设置EnableHighDPISupport之后大部分高分屏问题会缓解但个别机器仍可能出现渲染区域计算错误这时需要检查窗体创建和CEF浏览器创建时的尺寸同步。5.2 32位/64位架构和支持库错配支持库的架构必须和exe的编译目标一致。86.0.23.0版本同时提供了win32和x64的CEF二进制如果你的Delphi工程编译成32位而libcef.dll是64位程序一启动就会报“Cannot load libcef.dll”或者直接崩溃。这个坑看着低级但项目换电脑、换编译配置后很容易踩到因为IDE的默认Target Platform可能被改掉。检查方法很直接在Windows资源管理器里看exe架构或者在任务管理器的详细信息页确认进程是32位还是64位然后确认libcef.dll的架构。Delphi工程编译目标也要同步核对IDE右下角或Project Manager里的Target Platforms不要选错。我在项目里会单独建Release和Debug两个编译配置分别锁定32位/64位目标避免手动切换时出错。5.3 多进程架构带来的进程管理CEF是多进程架构一个主进程会衍生出GPU进程、Renderer渲染进程、网络进程等一堆子进程。正常使用时这没问题但如果你在任务管理器里看到十几个同名exe进程不要以为是病毒或内存泄漏这是CEF的正常表现每个渲染标签页或iframe都可能对应独立的渲染进程。这个架构带来的一个实际问题如果你用了全局异常处理或者进程守护逻辑子进程崩溃时会触发某些钩子可能导致程序误退出。我给项目的建议是在主进程里收集异常但不要在子进程里做复杂的异常上报CEF自己的崩溃恢复机制会处理渲染进程的崩溃页面上表现为白屏或刷新后会恢复。另外程序退出时要给CEF一点清理时间。在Application.Run结束后GlobalCEFApp.Free之前确保所有浏览器组件都已释放否则会有内存报错或崩溃日志。防止这个问题的一个简单办法是在窗体FormClose里先释放Chromium组件或者设置GlobalCEFApp.CloseAllBrowsers。我遇到过客户系统关机时弹内存错误弹窗最后就是退出顺序没处理好调整后问题消失。5.4 从旧版升级注意事项如果你是从更老的CEF4Delphi版本比如79、65之类的升级到86.0.23.0有几件事要确认。第一API变化。CEF4Delphi在版本迭代中偶尔会调整接口名称和事件签名旧工程编译时会有一堆类型不匹配。建议对照官方Demo逐个修正不要用全局替换这种粗暴方式。第二缓存目录格式变了。Chromium的缓存数据库不向前兼容升级后第一次启动如果页面显示异常或者登录状态丢失直接把Cache目录删掉重新生成就行这是正常现象。第三体积和资源占用。86内核比老版本内核大不少安装包体积会膨胀同时进程数增多这是内核升级的必然代价。如果你的目标机器硬件比较老建议仔细测试一下内存占用上限。给一个通用的建议CEF4Delphi版本升级后至少留一周的回归测试时间重点覆盖本地页面加载、JS交互、文件下载、打印预览这些常用功能因为这些模块在不同Chromium版本中的行为差异最明显。我在实际项目中通常不会追最新版而是一个大版本稳定后再考虑升级。86.0.23.0这个版本我自己在好几个老项目中用了挺长时间最大的感受是它把“能用”和“好用”之间的平衡拿捏得不错可交付体积合理、内存可控、现代Web特性覆盖够全团队接手也容易。如果你的Delphi项目正准备集成嵌入式浏览器或者正在被IE内核的TWebBrowser折磨可以先用这个带支持库版本跑通一个Demo亲手验证一遍JS交互和高分屏表现再决定是否把它引入正式项目。如果后续遇到具体的API问题按我上面给的排查思路一条条过基本能覆盖大多数坑。本文还有配套的精品资源点击获取