简介这份示例工程面向需要在 C# WinForm 中内嵌 Chromium 浏览器的开发者基于 VS2010 与 .NET Framework 4.0完整演示 CefSharp.WinForms 49.0.1 的集成方式。工程覆盖 Cef 初始化、ChromiumWebBrowser 控件加载、导航与加载状态事件、JavaScript 执行及 CefSettings 参数配置并在退出时调用 Cef.Shutdown 释放资源可作为桌面端混合 Web 界面的起步模板。压缩包共 319 个文件约 189.28MB包含 52 个 dll、174 个 pak 等浏览器运行时依赖以及 7 个 cs 源文件、2 个 csproj 与 sln 工程文件、若干 xml/config 配置和 exe 程序便于直接打开对照或离线还原运行环境。已有 3433 人学习下载适合初中级 .NET 桌面开发者参考工程组织、依赖部署与常见初始化排错。1. 老 WinForm 要嵌现代前端这套 C# WinForm CefSharp 示例能省掉哪几步接手一个 VS2010 时代的 WinForm 工程客户要求界面里嵌一块能跑现代前端的区域换成 WebBrowser 控件打开页面直接脚本报错、样式错位——这套 C# WinForm CefSharp 示例代码就是在这种场景下攒出来的。它把 Chromium 内核包装成 WinForms 控件在 .NET 4.0 上把窗口、C# 与 JS 互调的桥接对象、初始化与退出清理这几段最容易出错的骨架先搭好你只需要改页面和业务方法。适合两类人手上压着 .NET 4.0 存量工程、又必须渲染现代页面的同学以及已经能把控件拖进窗体、却总是在“绑定对象拿不到”“关窗口闪退”上反复消耗时间的人。下面按编译、初始化、互调、排错、部署的顺序拆。2. 让例子在 VS2010 里编译通过版本天花板、目录铺法和 csproj 改法2.1 先认清版本天花板别一上来就装最新包.NET 4.0 这个约束比 VS2010 本身更致命。CefSharp 从 51 那一代开始把最低框架要求提到了 .NET 4.5.2也就是说 .NET 4.0 的工程能用的最后一批是 49 系列。很多人卡在第一步不是代码写错而是在 NuGet 里点了“最新版”还原完一堆 CS0246然后开始怀疑人生。第二个约束是编译器。VS2010 带的是 C# 4没有async/await关键字。示例代码里凡是用到异步 API 的地方都得用ContinueWith或者同步等待的方式改写这点在后面第 4 章讲互调时会反复用到。约束直接后果实际应对目标框架 .NET 4.0新版 CefSharp 的包引用不上锁定 49 系列包里带net40目录的那一版编译器 C# 4不能用async/await全部改用Task.ContinueWithVS2010 的 NuGet 客户端包的 build targets 展开异常不依赖 targets手动铺目录、手动加引用原生依赖 libcef位数不匹配就启动即崩平台目标固定 x86 或 x64二选一提示判断一个包能不能用看解压后有没有net40或net40-client目录有就说明这一代还没放弃 .NET 4.0。2.2 手动铺目录绕开 MSBuild 4.0 的 build targets老版本 NuGet 客户端在 VS2010 下还原 CefSharp 时经常出现包已经下载、.csproj里的Import却指向一个不存在的 props 文件编译一开就报“找不到导入的项目”。我的做法是干脆不用包管理器把需要的 DLL 和原生文件按固定目录铺好然后在工程里手工加引用。这样换机器、换同事接手都不依赖 NuGet 缓存。# 在解决方案根目录建一个 libs 目录把包里的文件分两类放 # 1) 托管程序集给编译器看 libs/CefSharp/managed/ CefSharp.dll CefSharp.Core.dll CefSharp.WinForms.dll # 2) 原生资源运行时才用必须出现在输出目录 libs/CefSharp/native/x86/ libcef.dll icudtl.dat natives_blob.bin snapshot_blob.bin cef.pak cef_100_percent.pak cef_extensions.pak d3dcompiler_47.dll libEGL.dll libGLESv2.dll locales/zh-CN.pak swiftshader/ CefSharp.BrowserSubprocess.exe CefSharp.BrowserSubprocess.Core.dll目录分两层的理由是托管程序集只需要被引用原生文件必须在生成后被复制到bin\Debug而且CefSharp.BrowserSubprocess.exe要放在位数字目录里CefSharp 会按平台目标去x86\或x64\下找它。混在一起放第一次跑必然报子进程启动失败。改.csproj的时候直接编辑 XML 比在对话框里点更省事注意PlatformTarget和Prefer32Bit这两个属性PropertyGroup Condition $(Configuration)|$(Platform) Debug|AnyCPU !-- 平台目标必须落到具体的位数AnyCPU 会让 CEF 找不到原生库 -- PlatformTargetx86/PlatformTarget Prefer32Bitfalse/Prefer32Bit OutputPathbin\Debug\/OutputPath /PropertyGroup ItemGroup !-- 三个托管程序集全部用相对路径引用换机器不用改 -- Reference IncludeCefSharp HintPath..\libs\CefSharp\managed\CefSharp.dll/HintPath PrivateTrue/Private /Reference Reference IncludeCefSharp.Core HintPath..\libs\CefSharp\managed\CefSharp.Core.dll/HintPath PrivateTrue/Private /Reference Reference IncludeCefSharp.WinForms HintPath..\libs\CefSharp\managed\CefSharp.WinForms.dll/HintPath PrivateTrue/Private /Reference /ItemGroup Target NameCopyCefNative AfterTargetsBuild !-- 原生文件用通配复制避免以后补文件忘了改工程 -- ItemGroup CefNative Include..\libs\CefSharp\native\$(PlatformTarget)\**\*.* / /ItemGroup Copy SourceFiles(CefNative) DestinationFiles(CefNative-$(OutputPath)%(RecursiveDir)%(Filename)%(Extension)) / /TargetPrivateTrue决定程序集是否复制到输出目录漏了就会在运行时报“无法加载文件或程序集 CefSharp.Core”。CopyCefNative里的$(PlatformTarget)让复制路径跟着平台目标走把平台从 x86 改成 x64 时不用再动手改复制路径。RecursiveDir保留locales\、swiftshader\这类子目录层级少了它所有 pak 文件会被拍平到根目录CEF 就找不到本地化资源。2.3 最小可运行窗体两处注册、一个 Dock把窗体做成“地址栏 浏览器”两行结构是验证环境最省事的形态出问题一眼能看出是加载失败还是渲染失败。示例里的主窗体只做三件事创建ChromiumWebBrowser、在加载任何页面之前注册桥接对象、挂上错误事件。public partial class MainForm : Form { private ChromiumWebBrowser _browser; public MainForm() { InitializeComponent(); _browser new ChromiumWebBrowser(about:blank); _browser.Dock DockStyle.Fill; // 关键绑定对象必须在页面脚本执行之前注册否则 JS 侧拿不到 window.bound _browser.RegisterJsObject(bound, new JsBridge(this)); // 加载失败和页面 console 输出都挂上排查时不用猜 _browser.LoadError OnLoadError; _browser.ConsoleMessage OnConsoleMessage; Controls.Add(_browser); _browser.Load(file:///C:/app/ui/index.html); } private void OnLoadError(object sender, LoadErrorEventArgs e) { System.Diagnostics.Debug.WriteLine( string.Format(load error url{0} code{1} text{2}, e.FailedUrl, e.ErrorCode, e.ErrorText)); } }DockFill的前提是这个控件最后加入Controls集合先加工具栏再加浏览器否则浏览器会把工具栏盖住。RegisterJsObject的第二个参数是一个普通 C# 对象CefSharp 会用反射把它暴露到页面的window.bound上第三个参数在示例里保持默认即把 C# 的 PascalCase 方法名映射成 JS 的 camelCase这条映射规则后面会单独提一次因为它是“方法明明写了却调不到”的头号原因。3. 初始化的三件事CefSettings 参数、调用时机和退出顺序3.1 CefSettings 里真正需要改的就那几项CefSettings有几十个属性实际项目里九成的人只会动其中五六个。剩下的保持默认改多了反而容易互相打架。示例代码把这几项提出来集中配置理由写在注释里。var settings new CefSettings { // 界面语言影响右键菜单和内置对话框不设会出现英文菜单 Locale zh-CN, // 缓存目录必须是可写路径放在 Program Files 下会静默失败 CachePath Path.Combine(Application.StartupPath, cef_cache), // 日志是唯一的黑匣子出问题第一件事就是看它 LogSeverity LogSeverity.Warning, LogFile Path.Combine(Application.StartupPath, cef.log), // 子进程默认在输出目录找自己挪过位置就必须显式指定 BrowserSubprocessPath Path.Combine( Application.StartupPath, x86, CefSharp.BrowserSubprocess.exe) }; // 远程桌面、老显卡、虚拟机里关掉 GPU 能省掉一半白屏投诉 settings.CefCommandLineArgs.Add(disable-gpu, 1); settings.CefCommandLineArgs.Add(disable-gpu-compositing, 1); // 页面里用到 getUserMedia 之类的接口时再打开默认关 settings.CefCommandLineArgs.Add(enable-media-stream, 1);CefCommandLineArgs是透传给 Chromium 的命令行开关disable-gpu加1是赋值形式不能只写 key。CachePath指向Application.StartupPath在绿色部署时很方便但如果程序装在受保护目录下这个路径不可写CEF 不会报错只是每次启动都当首次加载表现为“登录状态老是丢”这条坑我在现场遇到过两次才反应过来。3.2 初始化放 Program.cs只能调一次且必须在窗体之前Cef.Initialize的正确位置是Main里、Application.Run之前。放在窗体构造函数里也会跑但一旦有第二个窗体或者第二个浏览器实例就容易重复初始化直接抛异常。示例代码用一个静态标记加Cef.IsInitialized判重。[STAThread] static void Main() { // 同一进程内重复 Initialize 会抛异常多窗体场景下这句判重很关键 if (!Cef.IsInitialized) { var settings BuildCefSettings(); // 见 3.1 if (!Cef.Initialize(settings)) { // 初始化失败九成是原生依赖或位数问题日志里写得很清楚 MessageBox.Show(CEF 初始化失败请查看 cef.log); return; } } Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Application.Run(new MainForm()); }Cef.Initialize的签名在不同版本之间变过早期版本没有返回值也没办法在返回值里判断成败只能看日志文件49 这一代是有bool返回值的。这意味着从别处抄来的代码片段未必能直接编译遇到“参数数量不匹配”先查签名再说别急着怀疑 DLL 引错。还有一个细节值得说明STAThread特性不能丢。WinForms 的消息泵要求 STA 线程而 CEF 在初始化时会检查当前线程的单元状态缺了它可能出现拖拽、剪贴板、文件选择对话框集体失灵这种很玄学的现象。3.3 退出顺序Dispose 在前Shutdown 在后CefSharp 最典型的“翻车”现场不在启动而在关闭用户点叉窗口消失进程还挂在任务管理器里或者干脆弹一个AccessViolationException。原因几乎都是清理顺序不对——浏览器对象还没释放就先把 CEF 的全局运行时关掉了。protected override void OnFormClosing(FormClosingEventArgs e) { // 顺序不能换先停导航、再释放控件、最后关 CEF if (_browser ! null) { try { _browser.Stop(); _browser.Dispose(); } catch (Exception ex) { System.Diagnostics.Debug.WriteLine(browser dispose: ex.Message); } _browser null; } base.OnFormClosing(e); } // Program.cs 里补一刀兜住所有退出路径 Application.ApplicationExit (s, e) { if (Cef.IsInitialized) { Cef.Shutdown(); // 必须在所有 ChromiumWebBrowser 释放之后调用 } };Stop()的作用是打断正在进行的导航某些版本的Dispose在页面加载中会阻塞几百毫秒加上Stop()能把这段时间压下去。Cef.Shutdown()之后再访问任何浏览器实例都是未定义行为所以示例里紧跟着把字段置空避免别处的定时器还拿着引用。注意如果进程里还有后台线程在调EvaluateScriptAsyncShutdown也会卡住。清理前先把自己的定时器和后台任务停掉。4. C# 与 JS 互调绑定对象、线程切换和没有 async 的写法4.1 同步绑定与异步绑定先搞清楚什么时候用哪个CefSharp 提供两套暴露对象的方式。RegisterJsObject是同步的JS 调用后能直接拿到返回值代价是这会阻塞渲染进程的 JS 线程方法里做超过几十毫秒的事情页面就会卡顿。RegisterAsyncJsObject不阻塞但 JS 侧必须传一个回调函数当最后一个参数写法比同步版啰嗦。判断标准很简单取个配置项、返回个当前用户名用同步读文件、查数据库、调接口用异步。// 同步桥接JS 侧 bound.echo(x) 直接拿到返回值 public class JsBridge { private readonly MainForm _form; public JsBridge(MainForm form) { _form form; } // C# 里叫 EchoJS 里必须写 bound.echo默认 camelCase 映射 public string Echo(string text) { return csharp: text; } // 返回复杂对象时 CefSharp 会做 JSON 序列化别塞循环引用 public object GetUserInfo() { return new { name operator, role admin }; } } // 异步桥接JS 侧 bound2.readFile(cfg.json, function (text) { ... }) public class AsyncBridge { public void ReadFile(string path, IJavascriptCallback callback) { Task.Factory.StartNew(() { string text File.Exists(path) ? File.ReadAllText(path) : string.Empty; if (callback.CanExecute) { // 回调执行失败不要吞异常至少写日志 callback.ExecuteAsync(text) .ContinueWith(t System.Diagnostics.Debug.WriteLine(t.Exception), TaskContinuationOptions.OnlyOnFaulted); } }); } }IJavascriptCallback是 CefSharp 注入的位置固定在参数列表最后少写一个参数就会在 JS 侧报“回调不是函数”。CanExecute的判断不能省——页面已经导航走的时候回调对象会失效此时执行会抛异常。4.2 回调线程为什么在绑定方法里改控件必炸这是我最想提前说清楚的一条。绑定方法被调用时执行线程不是 WinForms 的 UI 线程而是 CEF 侧的线程。在里面直接label.Text ...轻则抛跨线程访问异常重则界面卡住不动——因为渲染线程正同步等着你的返回值你却在等 UI 线程两边互相等待死锁。public class JsBridge { private readonly MainForm _form; public JsBridge(MainForm form) { _form form; } // 从 JS 侧通知界面刷新标题 public void NotifyTitle(string title) { // InvokeRequired 在非 UI 线程上才为 true判断后再切回去 if (_form.InvokeRequired) { // 用 BeginInvoke 而不是 Invoke同步版桥接方法里用 Invoke 会死锁 _form.BeginInvoke(new Actionstring(_form.SetTitle), title); return; } _form.SetTitle(title); } }BeginInvoke是投递消息后立即返回Invoke是阻塞等待 UI 线程执行完。在同步绑定的方法里JS 线程正等着你 return你用Invoke等 UI 线程UI 线程如果这时恰好在等渲染结果就成了死锁。这条血泪经验没法从文档里读出来只能自己踩一次。4.3 C# 调 JS没有 async 关键字时怎么写VS2010 下不能写await但EvaluateScriptAsync返回的是TaskJavascriptResponse用ContinueWith接上完全一样只是嵌套深一点。private void ReadPageTitle() { // 表达式要包成 IIFE避免返回值被当成语句丢弃 _browser.EvaluateScriptAsync((function(){ return document.title; })()) .ContinueWith(t { if (t.IsFaulted || !t.Result.Success) { System.Diagnostics.Debug.WriteLine(eval failed: (t.IsFaulted ? t.Exception.Message : t.Result.Message)); return; } // 结果经过 JSON 反序列化字符串还是 string数字会变 double string title Convert.ToString(t.Result.Result); if (_browser ! null !_browser.IsDisposed) { BeginInvoke(new Action(() Text title)); } }); }JavascriptResponse有三个字段值得记住Success表示脚本有没有抛异常Result是反序列化后的返回值Message在失败时给出异常描述。Result的类型不是强类型的返回对象会变成字典或 JObject返回数字一律是double直接强转int会抛InvalidCastException用Convert.ToInt32更稳妥。另一条容易忽略的规则页面还在加载时调EvaluateScriptAsync脚本可能在旧文档上执行然后被导航冲掉结果就是你拿到一个空值。稳妥的做法是等FrameLoadEnd之后再发起首次调用。4.4 把调试信息引到自己的日志里嵌入浏览器的项目最怕“用户说白屏你这边一切正常”。示例里挂了两个事件把页面内部的信息引到自己的日志文件比让用户开 DevTools 现实得多。private void OnConsoleMessage(object sender, ConsoleMessageEventArgs e) { // 页面里的 console.log 原样过来前端排查不用远程连 Logger.Write(string.Format([js] {0} ({1}:{2}), e.Message, e.Source, e.Line)); } // 需要看网络请求时临时打开正式发布前关掉 _browser.ShowDevTools();ConsoleMessage事件如果一直不触发先检查是不是自定义了RequestHandler并覆盖掉OnConsoleMessage返回false会截断事件。ShowDevTools打开的窗口依赖CefSettings里没有禁用相关特性在精简过的包上可能弹不出来此时退回到日志方案。5. 避坑与排查五个把人卡半天的现场5.1 启动与加载类现象一双击 exe 直接退出事件查看器里连异常都没有。原因基本是原生库没到位——要么libcef.dll没复制到输出目录要么平台目标写的AnyCPU而x86\目录不存在。解决方式是先看输出目录里有没有libcef.dll和CefSharp.BrowserSubprocess.exe再把PlatformTarget改成明确的x86最后确认复制目标的目录名和$(PlatformTarget)的值一致。这三步能盖掉八成“程序一闪就没”的问题。现象二窗口出来了浏览器区域纯白FrameLoadEnd从不触发。先在LoadError里打日志如果ErrorCode是负数且FailedUrl是本地路径多半是路径写错或者文件编码不对如果是远程地址检查目标机器上有没有拦截出站访问的策略。还有一种情况是页面加载了但渲染没出来——远程桌面或者老显卡环境下把disable-gpu和disable-gpu-compositing都打开白屏概率立刻下降。这一条属于环境相关不是代码 bug但报障的人永远描述成“你的程序有问题”。现象三开发机正常客户机上启动就提示缺少 DLL。缺的是 VC 运行库——CEF 的原生层依赖对应版本的系统运行库。解决方式是把运行库安装包随发布包一起提供或者在部署说明里写清依赖。别指望“装个 .NET 4.0 就够了”托管框架和原生运行库是两码事。5.2 互调类现象四JS 报bound.myMethod is not a function。三个原因按概率排序方法名大小写不匹配C# 的MyMethod在 JS 里是myMethod、注册时机晚于页面脚本执行、绑定对象是同步注册但 JS 用了异步回调写法。排查时先在页面里执行typeof bound看对象在不在再执行Object.keys(bound)看暴露了哪些方法名两步就能定位。现象五关闭窗口时进程不退或者退出瞬间弹AccessViolationException。原因是清理顺序错或者还有后台线程持有浏览器引用。把Dispose、Shutdown、停定时器三步按顺序走一遍并且在Shutdown之后不再访问任何 CEF 对象。如果进程仍不退出用任务管理器看一下是不是CefSharp.BrowserSubprocess.exe残留那说明主进程的Shutdown没被调用到。现象六绑定方法里弹了个 MessageBox页面直接卡死。同步桥接方法在渲染线程上执行弹模态框会把这条线程占住JS 侧等不到返回值整个页面失去响应。解决方式是把交互挪到 UI 线程用BeginInvoke异步弹或者干脆改成异步桥接。这类问题在测试阶段很难发现因为开发时大家习惯点一下就走。6. 搬到客户机上部署清单与一条自检命令打包发给别人之前先照下表把输出目录过一遍。CefSharp 的坑集中在“文件缺一个就白屏”上清单比记忆可靠。文件或目录缺了会怎样备注CefSharp.dll、CefSharp.Core.dll、CefSharp.WinForms.dll启动报找不到程序集必须与 libcef 版本配套libcef.dll进程直接退出位数必须与平台目标一致CefSharp.BrowserSubprocess.exe浏览器区域空白放在x86\或x64\子目录下icudtl.dat中文乱码或启动失败大小几十 MB最容易被漏拷cef.pak、cef_100_percent.pak、cef_extensions.pak界面控件样式异常三个都要locales\zh-CN.pak右键菜单变英文目录层级不能拍平d3dcompiler_47.dll、libEGL.dll、libGLESv2.dll特定机器渲染失败显卡驱动环境差异大swiftshader\无 GPU 环境回退失败虚拟机里尤其重要清单过完之后还有一步是很多人省掉的给程序加一个启动自检。思路是拿一个必然成功的表达式去问浏览器能看到正确结果说明 CEF 起来了、页面上下文在了、脚本通道通了三件事一次性验完。private bool SelfCheck(int timeoutMs) { bool ok false; // 放到后台线程等别把 WinForms 的消息泵堵死 Task.Factory.StartNew(() { var task _browser.EvaluateScriptAsync( (function(){ return typeof bound ! undefined ? bound.echo(ping) : no-bridge; })()); if (!task.Wait(timeoutMs)) { Logger.Write(自检超时页面可能未加载完成); return; } if (!task.Result.Success) { Logger.Write(自检脚本异常 task.Result.Message); return; } ok csharp:ping.Equals(Convert.ToString(task.Result.Result)); }).Wait(timeoutMs 500); return ok; }这段代码的价值不在“检测功能是否正常”而在把三类故障区分开超时说明页面还没加载完或者渲染线程被占住脚本异常说明页面上下文有问题返回no-bridge说明绑定对象没注册上。日志里出现哪一句对应的排查方向立刻明确不用再靠“重启试试”这种玄学手段。参数上timeoutMs给 3000 到 5000 比较合适太短会在老机器上误报太长会让启动画面僵住。外层那个.Wait(timeoutMs 500)是后悔药防止内层Task因为某种原因没结束而让整个自检挂死。另外一个建议是把自检结果写进启动日志而不是弹窗。现场用户看到弹窗只会点确定日志才会被带回来。从那以后我每次交付带浏览器的客户端都会强制走一遍“清单核对 自检日志”这两个动作哪怕这次只改了一行页面代码——因为漏拷一个icudtl.dat导致的返工成本远高于花五分钟核对。希望帮到你。本文还有配套的精品资源点击获取
简介这份示例工程面向需要在 C# WinForm 中内嵌 Chromium 浏览器的开发者基于 VS2010 与 .NET Framework 4.0完整演示 CefSharp.WinForms 49.0.1 的集成方式。工程覆盖 Cef 初始化、ChromiumWebBrowser 控件加载、导航与加载状态事件、JavaScript 执行及 CefSettings 参数配置并在退出时调用 Cef.Shutdown 释放资源可作为桌面端混合 Web 界面的起步模板。压缩包共 319 个文件约 189.28MB包含 52 个 dll、174 个 pak 等浏览器运行时依赖以及 7 个 cs 源文件、2 个 csproj 与 sln 工程文件、若干 xml/config 配置和 exe 程序便于直接打开对照或离线还原运行环境。已有 3433 人学习下载适合初中级 .NET 桌面开发者参考工程组织、依赖部署与常见初始化排错。1. 老 WinForm 要嵌现代前端这套 C# WinForm CefSharp 示例能省掉哪几步接手一个 VS2010 时代的 WinForm 工程客户要求界面里嵌一块能跑现代前端的区域换成 WebBrowser 控件打开页面直接脚本报错、样式错位——这套 C# WinForm CefSharp 示例代码就是在这种场景下攒出来的。它把 Chromium 内核包装成 WinForms 控件在 .NET 4.0 上把窗口、C# 与 JS 互调的桥接对象、初始化与退出清理这几段最容易出错的骨架先搭好你只需要改页面和业务方法。适合两类人手上压着 .NET 4.0 存量工程、又必须渲染现代页面的同学以及已经能把控件拖进窗体、却总是在“绑定对象拿不到”“关窗口闪退”上反复消耗时间的人。下面按编译、初始化、互调、排错、部署的顺序拆。2. 让例子在 VS2010 里编译通过版本天花板、目录铺法和 csproj 改法2.1 先认清版本天花板别一上来就装最新包.NET 4.0 这个约束比 VS2010 本身更致命。CefSharp 从 51 那一代开始把最低框架要求提到了 .NET 4.5.2也就是说 .NET 4.0 的工程能用的最后一批是 49 系列。很多人卡在第一步不是代码写错而是在 NuGet 里点了“最新版”还原完一堆 CS0246然后开始怀疑人生。第二个约束是编译器。VS2010 带的是 C# 4没有async/await关键字。示例代码里凡是用到异步 API 的地方都得用ContinueWith或者同步等待的方式改写这点在后面第 4 章讲互调时会反复用到。约束直接后果实际应对目标框架 .NET 4.0新版 CefSharp 的包引用不上锁定 49 系列包里带net40目录的那一版编译器 C# 4不能用async/await全部改用Task.ContinueWithVS2010 的 NuGet 客户端包的 build targets 展开异常不依赖 targets手动铺目录、手动加引用原生依赖 libcef位数不匹配就启动即崩平台目标固定 x86 或 x64二选一提示判断一个包能不能用看解压后有没有net40或net40-client目录有就说明这一代还没放弃 .NET 4.0。2.2 手动铺目录绕开 MSBuild 4.0 的 build targets老版本 NuGet 客户端在 VS2010 下还原 CefSharp 时经常出现包已经下载、.csproj里的Import却指向一个不存在的 props 文件编译一开就报“找不到导入的项目”。我的做法是干脆不用包管理器把需要的 DLL 和原生文件按固定目录铺好然后在工程里手工加引用。这样换机器、换同事接手都不依赖 NuGet 缓存。# 在解决方案根目录建一个 libs 目录把包里的文件分两类放 # 1) 托管程序集给编译器看 libs/CefSharp/managed/ CefSharp.dll CefSharp.Core.dll CefSharp.WinForms.dll # 2) 原生资源运行时才用必须出现在输出目录 libs/CefSharp/native/x86/ libcef.dll icudtl.dat natives_blob.bin snapshot_blob.bin cef.pak cef_100_percent.pak cef_extensions.pak d3dcompiler_47.dll libEGL.dll libGLESv2.dll locales/zh-CN.pak swiftshader/ CefSharp.BrowserSubprocess.exe CefSharp.BrowserSubprocess.Core.dll目录分两层的理由是托管程序集只需要被引用原生文件必须在生成后被复制到bin\Debug而且CefSharp.BrowserSubprocess.exe要放在位数字目录里CefSharp 会按平台目标去x86\或x64\下找它。混在一起放第一次跑必然报子进程启动失败。改.csproj的时候直接编辑 XML 比在对话框里点更省事注意PlatformTarget和Prefer32Bit这两个属性PropertyGroup Condition $(Configuration)|$(Platform) Debug|AnyCPU !-- 平台目标必须落到具体的位数AnyCPU 会让 CEF 找不到原生库 -- PlatformTargetx86/PlatformTarget Prefer32Bitfalse/Prefer32Bit OutputPathbin\Debug\/OutputPath /PropertyGroup ItemGroup !-- 三个托管程序集全部用相对路径引用换机器不用改 -- Reference IncludeCefSharp HintPath..\libs\CefSharp\managed\CefSharp.dll/HintPath PrivateTrue/Private /Reference Reference IncludeCefSharp.Core HintPath..\libs\CefSharp\managed\CefSharp.Core.dll/HintPath PrivateTrue/Private /Reference Reference IncludeCefSharp.WinForms HintPath..\libs\CefSharp\managed\CefSharp.WinForms.dll/HintPath PrivateTrue/Private /Reference /ItemGroup Target NameCopyCefNative AfterTargetsBuild !-- 原生文件用通配复制避免以后补文件忘了改工程 -- ItemGroup CefNative Include..\libs\CefSharp\native\$(PlatformTarget)\**\*.* / /ItemGroup Copy SourceFiles(CefNative) DestinationFiles(CefNative-$(OutputPath)%(RecursiveDir)%(Filename)%(Extension)) / /TargetPrivateTrue决定程序集是否复制到输出目录漏了就会在运行时报“无法加载文件或程序集 CefSharp.Core”。CopyCefNative里的$(PlatformTarget)让复制路径跟着平台目标走把平台从 x86 改成 x64 时不用再动手改复制路径。RecursiveDir保留locales\、swiftshader\这类子目录层级少了它所有 pak 文件会被拍平到根目录CEF 就找不到本地化资源。2.3 最小可运行窗体两处注册、一个 Dock把窗体做成“地址栏 浏览器”两行结构是验证环境最省事的形态出问题一眼能看出是加载失败还是渲染失败。示例里的主窗体只做三件事创建ChromiumWebBrowser、在加载任何页面之前注册桥接对象、挂上错误事件。public partial class MainForm : Form { private ChromiumWebBrowser _browser; public MainForm() { InitializeComponent(); _browser new ChromiumWebBrowser(about:blank); _browser.Dock DockStyle.Fill; // 关键绑定对象必须在页面脚本执行之前注册否则 JS 侧拿不到 window.bound _browser.RegisterJsObject(bound, new JsBridge(this)); // 加载失败和页面 console 输出都挂上排查时不用猜 _browser.LoadError OnLoadError; _browser.ConsoleMessage OnConsoleMessage; Controls.Add(_browser); _browser.Load(file:///C:/app/ui/index.html); } private void OnLoadError(object sender, LoadErrorEventArgs e) { System.Diagnostics.Debug.WriteLine( string.Format(load error url{0} code{1} text{2}, e.FailedUrl, e.ErrorCode, e.ErrorText)); } }DockFill的前提是这个控件最后加入Controls集合先加工具栏再加浏览器否则浏览器会把工具栏盖住。RegisterJsObject的第二个参数是一个普通 C# 对象CefSharp 会用反射把它暴露到页面的window.bound上第三个参数在示例里保持默认即把 C# 的 PascalCase 方法名映射成 JS 的 camelCase这条映射规则后面会单独提一次因为它是“方法明明写了却调不到”的头号原因。3. 初始化的三件事CefSettings 参数、调用时机和退出顺序3.1 CefSettings 里真正需要改的就那几项CefSettings有几十个属性实际项目里九成的人只会动其中五六个。剩下的保持默认改多了反而容易互相打架。示例代码把这几项提出来集中配置理由写在注释里。var settings new CefSettings { // 界面语言影响右键菜单和内置对话框不设会出现英文菜单 Locale zh-CN, // 缓存目录必须是可写路径放在 Program Files 下会静默失败 CachePath Path.Combine(Application.StartupPath, cef_cache), // 日志是唯一的黑匣子出问题第一件事就是看它 LogSeverity LogSeverity.Warning, LogFile Path.Combine(Application.StartupPath, cef.log), // 子进程默认在输出目录找自己挪过位置就必须显式指定 BrowserSubprocessPath Path.Combine( Application.StartupPath, x86, CefSharp.BrowserSubprocess.exe) }; // 远程桌面、老显卡、虚拟机里关掉 GPU 能省掉一半白屏投诉 settings.CefCommandLineArgs.Add(disable-gpu, 1); settings.CefCommandLineArgs.Add(disable-gpu-compositing, 1); // 页面里用到 getUserMedia 之类的接口时再打开默认关 settings.CefCommandLineArgs.Add(enable-media-stream, 1);CefCommandLineArgs是透传给 Chromium 的命令行开关disable-gpu加1是赋值形式不能只写 key。CachePath指向Application.StartupPath在绿色部署时很方便但如果程序装在受保护目录下这个路径不可写CEF 不会报错只是每次启动都当首次加载表现为“登录状态老是丢”这条坑我在现场遇到过两次才反应过来。3.2 初始化放 Program.cs只能调一次且必须在窗体之前Cef.Initialize的正确位置是Main里、Application.Run之前。放在窗体构造函数里也会跑但一旦有第二个窗体或者第二个浏览器实例就容易重复初始化直接抛异常。示例代码用一个静态标记加Cef.IsInitialized判重。[STAThread] static void Main() { // 同一进程内重复 Initialize 会抛异常多窗体场景下这句判重很关键 if (!Cef.IsInitialized) { var settings BuildCefSettings(); // 见 3.1 if (!Cef.Initialize(settings)) { // 初始化失败九成是原生依赖或位数问题日志里写得很清楚 MessageBox.Show(CEF 初始化失败请查看 cef.log); return; } } Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Application.Run(new MainForm()); }Cef.Initialize的签名在不同版本之间变过早期版本没有返回值也没办法在返回值里判断成败只能看日志文件49 这一代是有bool返回值的。这意味着从别处抄来的代码片段未必能直接编译遇到“参数数量不匹配”先查签名再说别急着怀疑 DLL 引错。还有一个细节值得说明STAThread特性不能丢。WinForms 的消息泵要求 STA 线程而 CEF 在初始化时会检查当前线程的单元状态缺了它可能出现拖拽、剪贴板、文件选择对话框集体失灵这种很玄学的现象。3.3 退出顺序Dispose 在前Shutdown 在后CefSharp 最典型的“翻车”现场不在启动而在关闭用户点叉窗口消失进程还挂在任务管理器里或者干脆弹一个AccessViolationException。原因几乎都是清理顺序不对——浏览器对象还没释放就先把 CEF 的全局运行时关掉了。protected override void OnFormClosing(FormClosingEventArgs e) { // 顺序不能换先停导航、再释放控件、最后关 CEF if (_browser ! null) { try { _browser.Stop(); _browser.Dispose(); } catch (Exception ex) { System.Diagnostics.Debug.WriteLine(browser dispose: ex.Message); } _browser null; } base.OnFormClosing(e); } // Program.cs 里补一刀兜住所有退出路径 Application.ApplicationExit (s, e) { if (Cef.IsInitialized) { Cef.Shutdown(); // 必须在所有 ChromiumWebBrowser 释放之后调用 } };Stop()的作用是打断正在进行的导航某些版本的Dispose在页面加载中会阻塞几百毫秒加上Stop()能把这段时间压下去。Cef.Shutdown()之后再访问任何浏览器实例都是未定义行为所以示例里紧跟着把字段置空避免别处的定时器还拿着引用。注意如果进程里还有后台线程在调EvaluateScriptAsyncShutdown也会卡住。清理前先把自己的定时器和后台任务停掉。4. C# 与 JS 互调绑定对象、线程切换和没有 async 的写法4.1 同步绑定与异步绑定先搞清楚什么时候用哪个CefSharp 提供两套暴露对象的方式。RegisterJsObject是同步的JS 调用后能直接拿到返回值代价是这会阻塞渲染进程的 JS 线程方法里做超过几十毫秒的事情页面就会卡顿。RegisterAsyncJsObject不阻塞但 JS 侧必须传一个回调函数当最后一个参数写法比同步版啰嗦。判断标准很简单取个配置项、返回个当前用户名用同步读文件、查数据库、调接口用异步。// 同步桥接JS 侧 bound.echo(x) 直接拿到返回值 public class JsBridge { private readonly MainForm _form; public JsBridge(MainForm form) { _form form; } // C# 里叫 EchoJS 里必须写 bound.echo默认 camelCase 映射 public string Echo(string text) { return csharp: text; } // 返回复杂对象时 CefSharp 会做 JSON 序列化别塞循环引用 public object GetUserInfo() { return new { name operator, role admin }; } } // 异步桥接JS 侧 bound2.readFile(cfg.json, function (text) { ... }) public class AsyncBridge { public void ReadFile(string path, IJavascriptCallback callback) { Task.Factory.StartNew(() { string text File.Exists(path) ? File.ReadAllText(path) : string.Empty; if (callback.CanExecute) { // 回调执行失败不要吞异常至少写日志 callback.ExecuteAsync(text) .ContinueWith(t System.Diagnostics.Debug.WriteLine(t.Exception), TaskContinuationOptions.OnlyOnFaulted); } }); } }IJavascriptCallback是 CefSharp 注入的位置固定在参数列表最后少写一个参数就会在 JS 侧报“回调不是函数”。CanExecute的判断不能省——页面已经导航走的时候回调对象会失效此时执行会抛异常。4.2 回调线程为什么在绑定方法里改控件必炸这是我最想提前说清楚的一条。绑定方法被调用时执行线程不是 WinForms 的 UI 线程而是 CEF 侧的线程。在里面直接label.Text ...轻则抛跨线程访问异常重则界面卡住不动——因为渲染线程正同步等着你的返回值你却在等 UI 线程两边互相等待死锁。public class JsBridge { private readonly MainForm _form; public JsBridge(MainForm form) { _form form; } // 从 JS 侧通知界面刷新标题 public void NotifyTitle(string title) { // InvokeRequired 在非 UI 线程上才为 true判断后再切回去 if (_form.InvokeRequired) { // 用 BeginInvoke 而不是 Invoke同步版桥接方法里用 Invoke 会死锁 _form.BeginInvoke(new Actionstring(_form.SetTitle), title); return; } _form.SetTitle(title); } }BeginInvoke是投递消息后立即返回Invoke是阻塞等待 UI 线程执行完。在同步绑定的方法里JS 线程正等着你 return你用Invoke等 UI 线程UI 线程如果这时恰好在等渲染结果就成了死锁。这条血泪经验没法从文档里读出来只能自己踩一次。4.3 C# 调 JS没有 async 关键字时怎么写VS2010 下不能写await但EvaluateScriptAsync返回的是TaskJavascriptResponse用ContinueWith接上完全一样只是嵌套深一点。private void ReadPageTitle() { // 表达式要包成 IIFE避免返回值被当成语句丢弃 _browser.EvaluateScriptAsync((function(){ return document.title; })()) .ContinueWith(t { if (t.IsFaulted || !t.Result.Success) { System.Diagnostics.Debug.WriteLine(eval failed: (t.IsFaulted ? t.Exception.Message : t.Result.Message)); return; } // 结果经过 JSON 反序列化字符串还是 string数字会变 double string title Convert.ToString(t.Result.Result); if (_browser ! null !_browser.IsDisposed) { BeginInvoke(new Action(() Text title)); } }); }JavascriptResponse有三个字段值得记住Success表示脚本有没有抛异常Result是反序列化后的返回值Message在失败时给出异常描述。Result的类型不是强类型的返回对象会变成字典或 JObject返回数字一律是double直接强转int会抛InvalidCastException用Convert.ToInt32更稳妥。另一条容易忽略的规则页面还在加载时调EvaluateScriptAsync脚本可能在旧文档上执行然后被导航冲掉结果就是你拿到一个空值。稳妥的做法是等FrameLoadEnd之后再发起首次调用。4.4 把调试信息引到自己的日志里嵌入浏览器的项目最怕“用户说白屏你这边一切正常”。示例里挂了两个事件把页面内部的信息引到自己的日志文件比让用户开 DevTools 现实得多。private void OnConsoleMessage(object sender, ConsoleMessageEventArgs e) { // 页面里的 console.log 原样过来前端排查不用远程连 Logger.Write(string.Format([js] {0} ({1}:{2}), e.Message, e.Source, e.Line)); } // 需要看网络请求时临时打开正式发布前关掉 _browser.ShowDevTools();ConsoleMessage事件如果一直不触发先检查是不是自定义了RequestHandler并覆盖掉OnConsoleMessage返回false会截断事件。ShowDevTools打开的窗口依赖CefSettings里没有禁用相关特性在精简过的包上可能弹不出来此时退回到日志方案。5. 避坑与排查五个把人卡半天的现场5.1 启动与加载类现象一双击 exe 直接退出事件查看器里连异常都没有。原因基本是原生库没到位——要么libcef.dll没复制到输出目录要么平台目标写的AnyCPU而x86\目录不存在。解决方式是先看输出目录里有没有libcef.dll和CefSharp.BrowserSubprocess.exe再把PlatformTarget改成明确的x86最后确认复制目标的目录名和$(PlatformTarget)的值一致。这三步能盖掉八成“程序一闪就没”的问题。现象二窗口出来了浏览器区域纯白FrameLoadEnd从不触发。先在LoadError里打日志如果ErrorCode是负数且FailedUrl是本地路径多半是路径写错或者文件编码不对如果是远程地址检查目标机器上有没有拦截出站访问的策略。还有一种情况是页面加载了但渲染没出来——远程桌面或者老显卡环境下把disable-gpu和disable-gpu-compositing都打开白屏概率立刻下降。这一条属于环境相关不是代码 bug但报障的人永远描述成“你的程序有问题”。现象三开发机正常客户机上启动就提示缺少 DLL。缺的是 VC 运行库——CEF 的原生层依赖对应版本的系统运行库。解决方式是把运行库安装包随发布包一起提供或者在部署说明里写清依赖。别指望“装个 .NET 4.0 就够了”托管框架和原生运行库是两码事。5.2 互调类现象四JS 报bound.myMethod is not a function。三个原因按概率排序方法名大小写不匹配C# 的MyMethod在 JS 里是myMethod、注册时机晚于页面脚本执行、绑定对象是同步注册但 JS 用了异步回调写法。排查时先在页面里执行typeof bound看对象在不在再执行Object.keys(bound)看暴露了哪些方法名两步就能定位。现象五关闭窗口时进程不退或者退出瞬间弹AccessViolationException。原因是清理顺序错或者还有后台线程持有浏览器引用。把Dispose、Shutdown、停定时器三步按顺序走一遍并且在Shutdown之后不再访问任何 CEF 对象。如果进程仍不退出用任务管理器看一下是不是CefSharp.BrowserSubprocess.exe残留那说明主进程的Shutdown没被调用到。现象六绑定方法里弹了个 MessageBox页面直接卡死。同步桥接方法在渲染线程上执行弹模态框会把这条线程占住JS 侧等不到返回值整个页面失去响应。解决方式是把交互挪到 UI 线程用BeginInvoke异步弹或者干脆改成异步桥接。这类问题在测试阶段很难发现因为开发时大家习惯点一下就走。6. 搬到客户机上部署清单与一条自检命令打包发给别人之前先照下表把输出目录过一遍。CefSharp 的坑集中在“文件缺一个就白屏”上清单比记忆可靠。文件或目录缺了会怎样备注CefSharp.dll、CefSharp.Core.dll、CefSharp.WinForms.dll启动报找不到程序集必须与 libcef 版本配套libcef.dll进程直接退出位数必须与平台目标一致CefSharp.BrowserSubprocess.exe浏览器区域空白放在x86\或x64\子目录下icudtl.dat中文乱码或启动失败大小几十 MB最容易被漏拷cef.pak、cef_100_percent.pak、cef_extensions.pak界面控件样式异常三个都要locales\zh-CN.pak右键菜单变英文目录层级不能拍平d3dcompiler_47.dll、libEGL.dll、libGLESv2.dll特定机器渲染失败显卡驱动环境差异大swiftshader\无 GPU 环境回退失败虚拟机里尤其重要清单过完之后还有一步是很多人省掉的给程序加一个启动自检。思路是拿一个必然成功的表达式去问浏览器能看到正确结果说明 CEF 起来了、页面上下文在了、脚本通道通了三件事一次性验完。private bool SelfCheck(int timeoutMs) { bool ok false; // 放到后台线程等别把 WinForms 的消息泵堵死 Task.Factory.StartNew(() { var task _browser.EvaluateScriptAsync( (function(){ return typeof bound ! undefined ? bound.echo(ping) : no-bridge; })()); if (!task.Wait(timeoutMs)) { Logger.Write(自检超时页面可能未加载完成); return; } if (!task.Result.Success) { Logger.Write(自检脚本异常 task.Result.Message); return; } ok csharp:ping.Equals(Convert.ToString(task.Result.Result)); }).Wait(timeoutMs 500); return ok; }这段代码的价值不在“检测功能是否正常”而在把三类故障区分开超时说明页面还没加载完或者渲染线程被占住脚本异常说明页面上下文有问题返回no-bridge说明绑定对象没注册上。日志里出现哪一句对应的排查方向立刻明确不用再靠“重启试试”这种玄学手段。参数上timeoutMs给 3000 到 5000 比较合适太短会在老机器上误报太长会让启动画面僵住。外层那个.Wait(timeoutMs 500)是后悔药防止内层Task因为某种原因没结束而让整个自检挂死。另外一个建议是把自检结果写进启动日志而不是弹窗。现场用户看到弹窗只会点确定日志才会被带回来。从那以后我每次交付带浏览器的客户端都会强制走一遍“清单核对 自检日志”这两个动作哪怕这次只改了一行页面代码——因为漏拷一个icudtl.dat导致的返工成本远高于花五分钟核对。希望帮到你。本文还有配套的精品资源点击获取
