简介：CEF4Delphi（一个基于Chromium Embedded Framework的Delphi组件库）让开发者能在传统Delphi桌面应用中嵌入Chromium内核，借助HTML5、CSS3和JavaScript打造现代交互界面，非常适用于办公系统、数据看板及混合形态的客户端。压缩包内含该库完整源码工程，共525个文件、仅1.71MB，包括210个.pas源文件、50个.dfm窗体定义、49个.dpr/dproj工程文件，以及批处理脚本、编译配置、示例页面与图片资源等，结构紧凑，便于逐层复用。当前已有348人学习浏览。通过阅读源码和示例，可掌握TChromium组件的加载URL、导航事件、JS与Delphi对象双向调用等核心用法；同时参考不同Delphi版本的项目文件与构建脚本，能快速完成工具链配置，免去自行编译CEF库的繁琐过程。对中高级Delphi开发者而言，这份代码尤为实用，既能跟随Demo上手，也能深入理解浏览器进程与消息通信机制；压缩包中还收录了Lazarus跨平台入口、.inc条件编译脚本、应用图标和资源文件，为跨平台适配和二次封装提供了完整参考。
1. 为什么是CEF4Delphi而不是TWebBrowser
做桌面端的老Delphi项目，最尴尬的场景不是数据库慢，而是界面里嵌的那个浏览器今天连CSS3动画都跑不明白。TWebBrowser封装的是IE内核，面对现代前端页面要么渲染错位，要么交互失效，更别提WebGL和WebSocket。CEF4Delphi把Chromium Embedded Framework搬进Delphi，让Delphi 7到10.x的项目都能直接获得Chrome同级别的渲染能力，而且不是套壳网页，是原生窗体里嵌一个真正的Chromium进程。这篇博文会顺着“解包资源、配全局参数、初始化组件、处理导航事件、打通JS双向通信”这条路线，把关键代码和参数边界都拆开讲，最后收在CEF多进程模型和资源释放上——那是几乎所有自测通过但上线崩框的项目都会踩到的地方。
2. CEF4Delphi项目结构与环境初始化：从bat文件到全局参数
拿到CEF4Delphi-master.zip之后，第一件事不是急着往Delphi里装组件，而是先看清楚这个zip里躺着的是一套“源码包+构建脚本+示例工程”的集合。项目里一长串重复的00-DeleteDCUs.bat看似冗余，其实对应不同子目录下的批处理入口，比如00-CreateLazarusResources.bat是为了在Lazarus环境下准备CEF的.res资源文件。如果只用Delphi，这几个bat基本碰不着，但一定要知道它们的存在——很多从GitHub直接拉源码的开发者会误以为缺了bat就无法编译，其实真正决定成败的是后续的全局初始化参数。
2.1 解压后那些00开头的bat是干什么的
这些bat属于项目整理步骤：00-CreateLazarusResources.bat用于为Lazarus IDE生成CEF4Delphi需要的资源描述文件；00-DeleteDCUs.bat则是递归清除各子项目残留的.dcu编译缓存。为什么这么在意删除DCU？CEF4Delphi跨多个Delphi版本，不同版本的RTL/VCL单元对接口布局有细微差异，旧DCU残留轻则链接混乱，重则弹出“单元版本不匹配”的提示。我一般把zip解压到D:\libs\CEF4Delphi-master这种无空格目录，先跑一遍删除脚本，再用Delphi打开Packages目录下的组件包安装——注意装组件包时要确认CEF4Delphi的源码搜索路径是绝对的还是相对的。
安装组件后，拖放面板上会出现TChromium和TCEFWindowParent。TChromium是逻辑控制器，管理浏览器实例、事件、JS绑定；TCEFWindowParent是继承自TWinControl的承载窗口，必须在表单上可见才能显示渲染画面。不推荐只拖TChromium，它没有窗口句柄。
2.2 全局CEF参数的启动顺序
CEF4Delphi要求在Application.Initialize之前完成GlobalCEFApp的参数设置，因为CEF的老大哥Chromium进程需要尽早拉起。下面这段是dpr文件的典型写法：
program CEFDemo; uses Vcl.Forms, uCEFApplication, uCEFConstants, MainForm in 'MainForm.pas' {Form1}; {$R *.res} begin // 必须放在VCL初始化之前，否则CEF内部消息循环会和其他初始化动作竞争 GlobalCEFApp.BrowserSubprocessPath := 'cef\Release\CefSharp.BrowserSubprocess.exe'; GlobalCEFApp.ResourcesDirPath := 'cef\Release\Resources'; GlobalCEFApp.LocalesDirPath := 'cef\Release\Resources\locales'; GlobalCEFApp.CacheDirPath := 'cef\Cache'; GlobalCEFApp.WorkerProcessCount := 2; GlobalCEFApp.EnableGPU := False; GlobalCEFApp.StartMainProcess; Application.Initialize; Application.MainFormOnTaskbar := True; Application.CreateForm(TForm1, Form1); Application.Run; GlobalCEFApp.ShutdownMainProcess; end.BrowserSubprocessPath指向渲染/GPU子进程的可执行文件；若留空，CEF4Delphi会自动从libcef.dll同目录查找。ResourcesDirPath放置cef.pak、icudtl.dat等Chromium资源，路径错误时窗口会一片白。EnableGPU设为False是应对老显卡驱动崩溃的保守做法，代价是CSS动画的流畅度稍有下降。WorkerProcessCount限定子进程数量为2，避免低配机器上出现几十个CEF进程。
设置这些参数时我习惯用相对路径而不是硬编码C:\，因为目标客户机器上软件可能装在任意带空格或中文的目录——而路径带空格时，有些CEF版本对LocalesDirPath的解析会失败，表现为右键菜单和工具提示全部变成英文。
2.3 最小浏览器Form代码与TChromium组件
表单上放一个TCEFWindowParent（设为alClient）和一个TChromium（不可见）。在FormShow里创建浏览器：
procedure TForm1.FormShow(Sender: TObject); begin // 必须先让窗口获得实际尺寸，否则初始viewport为0x0 CEFWindowParent1.UpdateSize; // CreateBrowser的第二个参数是要加载的起始URL Chromium1.CreateBrowser(CEFWindowParent1, 'https://example.com'); Timer1.Enabled := True; // 用于轮询创建状态 end;procedure TForm1.Timer1Timer(Sender: TObject); begin if Chromium1.Initialized then begin Timer1.Enabled := False; Caption := '浏览器已就绪，PID=' + IntToStr(Chromium1.Browser.Identifier); end; end;CreateBrowser是异步的，调用后Chromium1.Browser可能为空，所以用定时器轮询Initialized。不要在FormCreate里直接调用CreateBrowser，此时窗体句柄还没稳定，渲染窗口收不到WM_SIZE，会出现黑块。TCEFWindowParent继承自VCL标准控件，所以调整大小、Dock等行为都和普通Panel一致，这也是它比直接用THandle承载CEF更便于融入界面的原因。
3. 导航与生命周期事件处理：页面状态如何影响业务逻辑
浏览器组件能加载只是一个起点，真正要接进业务的是“页面加载到哪一步了”“用户点了什么链接”“弹窗要不要拦”这些运行时事件。CEF4Delphi把CEF的回调整理成了TChromium的一大串事件属性，全部以On开头。用好这些事件，才能做到在页面跳转时同步UI、在鉴权失败时切回本地页面。
3.1 Navigate和LoadURL的选择
TChromium暴露了多个加载方法。常见的三个调用是：
// 方法一：直接赋值URL属性，等价于导航 Chromium1.LoadURL('https://localhost:8443/app'); // 方法二：从某个Frame发起导航（用于框架页内部跳转） // Chromium1.Browser.MainFrame.LoadURL('/api/bootstrap'); // 方法三：刷新当前页 Chromium1.Browser.Reload;LoadURL与Browser.MainFrame.LoadURL的区别在于作用范围：前者加载到主frame；后者可以指定frame名，适合页面里有iframe且需要只刷新子框架的场景。日常最常用的还是LoadURL。注意LoadURL不会等待原页面卸载完成，连续调用两次会出现一次白屏闪烁，因为CEF内部会为每个导航产生独立CefLoadRequest。
3.2 关键生命周期事件与参数表
下面这张表列出了项目里几乎必挂的事件，以及每个事件适合做什么：
| 事件名 | 触发时机 | 常见用途 |
|---|---|---|
OnBeforePopup | 页面向window.open或target=_blank时 | 拦截新窗口，改为当前组件内导航 |
OnBeforeBrowse | 浏览器准备导航时（服务端重定向前） | 拦截外部协议，如mailto:、自定义myapp:// |
OnLoadStart | 新页面开始加载时 | 显示等待遮罩、记录加载耗时 |
OnLoadEnd | 页面主frame加载完成时 | 注入JS、更新状态栏 |
OnLoadingStateChange | 加载状态变化时（是否在加载） | 同步按钮的“停止/刷新”状态 |
OnRenderProcessTerminated | 渲染进程崩溃或被kill时 | 提示用户并重载页面 |
一个典型业务场景：内嵌后台系统需要检测登录Cookie是否过期，通常在OnLoadEnd里执行一段JS读取document.cookie，再调用Delphi回传状态。但OnLoadEnd对页面内异步接口并不保证数据都到位，所以严格判断登录态还是得依靠OnBeforeBrowse拦截HTTP状态码或JS侧的MutationObserver。
3.3 弹窗拦截与多标签页处理
CEF默认遇到target=_blank会新建一个独立窗口，这对单窗口应用来说很突兀。我习惯在OnBeforePopup里把链接强行导航到当前组件：
procedure TForm1.Chromium1BeforePopup(Sender: TObject; const browser: ICefBrowser; const frame: ICefFrame; const targetUrl, targetFrameName: string; const targetDisposition: TCefWindowOpenDisposition; userGesture: Boolean; const popupFeatures: TCefPopupFeatures; var windowInfo: TCefWindowInfo; var client: ICefClient; var settings: TCefBrowserSettings; var noJavascriptAccess: Boolean; var Result: Boolean); begin // 无论新标签还是新窗口，都被当成当前页面的导航 if targetUrl <> '' then begin Chromium1.LoadURL(targetUrl); // 阻止CEF创建新浏览器窗口 Result := True; end; end;targetDisposition可以区分是WOD_NEW_FOREGROUND_TAB还是WOD_NEW_WINDOW，如果需要把某些外链丢给系统默认浏览器，可以在这里判断域名白名单，然后调用ShellExecute(0,'open',PChar(targetUrl),nil,nil,SW_SHOWNORMAL)。关键点：只要把Result设为True，新窗口就不会创建，但导航动作不会自动发生，必须手动调用LoadURL。很多新手只设Result := True，结果点击链接后页面没有任何反应。
4. JavaScript与Delphi双向通信的完整实现
嵌入浏览器的核心价值在于复用Web端UI，同时又不放弃Delphi的业务能力。双向通信意味着Delphi对象能被JS直接“调用”，JS函数也能被Delphi主动触发。CEF4Delphi把这件事封装成了两个方向：注册绑定对象、执行JavaScript。
4.1 注册Delphi对象到JS上下文
CEF4Delphi提供了一个简化基类TCefSimpleJSObject，继承它就能把自己的方法暴露给JS。以下代码注册一个bridge对象，JS端可以调用bridge.showMessage('hello')：
type TDelphiBridge = class(TCefSimpleJSObject) protected procedure showMessage(const event: ICefEvent; const arguments: TCefValueArray); override; end; procedure TDelphiBridge.showMessage(const event: ICefEvent; const arguments: TCefValueArray); begin if Length(arguments) > 0 then ShowMessage('JS调用了Delphi: ' + arguments[0].GetStringValue); end;在Form的OnLoadEnd事件（确保JS上下文已存在）里注册：
procedure TForm1.Chromium1LoadEnd(Sender: TObject; const browser: ICefBrowser; const frame: ICefFrame; httpStatusCode: Integer); begin // 只向主frame注册，避免iframe里重复绑定导致变量被覆盖 if frame.IsMain then Chromium1.RegisterJavaScriptObject('bridge', TDelphiBridge.Create); end;TDelphiBridge.Create不需要手动释放，CEF的v8引擎会持有引用。JS侧用法就像调用本地函数：
bridge.showMessage('表格行双击事件');注意方法名大小写要保持一致，CEF4Delphi默认绑定函数时严格区分大小写。arguments是TCefValueArray，取字符串用GetStringValue，取整数用GetIntValue，取布尔用GetBoolValue。一旦类型不匹配，CEF不会抛异常，而是静默转换或返回0，这常常让调试陷入迷雾。我一般会在showMessage里先打印arguments[0].Type帮助排查。
4.2 从Delphi调用JavaScript函数
反向调用不需要注册任何对象，直接用ExecuteJavaScript。比如点击Delphi按钮，把当前编辑框内容同步到页面的一个输入框：
procedure TForm1.Button1Click(Sender: TObject); var js: string; begin js := Format('document.getElementById("title").value = %s;', [QuotedStr(Edit1.Text)]); Chromium1.Browser.MainFrame.ExecuteJavaScript(js, '', 0); end;ExecuteJavaScript的三个参数依次是JS代码、来源URL（不影响执行，一般传空串）、行号（用于调试时定位脚本错误）。还可以在页面加载完成后调用页内的全局函数：
procedure TForm1.Button2Click(Sender: TObject); begin Chromium1.Browser.MainFrame.ExecuteJavaScript( 'if (window.exportData) exportData("fromDelphi");', 'local', 1); end;调用时机特别重要。如果页面正在跳转，旧的MainFrame可能已经失效，这时执行JS会抛出“无框架上下文”的错误。稳妥做法是先用Chromium1.IsLoading判断，或者在OnLoadEnd里做延迟调用。
4.3 参数类型和返回值边界
下表列出JS值和Pascal类型的大致对应关系，避免你取出空对象时一头雾水：
| JS类型 | TCefValue.Get方法 | 注意事项 |
|---|---|---|
| string | GetStringValue | UTF-8，中文不需要额外转码 |
| number | GetIntValue或GetDoubleValue | 超过2^31的数字要用GetDoubleValue |
| boolean | GetBoolValue | JS的1和0不自动转布尔 |
| object/array | 无直接方法 | 需要再套一层FindValue或转换成JSON字符串 |
| null/undefined | GetType判断 | 访问成员前务必判空 |
当需要传复杂结构（比如一个订单对象）时，我建议不要在v8层面逐字段读取，而是在JS侧JSON.stringify(obj)后传字符串，Delphi端用SuperObject或同等级的JSON库解析。CEF4Delphi的v8对象模型设计得比较底层，直接在Delphi里遍历JS Object容易踩到生命周期管理上的坑——项对象可能在一次跨进程调用后被意外释放。
5. 容易被忽略的进程模型与资源释放陷阱
到前面为止，浏览器能跑、能跳转、能和JS说话了，看起来一切正常。但如果现在就打正式包，大概率会遇到“关闭窗口后Delphi进程不结束”或“程序第二次启动时崩溃”的问题。这既不是CEF4Delphi的bug，也不是代码逻辑错误，而是没理解CEF的多进程模型和VCL窗体生命周期的耦合关系。
5.1 CEF的多进程模型对Delphi的影响
CEF不是一个纯DLL嵌入方案，它启动时会产生一个主进程（browser process）和多个子进程（renderer, GPU, utility）。在任务管理器里，你会看到你的exe被运行了7、8次，这是CEF的正常行为。子进程由libcef.dll拉起，而它们的终止信号来自GlobalCEFApp.ShutdownMainProcess。如果代码在Application.Run结束后直接走默认退出逻辑，而没有调用ShutdownMainProcess，子进程就成了“孤儿”，主进程的退出标志位也清不掉，表现为任务管理器里残留若干同名exe。
5.2 正确关闭CEFWindowParent的顺序
直接关窗体而不管浏览器实例，会导致浏览器窗口销毁时回调还没完成就释放了VCL句柄。下面是我在一套支付客户端里验证过的关闭顺序：
procedure TForm1.FormCloseQuery(Sender: TObject; var CanClose: Boolean); begin // 先告诉浏览器：用户要关闭了，停止后台JS Chromium1.CloseBrowser(True); // 每次关闭前都缓存一个字段，等待OnBeforeClose真正触发 FCanClose := False; CanClose := FCanClose; // 启动一个短超时保护，防止某些页面拒绝关闭 TimerForceClose.Enabled := True; end;procedure TForm1.Chromium1BeforeClose(Sender: TObject; const browser: ICefBrowser); begin // 到这里，浏览器内部的窗口句柄已经销毁，VCL组件可以安全释放 FCanClose := True; Close; end;procedure TForm1.TimerForceCloseTimer(Sender: TObject); begin // 3秒还没有触发BeforeClose，强制关闭并清理CEF TimerForceClose.Enabled := False; GlobalCEFApp.ShutdownMainProcess; Halt(0); end;Chromium1.CloseBrowser(True)表示强制关闭，但页面里的beforeunload事件如果弹窗确认，CEF会暂时挂起关闭流程。所以必须有一个超时兜底，否则用户点了一个“你确定要离开吗？”确认框未响应，窗口就假死在那里。
5.3 一个通用的退出流程模板
把上面两段拼起来，就是一个可以复制的退出模板：
- 在
FormCloseQuery里调用Chromium1.CloseBrowser(True),设置CanClose := False。 - 在
TChromium.OnBeforeClose中把标志位置为True并重新Close。 - 在
FormDestroy中只TCEFWindowParent.Free不操作Chromium1。 - 在dpr的
Application.Run之后无条件调用GlobalCEFApp.ShutdownMainProcess。
这个顺序之所以重要，是因为OnBeforeClose触发时CEF的C++对象还活着，但窗口已销毁；此时若在事件里直接释放TCEFWindowParent，会重复释放同一个句柄，导致访问冲突。正确的做法是让VCL的消息循环接管后续释放。如果遇到个别页面脚本无限循环导致beforeunload永不返回，超时强制Halt(0)虽然粗暴，但对于桌面应用来说，总比进程残留被用户骂“软件关不掉”要好。
另一个相关技巧：开发时把GlobalCEFApp.LogFile指向一个文件路径，LogSeverity设为LOGSEVERITY_VERBOSE，退出崩溃时能看到是哪一步卡住。CEF4Delphi的日志里会明确打印Browser process shutdown sequence的每一阶段，对照日志就能定位是渲染进程挂起还是GPU进程没退干净。这份zip里自带的Demo工程，关闭流程基本都遵循上述模板，直接抄它们的FormCloseQuery实现是最省事的。
本文还有配套的精品资源，点击获取
