简介CEF4Delphi控件是一套面向Delphi开发者的Chromium谷歌内核浏览器集成方案适合需要在桌面程序中嵌入现代网页渲染能力的开发者覆盖从Delphi 7到Delphi 10.2的多个版本作者已亲自测试调试安装正常。资源包共462个文件压缩后约1.47MB以pas单元、dfm窗体、dpr与dproj工程文件、inc与bat脚本为主另含dpk包、res资源、html与png示例素材及帮助文档结构完整便于按模块查阅。其中Chromium32位与64位框架需另行下载帮助文档对安装配置与调用方式有详细说明可帮助读者快速理解控件封装结构、掌握浏览器组件的集成与调试思路。目前已有785人学习下载适合希望为Delphi项目补充内嵌浏览器、网页交互或混合开发能力的中高级开发者参考使用。1. CEF4Delphi 控件把 Chromium 塞进 Delphi 桌面程序的那条路如果你手上有一个跑了十几年的 Delphi 桌面系统客户突然要求内嵌一个能跑现代前端框架的浏览器窗口还要能双向调用本地方法你大概率会搜到 CEF4Delphi 控件这个方案。它本质是一组 Delphi 封装把 Chromium Embedded Framework 的 C 接口翻译成 Delphi 能直接用的类、事件和回调让你在 VCL 或 FireMonkey 窗体里放一个浏览器实例加载本地 HTML 或远程页面同时通过扩展机制让 JavaScript 调用 Delphi 方法、Delphi 调用 JavaScript。适合谁适合那些不想把整个系统重写成 Electron、又必须让界面跟上现代 Web 技术栈的团队。它解决的不是“怎么做一个浏览器”而是“怎么让老桌面程序长出 Web 界面并且两边能说上话”。这条路能走通但版本匹配、进程模型和资源释放三个地方最容易翻车。2. 环境搭建与最小可运行实例从零跑起一个 CEF4Delphi 窗口2.1 先搞清楚 CEF4Delphi 的版本对应关系CEF4Delphi 本身是 Delphi 封装层它依赖两个东西Delphi 编译器版本和 CEF 二进制版本。常见做法是去项目仓库下载对应 Delphi 版本的包里面已经按 CEF 分支分好目录。我一般会先确认三件事Delphi 是 10.x 还是 11/12、目标平台是 Win32 还是 Win64、CEF 用的是哪个大版本分支。这三者不匹配编译能过运行时直接黑屏或崩溃。一个血泪经验不要混用不同来源的 CEF 二进制文件。CEF4Delphi 的封装代码和 CEF 的 C API 头文件是绑定的你从 A 处拿封装、从 B 处拿 libcef.dll版本差一点就可能出现“窗口能创建但渲染进程起不来”的玄学问题。稳妥做法是只用项目自带的二进制包或者严格按它文档里标注的 CEF 版本去官方构建下载。2.2 最小工程一个窗体加一个 TChromium下面是一个最小可运行示例的核心代码。假设你已经把 CEF4Delphi 的源码目录加入搜索路径并且把 CEF 二进制文件放到了可执行文件同级目录。unit UnitMain; interface uses Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, uCEFApplication, uCEFChromium, uCEFWindowParent; type TFormMain class(TForm) ChromiumWindow: TCEFWindowParent; // 承载浏览器窗口的父容器 Chromium: TChromium; // 浏览器实例 procedure FormCreate(Sender: TObject); procedure FormShow(Sender: TObject); procedure FormCloseQuery(Sender: TObject; var CanClose: Boolean); procedure ChromiumAfterCreated(Sender: TObject; const browser: ICefBrowser); private FCanClose: Boolean; end; var FormMain: TFormMain; implementation {$R *.dfm} procedure TFormMain.FormCreate(Sender: TObject); begin // 创建浏览器指定父容器和初始 URL Chromium.CreateBrowser(ChromiumWindow); end; procedure TFormMain.FormShow(Sender: TObject); begin // 窗体显示后再加载页面避免窗口句柄未就绪 Chromium.LoadURL(https://example.com); end; procedure TFormMain.ChromiumAfterCreated(Sender: TObject; const browser: ICefBrowser); begin // 浏览器创建完成可以在这里做后续操作 Caption : CEF4Delphi 已就绪; end; procedure TFormMain.FormCloseQuery(Sender: TObject; var CanClose: Boolean); begin // 关闭前先通知浏览器关闭否则进程可能残留 CanClose : FCanClose; if not FCanClose then Chromium.CloseBrowser(True); end; end.逻辑说明TCEFWindowParent是一个特殊容器它负责把 Chromium 的原生窗口句柄嵌到 VCL 窗体里。TChromium是浏览器控制对象CreateBrowser触发创建流程AfterCreated事件表示浏览器进程和渲染进程都准备好了。FormCloseQuery里先调CloseBrowser等浏览器真正关闭后再允许窗体关闭这是避免进程残留的关键。参数说明CreateBrowser的第二个参数是初始 URL可以传空字符串后续用LoadURL加载。CloseBrowser(True)里的True表示强制关闭会等待所有子进程退出。如果你在AfterCreated之前就调LoadURL可能因为浏览器还没创建完而无效所以放在FormShow里更稳。2.3 初始化 CEF 全局上下文别漏了这一步上面的代码能跑但前提是 CEF 的全局初始化已经完成。常见做法是在项目文件里创建主窗体之前初始化 CEF 应用对象。program ProjectMain; uses Vcl.Forms, uCEFApplication, UnitMain in UnitMain.pas {FormMain}; {$R *.res} begin // 初始化 CEF指定子进程可执行文件路径和资源目录 CefSingleProcess : False; // 多进程模式更稳定 if not CefLoadLibDefault then begin MessageBox(0, CEF 初始化失败, 错误, MB_ICONERROR); Exit; end; Application.Initialize; Application.MainFormOnTaskbar : True; Application.CreateForm(TFormMain, FormMain); Application.Run; // 退出前清理 CEF CefShutdown; end.逻辑说明CefLoadLibDefault会加载 libcef.dll 并初始化 CEF 运行时。CefSingleProcess设为 False 表示使用多进程架构浏览器进程、渲染进程、GPU 进程分开这是推荐做法。CefShutdown必须在所有浏览器窗口关闭后调用否则可能卡死。参数说明CefLoadLibDefault内部会去可执行文件目录找 CEF 的二进制文件和 locales 资源目录。如果你把 CEF 文件放在子目录需要改用带路径参数的重载版本。CefSingleProcess : True只在调试特定问题时用生产环境不要开单进程模式下渲染崩溃会拖垮整个应用。3. Delphi 与 JavaScript 双向通信让本地方法和网页说上话3.1 扩展机制JS 调 Delphi 的标准姿势CEF4Delphi 支持通过ICefRenderProcessHandler注册扩展让 JavaScript 能调用 Delphi 方法。常见做法是定义一个扩展对象在渲染进程里注册一个 JS 函数这个函数通过消息把参数传回浏览器进程再由 Delphi 处理。type TMyRenderProcess class(TCefRenderProcessHandlerOwn) protected procedure OnWebKitInitialized; override; end; procedure TMyRenderProcess.OnWebKitInitialized; var Code: string; begin // 定义 JS 端可调用的扩展函数 Code : var nativeApp { callDelphi: function(method, args) { native function CallDelphi(); return CallDelphi(JSON.stringify({method: method, args: args})); } };; CefRegisterExtension(v8/nativeApp, Code, nil); end;逻辑说明CefRegisterExtension注册的代码会在每个页面加载时注入。native function CallDelphi()是 CEF 提供的桥接声明它会把调用转发到浏览器进程的OnProcessMessageReceived事件。你在那里解析 JSON根据 method 名分发到对应的 Delphi 方法。参数说明扩展名v8/nativeApp是自定义标识保持唯一即可。Code里的JSON.stringify是为了把复杂参数序列化成字符串避免 CEF 消息只支持简单类型的限制。如果你只需要传字符串可以简化。3.2 浏览器进程侧接收 JS 消息并分发在浏览器进程的TChromium上处理OnProcessMessageReceived解析来自渲染进程的消息。procedure TFormMain.ChromiumProcessMessageReceived(Sender: TObject; const browser: ICefBrowser; sourceProcess: TCefProcessId; const message: ICefProcessMessage; out Result: Boolean); var MsgJson: string; MethodName: string; begin Result : False; if message.Name callDelphi then begin MsgJson : message.ArgumentList.GetString(0); // 解析 JSON取出 method 和 args MethodName : ExtractMethodName(MsgJson); if MethodName getVersion then begin // 执行本地方法把结果通过 JS 回调返回 browser.MainFrame.ExecuteJavaScript( window.nativeAppCallback( GetAppVersion ), , 0); Result : True; end; end; end;逻辑说明message.Name对应 JS 端native function的名字。ArgumentList.GetString(0)取出 JS 传过来的 JSON 字符串。处理完后用ExecuteJavaScript把结果回传给页面。这里要注意ExecuteJavaScript是异步的页面需要提前定义好回调函数。参数说明sourceProcess可以用来判断消息来自哪个进程一般不用管。ExecuteJavaScript的第二个参数是脚本 URL传空字符串即可。第三个参数是起始行号传 0。3.3 Delphi 调 JSExecuteJavaScript 的正确用法反过来Delphi 主动调 JavaScript 更简单直接调ExecuteJavaScript。但要注意时机必须在页面加载完成后调否则函数可能还没定义。procedure TFormMain.btnCallJS(Sender: TObject); begin if Chromium.Browser nil then Chromium.Browser.MainFrame.ExecuteJavaScript( updateStatus(来自 Delphi 的消息), , 0); end;逻辑说明Chromium.Browser是当前浏览器实例MainFrame是主框架。如果页面有 iframe需要拿到对应框架再调。updateStatus是页面里预先定义好的 JS 函数。参数说明执行前最好判断Browser是否为 nil以及页面是否加载完成。可以在OnLoadEnd事件里设置一个标志位避免在页面未就绪时调用。4. 避坑与排查CEF4Delphi 最常见的五类翻车现场4.1 窗口黑屏或白屏浏览器进程没起来现象窗体显示后浏览器区域一片空白任务管理器里看不到渲染进程。原因CEF 二进制文件缺失或版本不匹配最常见的是 libcef.dll 没放到可执行文件目录或者 locales 目录缺失。解决检查可执行文件同级目录是否有 libcef.dll、chrome_elf.dll、icudtl.dat 和 locales 文件夹。用 Dependency Walker 或类似工具看 libcef.dll 是否能被加载。版本不匹配时换用 CEF4Delphi 自带的二进制包。4.2 关闭窗体后进程残留现象主窗体关了但任务管理器里还有多个进程没退出。原因没有正确调用CloseBrowser和CefShutdown或者FormCloseQuery里直接允许关闭而没有等待浏览器关闭完成。解决在FormCloseQuery里先设CanClose : False调CloseBrowser(True)在OnBeforeClose事件里再设FCanClose : True并关闭窗体。项目文件末尾确保CefShutdown被调用。4.3 JS 调用 Delphi 无响应现象页面里调nativeApp.callDelphi没有任何反应也不报错。原因扩展注册的时机不对或者OnProcessMessageReceived没有正确设置。常见的是扩展注册在浏览器进程而不是渲染进程或者消息名不匹配。解决确认CefRegisterExtension是在TCefRenderProcessHandlerOwn的OnWebKitInitialized里调的。检查message.Name是否和 JS 端native function的名字一致。可以在OnProcessMessageReceived里加日志确认消息是否到达。4.4 加载本地 HTML 文件路径踩坑现象用LoadURL(file:///C:/...)加载本地文件页面显示但 JS 或 CSS 加载失败。原因CEF 对本地文件访问有安全限制跨域或相对路径可能被拦截。解决常见做法是注册自定义协议或者用LoadHTML直接加载 HTML 字符串。如果必须用本地文件确保路径用正斜杠并且把相关资源放在同一目录下。更稳的方式是起一个本地 HTTP 服务用http://localhost加载。4.5 多显示器或高 DPI 下界面模糊现象在 4K 屏或缩放比例非 100% 的显示器上浏览器内容模糊。原因CEF 默认的 DPI 感知和 Delphi 应用的 DPI 设置不一致。解决在项目文件里调用SetProcessDpiAwareness或SetProcessDPIAware并确保 CEF 的CefLoadLibDefault之前设置好。CEF4Delphi 的部分版本支持通过TCefApplication的属性设置 DPI 行为按文档调整。5. 进阶技巧用请求拦截和自定义协议把本地资源管起来前面跑通最小实例和双向通信后真正让 CEF4Delphi 在项目里站住脚的往往是资源加载这块。我一般会做两件事注册自定义协议处理本地资源以及用请求拦截统一加请求头。自定义协议的好处是你可以用app://这样的 scheme 加载本地文件既绕开 file:// 的限制又能控制缓存和路径映射。实现方式是继承TCefSchemeHandlerFactory在Create方法里返回一个TCefResourceHandler自己处理ProcessRequest和ReadResponse。type TAppSchemeHandler class(TCefResourceHandlerOwn) protected function ProcessRequest(const request: ICefRequest; const callback: ICefCallback): Boolean; override; procedure GetResponseHeaders(const response: ICefResponse; var responseLength: Int64; var redirectUrl: string); override; function ReadResponse(const dataOut: Pointer; bytesToRead: Integer; var bytesRead: Integer; const callback: ICefCallback): Boolean; override; end; function TAppSchemeHandler.ProcessRequest(const request: ICefRequest; const callback: ICefCallback): Boolean; begin // 根据 request.Url 映射到本地文件路径 FFilePath : MapUrlToLocalPath(request.Url); FStream : TFileStream.Create(FFilePath, fmOpenRead or fmShareDenyWrite); Result : True; callback.Cont; // 继续处理 end;逻辑说明ProcessRequest里根据 URL 找到本地文件打开流。GetResponseHeaders里设置 MIME 类型和内容长度。ReadResponse里从流里读数据填到dataOut。这样页面里引用app://assets/style.css就能加载到本地文件。参数说明MapUrlToLocalPath需要自己做路径安全校验防止../跳出资源目录。GetResponseHeaders里的responseLength设为文件大小redirectUrl留空。MIME 类型根据扩展名判断常见的是 text/html、text/css、application/javascript。请求拦截则是在TChromium的OnBeforeResourceLoad事件里拿到ICefRequest对象可以改 URL、加请求头、或者直接返回一个自定义响应。我一般用它来给所有请求加统一的 User-Agent 或鉴权头避免在每个页面里单独处理。procedure TFormMain.ChromiumBeforeResourceLoad(Sender: TObject; const browser: ICefBrowser; const frame: ICefFrame; const request: ICefRequest; const callback: ICefRequestCallback; out Result: TCefReturnValue); var Headers: ICefStringMultimap; begin Headers : request.HeaderMap; Headers.Append(X-Client-Version, 1.0.0); Result : rvContinue; end;逻辑说明HeaderMap是请求头映射Append追加自定义头。Result设为rvContinue表示继续加载设为rvCancel则取消请求。参数说明X-Client-Version是自定义头名按后端约定改。注意不要覆盖 CEF 自己管理的头比如User-Agent要用request.SetUserAgent单独设。最后一个我踩过的坑自定义协议注册必须在CefLoadLibDefault之前完成否则不生效。而且注册的 scheme 名不要用http、https、file这些保留字。我一般用app或项目缩写注册时调CefRegisterSchemeHandlerFactory在OnRegisterCustomSchemes事件里加 scheme 定义。这套组合拳打下来本地资源加载、缓存控制、请求鉴权都能收进一个地方管后面换前端框架也不用动 Delphi 这边的代码。希望帮到你。本文还有配套的精品资源点击获取