cefsharp.wpf 初始化失败、黑屏或崩溃的根本原因是运行时依赖未对齐，包括架构（x86/x64）、.net 版本、windows sdk 与本地 dll（如libcef.dll）严格匹配；项目平台目标不可设为any cpu，cefsharp.common与wpf包版本须完全一致；cef.initialize()需在app.onstartup早期同步调用且仅一次，配合multithreadedmessageloop=false；chromiumwebbrowser必须显式设置尺寸或确保父容器提供确定大小，避免置于scrollviewer/viewbox中；js调用c#需通过dispatcher切回wpf线程以避免跨线程异常。
为什么 CefSharp.Wpf 初始化失败、黑屏或直接崩溃
根本原因通常是运行时依赖没对齐，不是代码写错了。CefSharp 不是纯托管库，它背后绑着 Chromium 的本地 DLL（libcef.dll、chrome_elf.dll 等），这些文件必须和 .NET 运行时架构（x86/x64）、.NET 版本（.NET 5+ / .NET Framework）、甚至 Windows SDK 版本严格匹配。
- 项目平台目标（Platform Target）必须设为
x64或x86，不能用Any CPU（尤其在 .NET 6+ 中默认启用“首选 32 位”会隐式降级到 x86，导致 x64 CEF 加载失败） -
CefSharp.Common和CefSharp.Wpf的 NuGet 包版本必须完全一致，混用 122.x 和 123.x 会触发System.MissingMethodException - 调试时如果看到
Unable to load DLL 'libcef'，八成是libcef.dll没复制到输出目录，或者被杀毒软件误删——检查bin\Debug下是否存在该文件及其配套 DLL
如何正确初始化 CEF 并避免 UI 线程阻塞
Cef.Initialize() 必须在 WPF 应用启动早期调用，且只能调用一次；但它本身是同步阻塞的，如果放在 App.OnStartup 里不做处理，会导致窗口白屏几秒才出现。这不是 bug，是 Chromium 初始化资源加载的必然开销。
- 在
App.xaml.cs的OnStartup中调用Cef.Initialize()前，先设置CefSettings的MultiThreadedMessageLoop = false（WPF 默认使用单线程调度器，设为 true 反而容易出错） - 不要在
MainWindow构造函数或Loaded事件里初始化 CEF——此时 UI 已开始渲染，阻塞会卡死整个界面 - 若需异步加载页面，用
browser.Load("https://example.com")即可；但不要在Load后立刻访问browser.Address，它可能还是null，应监听FrameLoadEnd事件
CefSharp.Wpf.ChromiumWebBrowser 在 XAML 中不显示或尺寸异常
常见表现是控件区域全黑、只显示一行灰边、或拉伸错位。本质是 WPF 的布局系统与 Chromium 渲染层交互时，对 Width/Height、HorizontalAlignment 等属性敏感，且不支持某些动态尺寸策略。
- 必须显式设置
Width和Height，或确保其父容器（如Grid行列定义）能提供明确尺寸；Horizontal/VerticalAlignment="Stretch"仅在父容器有确定大小时才生效 - 避免把
ChromiumWebBrowser放进ScrollViewer或Viewbox，它们会触发非预期缩放或裁剪，导致渲染异常甚至崩溃 - 首次加载页面前，控件
IsVisible为false或Visibility="Collapsed"会导致后续无法正常渲染——务必保证初始化后控件处于Visibility="Visible"
如何安全地从 JS 调用 C# 方法并避免跨线程异常
RegisterAsyncJsObject 是常用入口，但它的回调默认在 CEF 的 UI 线程（不是 WPF 的 Dispatcher 线程），直接更新 UI 控件会抛 InvalidOperationException：“调用线程无法访问此对象”。
- 注册对象时传入的 JS 对象名（如
"bound"）必须是合法标识符，不能含点号或中划线；否则 JS 侧调用会静默失败 - 所有需要操作 UI 的回调，必须手动切回 WPF 线程：
Application.Current.Dispatcher.Invoke(() => { /* 更新 TextBox.Text */ }); - 如果 JS 频繁调用（比如每秒几十次），避免在回调里做耗时操作；CEF 的 JS 执行是单线程的，阻塞它会影响页面响应
CEF 的进程模型和线程模型比表面看起来深得多，尤其是混合了 WPF 的 Dispatcher 和 Chromium 的 TaskRunner 后，很多问题不是“会不会”，而是“在哪一线程上执行”。别信“只要加个 await 就行”，JS 回调本身就不走 .NET 的 async/await 路径。
