简介面向需要在 Delphi 桌面程序中嵌入 Chromium 浏览器的开发者与项目团队这套 CEF4Delphi 控件包提供可直接编译使用的 Chrome 组件封装兼容 Delphi 7 等较老版本适用于内嵌网页、混合界面和前端交互等场景。压缩包共 1330 个文件约 229.27MB以 pas 源码、dpr 与 dproj 工程、dfm 表单、inc 头文件及 bat 辅助脚本为主同时收录 Lazarus、FMX 相关工程和示例资源并配有 Windows 32 位运行库、资源文件、图标与说明文档目录按源码、示例和构建文件分层便于检索。已有 2826 人学习下载。读者可获得完整组件源码、多个演示工程和配置样例用于理解 CEF 封装结构、对照不同 IDE 下的工程组织方式并据此搭建自己的浏览器嵌入界面也适合做兼容性验证、项目迁移与二次开发参考。对研究浏览器内核封装与工程结构复用的读者较有帮助。1. 存量Delphi项目的新前端困境CEF4Delphi能解决什么维护一套跑了十几年的Delphi7业务系统前端页面早就换成Vue那套东西了结果内嵌的TWebBrowser还在用IE内核页面白屏、ES6语法报错、CSS Grid不认客户电话一个接一个。这时候CEF4Delphi就派上用场了——它把Chromium内核封装成Delphi控件支持Delphi7到最新版拖一个TChromium到窗体上就能加载现代网页。这个项目适合两类人手里有存量Delphi项目、不想重写又必须兼容新前端的前端维护者以及想用Delphi做桌面壳、需要内嵌浏览器做UI的开发者。源码结构不算复杂但编译和部署有不少坑下面按「架构拆解→跑通Demo→核心API→避坑→二次开发」的顺序讲清楚。2. 运行机制拆解Chromium多进程模型在Delphi里怎么落地2.1 主进程与渲染进程的分工CEF3开始就是多进程架构这一点决定了你在Delphi里看到的每一个浏览器窗口背后其实有两套进程在跑。主进程也叫Browser进程它承载Delphi的VCL消息循环负责窗口管理、网络请求调度、与操作系统打交道渲染进程也叫Render进程负责HTML解析、JavaScript执行、页面绘制和合成。两者之间通过IPC通道通信Delphi代码永远只跟主进程打交道渲染进程崩了不会直接拖垮你的VCL窗体这是它比老式ActiveX控件稳的根本原因。理解这个模型对后面调试很关键。你在TChromium上调用LoadURL请求先进入主进程的网络层再转发给渲染进程页面里的JS调用console.log日志也是先回到主进程再由OnConsoleMessage事件抛给Delphi。很多新手会疑惑「为什么我在渲染进程里断点断不到Delphi代码」原因就在这里——两边根本不在一个进程里。多进程还带来一个直接后果CEF要求主进程在启动时完成全局初始化且整个应用生命周期内只能初始化一次。CEF4Delphi用TCefApplication这个全局对象来承载这件事通常在工程文件.dpr里创建在Application.Run之前调用StartMainProcess。这个顺序不能反反了就是启动闪退。注意CEF的初始化必须在VCL窗体创建之前完成否则会出现「控件已创建但CEF还没就绪」的时序问题。2.2 Delphi封装层的三块拼图CEF4Delphi的源码单元数量不少但按职责可以分成三块。第一块是应用层核心是uCEFApplication里的TCefApplication负责加载libcef.dll、初始化CEF、注册全局配置、管理子进程启动。第二块是控件层uCEFChromium里的TChromium是开发者接触最多的类它把ICefBrowser、ICefClient、各类Handler包装成Delphi事件和属性。第三块是接口与Handler层uCEFInterfaces定义了大量ICefXxx接口uCEFLifeSpanHandler、uCEFLoadHandler、uCEFRequestHandler这些单元则提供了Handler的基类让你按需继承。这种分层的好处是日常用控件层就够了需要深度定制时再往Handler层下沉。比如只想加载一个页面用TChromium的LoadURL即可如果要拦截某个请求、修改响应头就得继承TCEFResourceRequestHandler并挂到TChromium的RequestHandler属性上。初始化代码通常长这样program Project1; uses Forms, uCEFApplication, Unit1 in Unit1.pas {Form1}; {$R *.res} begin // 创建 CEF 应用对象全局唯一 GlobalCEFApp : TCefApplication.Create; // 关键必须在 Application.Run 之前启动主进程 if not GlobalCEFApp.StartMainProcess then begin MessageBox(0, CEF 初始化失败, 错误, MB_ICONERROR); Halt(1); end; Application.Initialize; Application.CreateForm(TForm1, Form1); Application.Run; // 退出时释放顺序不能颠倒 GlobalCEFApp.Free; end.这段代码的逻辑是先构造TCefApplication把libcef.dll和资源路径配好再调用StartMainProcess完成CEF全局初始化。StartMainProcess内部会判断当前进程是不是子进程——如果是渲染进程或GPU进程它会接管消息循环并直接退出不再往下走VCL那一套。所以你看到「Application.Run没有执行」不一定是bug可能是子进程的正常分支。参数方面TCefApplication的属性如Cache、Locale、LogFile需要在StartMainProcess之前设置。2.3 面向Delphi7的兼容处理Delphi7没有UnicodeString、没有泛型、没有TBytes也没有接口辅助类这些现代语言特性在CEF4Delphi里都用条件编译绕开了。最典型的是字符串处理CEF内部统一用UTF-8而Delphi7的string是AnsiString直接传中文会乱码。CEF4Delphi在uCEFMiscFunctions里提供了StringToUTF8和UTF8ToString两个函数做转换所有跟CEF交互的字符串都必须走这一层。另一个坑是Delphi7的接口不支持方法重载Handler基类里那些带默认参数的虚方法得按原样声明。还有TBytes在Delphi7里叫TByteArray处理二进制响应时要注意类型别名。uses uCEFMiscFunctions; procedure TForm1.LoadLocalPage(const AFilePath: string); var CefUrl: ustring; begin // Delphi7 下 AFilePath 是 AnsiString先转 UTF-8 再交给 CEF CefUrl : StringToUTF8(file:/// AFilePath); Chromium1.LoadURL(CefUrl); end;这段代码的重点在StringToUTF8它把本地Ansi字符串按当前代码页转成UTF-8编码的ustringChromium1.LoadURL只认ustring。如果跳过这一步直接传stringDelphi7会做隐式转换中文路径大概率变成问号。参数AFilePath建议用绝对路径CEF对相对路径的解析基准是主进程的工作目录经常和你的预期不一致。3. 跑通第一个Demo环境准备、编译配置与最小窗口3.1 源码包目录与文件清单拿到源码包后先别急着打开工程花两分钟看清楚目录结构能省掉后面一半的编译错误。典型的CEF4Delphi包会包含source、demos、bin、packages这几个顶层目录各自职责如下目录内容是否必须sourceuCEFApplication.pas、uCEFChromium.pas等核心单元是demos官方示例工程按功能分类参考用binlibcef.dll、icudtl.dat、snapshot_blob.bin、locales目录是packages设计期包.dpk装到IDE里才有组件面板可选source目录要加入Delphi的Library Path否则uses uCEFChromium会直接报找不到单元。bin目录里的文件必须跟最终exe放在同一层CEF运行时按相对路径找资源路径错了就是白屏或者启动即崩。提示demos目录里通常有一个 MinimalBrowser 工程是验证环境是否配好的最佳起点先跑它再改自己的代码。3.2 依赖库与编译参数编译前有几个参数必须确认。第一是目标平台位数32位程序配32位的libcef.dll64位配64位混用是最常见的启动崩溃原因。第二是运行时库选项如果libcef.dll是动态链接VC运行库的版本客户机就得装对应的VC Redistributable想省事可以在编译时把运行库静态链接进去但exe体积会涨。第三是输出路径。CEF4Delphi的示例工程通常把bin目录下的文件作为Post-Build事件复制到输出目录你自己的工程也要配一份否则每次Clean之后都得手动拷。复制清单至少包括libcef.dll、icudtl.dat、snapshot_blob.bin、v8_context_snapshot.bin和locales整个目录。第四是子进程模式。CEF默认把渲染进程作为主exe的子进程启动主exe需要能被自己以命令行参数再次调用。如果你的工程改过exe名字或者加了启动参数校验子进程可能起不来表现为主窗口一直白屏。// 在 TCefApplication 创建后、StartMainProcess 之前配置 GlobalCEFApp.Cache : cache; // 缓存目录相对 exe 路径 GlobalCEFApp.Locale : zh-CN; // 界面语言 GlobalCEFApp.LogFile : debug.log; // 调试日志排查启动问题必开 GlobalCEFApp.LogSeverity : LOGSEVERITY_INFO; // 日志级别这几个属性的作用是Cache指定磁盘缓存位置不设会写到临时目录清理时容易丢登录态Locale影响右键菜单和内置页面的语言LogFile配合LogSeverity能在启动失败时留下线索比盲猜强得多。参数都必须在StartMainProcess之前赋值之后改不生效。3.3 最小可运行窗口的完整代码环境配好后一个能加载页面的最小窗体需要三个东西TCEFWindowParent作为容器、TChromium作为浏览器实例、OnAfterCreated事件里触发首次加载。TChromium本身不直接显示它把渲染结果贴到WindowParent上这个设计跟很多人的直觉相反第一次用容易漏掉容器导致「窗口一片灰」。unit Unit1; interface uses Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, uCEFChromium, uCEFWindowParent, uCEFInterfaces; type TForm1 class(TForm) procedure FormCreate(Sender: TObject); procedure FormDestroy(Sender: TObject); private FChromium: TChromium; FWindowParent: TCEFWindowParent; procedure ChromiumAfterCreated(Sender: TObject; const browser: ICefBrowser); end; implementation procedure TForm1.FormCreate(Sender: TObject); begin // 容器铺满窗体 FWindowParent : TCEFWindowParent.Create(Self); FWindowParent.Parent : Self; FWindowParent.Align : alClient; // 浏览器实例绑定容器 FChromium : TChromium.Create(Self); FChromium.WindowParent : FWindowParent; FChromium.OnAfterCreated : ChromiumAfterCreated; // 异步创建创建完成后触发 OnAfterCreated FChromium.CreateBrowser(FWindowParent); end; procedure TForm1.ChromiumAfterCreated(Sender: TObject; const browser: ICefBrowser); begin // 必须等浏览器创建完成后再加载提前调用会静默失败 FChromium.LoadURL(https://www.example.com); end; procedure TForm1.FormDestroy(Sender: TObject); begin // 先关浏览器再释放容器顺序反了会访问已释放对象 FChromium.CloseBrowser(True); end;逻辑上分三步创建容器并铺满、创建TChromium并绑定容器、调用CreateBrowser发起异步创建。OnAfterCreated是唯一可靠的加载时机CreateBrowser刚返回时浏览器对象还没准备好此时LoadURL会被丢弃且不报错。FormDestroy里的CloseBrowser(True)参数表示强制关闭传False会等待页面自己处理beforeunload在调试阶段容易卡住退出流程。4. 核心API实战页面加载、JS互调与请求拦截4.1 TChromium的初始化与生命周期TChromium的生命周期由一串事件串起来CreateBrowser触发创建OnAfterCreated表示浏览器就绪OnLoadStart和OnLoadEnd对应页面加载起止CloseBrowser触发关闭OnBeforeClose是最后清理时机。把资源释放、状态保存挂到OnBeforeClose上比挂在FormDestroy里安全因为后者执行时浏览器可能还在跑。procedure TForm1.ChromiumBeforeClose(Sender: TObject; const browser: ICefBrowser); begin // 浏览器即将销毁此时做状态落盘最稳妥 SaveLastUrl(UTF8ToString(browser.MainFrame.Url)); FChromium : nil; end;参数browser是当前浏览器接口通过MainFrame.Url能拿到最终地址可能经过重定向。这个方法里不要再调用LoadURL之类的操作浏览器已经在销毁流程中调用会被忽略。把FChromium置nil是为了防止后续事件回调访问已释放对象属于防御性写法。4.2 JavaScript与Delphi双向通信两个方向要分开看。Delphi调JS用ExecuteJavaScript传脚本字符串、目标URL、起始行号即可返回值通过回调拿。JS调Delphi有两种常见做法一种是用alert/console触发Delphi的OnJsdialog或OnConsoleMessage事件适合轻量场景另一种是注册自定义scheme或者用cefQuery适合需要返回值的场景。procedure TForm1.btnRunJsClick(Sender: TObject); begin // 执行脚本并把结果通过回调带回来 FChromium.ExecuteJavaScript( document.title | window.location.href, about:blank, 0); end; procedure TForm1.ChromiumConsoleMessage(Sender: TObject; const browser: ICefBrowser; level: TCefLogSeverity; const message, source: ustring; line: Integer); begin // 页面 console.log 的内容会走到这里 Memo1.Lines.Add(UTF8ToString(message)); end;ExecuteJavaScript的第二个参数是脚本所属的URL填about:blank表示不绑定具体页面第三个参数是起始行号影响报错定位。这个调用是异步的结果不会立刻返回需要的结果建议在JS里通过console.log输出再在OnConsoleMessage里接。ConsoleMessage回调里的level对应日志级别message是UTF-8字符串展示前记得UTF8ToString。4.3 请求拦截与自定义资源处理请求拦截靠继承TCEFResourceRequestHandler重写OnBeforeResourceLoad返回RV_CANCEL可以阻断请求返回RV_CONTINUE放行。这个能力在离线包、接口mock、广告过滤场景里很实用。type TMyRequestHandler class(TCEFResourceRequestHandler) protected function OnBeforeResourceLoad(const browser: ICefBrowser; const frame: ICefFrame; const request: ICefRequest; const callback: ICefRequestCallback): TCefReturnValue; override; end; function TMyRequestHandler.OnBeforeResourceLoad(const browser: ICefBrowser; const frame: ICefFrame; const request: ICefRequest; const callback: ICefRequestCallback): TCefReturnValue; var Url: string; begin Url : UTF8ToString(request.Url); // 阻断统计脚本放行其他请求 if Pos(analytics.js, Url) 0 then Result : RV_CANCEL else Result : RV_CONTINUE; end;OnBeforeResourceLoad在每个资源加载前触发request.Url是完整地址frame标识发起请求的框架。返回RV_CANCEL会直接给页面一个失败响应页面侧的onerror会触发返回RV_CONTINUE则正常走网络。注意这个方法在IO线程上执行里面不要直接操作VCL控件需要更新界面时用TThread.Queue切回主线程。挂载方式是把Handler实例赋给TChromium的RequestHandler属性在CreateBrowser之前设置。5. 避坑与排查编译、白屏、部署阶段的典型翻车现场5.1 编译与启动阶段现象编译时报「找不到uCEFApplication.pas」。原因source目录没有加入Library Path或者装了设计期包但包引用的路径跟实际源码位置不一致。解决在IDE的Tools-Options-Library里把source绝对路径加进去同时检查packages目录下.dpk的引用路径两处都对齐后重新Build。现象双击exe瞬间闪退没有任何窗口。原因libcef.dll位数跟编译目标不一致或者icudtl.dat、snapshot_blob.bin缺失。解决先看exe同目录下这几个文件是否齐全再用GlobalCEFApp.LogFile打开日志日志里会明确写「failed to load libcef」还是「missing resource」。32位工程配64位DLL是最常见的组合错误。5.2 运行期白屏与资源加载现象窗体出来了浏览器区域一直白屏日志里没有任何报错。原因CreateBrowser之后立刻调了LoadURL此时OnAfterCreated还没触发。解决把加载逻辑移到OnAfterCreated里或者用状态标志位判断浏览器是否就绪。另一个可能是WindowParent没有正确设置Parent和Align渲染结果贴到了一个不可见的容器上。现象部分页面能开部分页面白屏且控制台报跨域或协议错误。原因自定义scheme没有注册为standardCEF把它当成非标准协议处理CORS和部分API不可用。解决在GlobalCEFApp里用CefRegisterSchemeHandlerFactory注册scheme时把is_standard设为True同时注意standard scheme名不能跟内置的http、https冲突。5.3 部署与版本匹配现象开发机一切正常拷到客户机启动就崩。原因客户机缺少VC运行库或者杀软拦截了子进程创建。解决部署包带上对应版本的VC_redist并且在客户机上确认主exe能被自己以--typerenderer参数二次启动被杀软拦的话需要加白名单。现象升级CEF4Delphi源码后原来能编译的工程报一堆接口方法签名不匹配。原因源码版本和libcef.dll版本、CEF API版本三者必须成套。解决source、bin、dll整组替换不要只换其中一个升级前先看源码里的版本说明确认API变更点再逐个改Handler的重写方法。6. 二次开发把控件改造成业务壳的几条改造路径拿到能跑的Demo之后真正的工作才刚开始。我一般按改造难度从低到高走三条路。第一条是继承TChromium做业务封装把地址栏、前进后退、下载管理、快捷键这些通用能力收进一个TBusinessBrowser类业务窗体直接用它避免每个窗体重复写事件绑定。第二条是注入JS桥在OnAfterCreated之后ExecuteJavaScript一段初始化脚本把window.business对象挂上去页面里调window.business.saveData(payload)Delphi侧用自定义scheme或console通道接住这条路的坑在于序列化复杂对象建议统一走JSON字符串。第三条是自定义协议做离线包把app://映射到本地资源目录配合请求拦截做版本切换适合内网部署场景。改造方向改动量适用场景主要风险继承TChromium封装小多窗体复用浏览器能力事件绑定遗漏JS桥注入中页面与Delphi深度交互序列化与线程切换自定义协议离线包大内网、无网部署scheme注册与缓存策略有一个细节值得单独说多标签页场景下不要共用一个TChromium实例每个标签页配一个独立的TChromium和TCEFWindowParent用PageControl切换Visible。共用实例在切换标签时会出现焦点丢失和JS上下文串扰这个问题我在两个项目里都遇到过最后都是改成多实例才消停。从那以后我每次改CEF相关代码都强制先在MinimalBrowser上跑一遍最小复现确认是环境问题还是业务代码问题再动正式工程。这套习惯帮我省掉了大量「改了半小时发现是DLL没拷对」的时间。希望帮到你。本文还有配套的精品资源点击获取