简介：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 调 JS：ExecuteJavaScript 的正确用法
反过来，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 这边的代码。希望帮到你。
本文还有配套的精品资源，点击获取
