Skip to content

06 CEF Configuration

Jump to bottom
starTechnology1994 edited this page Aug 7, 2026 · 1 revision

06 CEF 参数配置

插件运行期参数通过项目 ini 文件中的 [WebNative] 配置节 统一管理。本章列出全部配置项、默认值、用途与推荐组合。

1. 配置文件位置

插件的 ini 配置写入项目的 Config/DefaultGame.ini（开发期）或打包后 Saved/Config/<平台>/Game.ini：

DefaultGame.ini 配置位置
图 6-1 DefaultGame.ini 配置位置 
[WebNative]
; ===== 常规 =====
clear_cache=false
clear_log=true
offgpu=false
touch_events=true
keyboard_f5=false
ctrl_scale=false
gpu_shared_mutex_per_adapter=false
multi_open=false
linux_single_process=false

; ===== 调试与性能 =====
show_cef_performance_monitor=true
show_download_notification=true
debugging_port_min=9223
debugging_port_max=9262

; ===== CEF 命令行 =====
cefcore=disable-web-security no-proxy-server allow-file-access-from-files allow-universal-access-from-files allow-running-insecure-content allow-insecure-localhost
cef_args=

修改配置后需要完整退出并重启应用（尤其 linux_single_process、multi_open 等进程级选项）。

2. 常规设置

配置键 类型 默认值 用途
clear_cache bool false 退出时删除 CEF 缓存（Cookie、LocalStorage 等）
clear_log bool true 退出时删除 CEF 日志目录
offgpu bool false 禁用 GPU 加速渲染，强制 CPU 软渲染（虚拟化/兼容性环境）
touch_events bool false 启用触摸输入
keyboard_f5 bool false 允许 F5 刷新网页
ctrl_scale bool false 允许 Ctrl + 滚轮缩放网页
gpu_shared_mutex_per_adapter bool true 按 GPU 适配器限制共享纹理并发数多实例场景如果GPU有压力建议true
multi_open bool false 多实例多开：false 时单实例独占锁（锁文件 Saved/WebNativeBrowser/.wnb_instance.lock，被占用自动回退多开）；true 时每实例独立缓存/日志目录
linux_single_process bool false 如遇到国产CPU和GPU平台下视频无法播放,建议设置成true

3. 调试与性能

配置键 类型 默认值 用途
show_cef_performance_monitor bool false 浏览器左下角实时性能叠加层（FPS / 内存 / 渲染模式）
show_download_notification bool true 显示内置下载进度条与完成/失败提示；false 时仅广播 JS 下载事件（见 07-文件上传下载）
debugging_port_min int 9223 DevTools 远程调试端口范围下限（0 表示禁用）
debugging_port_max int 9262 端口范围上限，范围内自动选择首个可用端口

开启远程调试后，可在 Chrome/Edge 访问 http://127.0.0.1:<端口> 调试任意页面；端口仅绑定本机回环地址。焦点在网页按快捷键Ctrl+F12既可以打开

4. 权限策略（18 项）

插件内置 18 项权限开关 + 1 个兜底开关，默认放行主流网页能力，可按项目安全策略整体收紧。

4.1 全局策略

配置键 默认值 用途
media_permission_policy allow 媒体设备（摄像头/麦克风）全局策略：allow / deny / prompt
permission_prompt_policy allow 通用权限弹窗全局策略，取值同上
  • allow：插件直接放行，不弹窗。
  • deny：插件直接拒绝。
  • 其他值（如 prompt）：交还 CEF 原生权限弹窗。

4.2 单项权限开关

配置键 默认值 对应权限
allow_microphone true 麦克风（音频采集）
allow_camera true 摄像头（视频采集）
allow_desktop_capture true 屏幕/桌面捕获（含系统音频）
allow_clipboard true 剪贴板读写
allow_geolocation true 地理位置
allow_notifications true 桌面通知
allow_local_network_access true 本地网络访问
allow_file_system_access true File System Access API（含磁盘配额）
allow_pointer_lock true 指针锁定（游戏场景）
allow_keyboard_lock true 键盘锁定
allow_storage_access true 第三方存储访问
allow_protected_media true EME / Widevine DRM 受保护媒体
allow_local_fonts true 本地字体枚举
allow_midi_sysex false MIDI SysEx
allow_multiple_downloads true 多文件并发下载
allow_window_management true 多屏/窗口管理
allow_extended_reality false WebXR（AR / VR / 手势追踪）
allow_other_permission_prompts false 兜底开关：true 时所有未列出的权限请求一律放行

说明：单项开关同时作用于媒体访问与权限弹窗两条路径；allow_other_permission_prompts=false 时，未列入上表的权限请求默认拒绝。

安全建议： 面向公开客户的正式产品，建议按业务需要将不使用的权限设为 false，例如：

allow_geolocation=false
allow_notifications=false
allow_midi_sysex=false
allow_extended_reality=false
allow_other_permission_prompts=false

5. CEF 命令行参数

通过两个自由字符串键向 CEF 注入命令行开关：

配置键 默认值 作用范围
cefcore disable-web-security no-proxy-server allow-file-access-from-files allow-universal-access-from-files allow-running-insecure-content allow-insecure-localhost 影响所有子进程（GPU / 网络 / 渲染），以 --开关 形式注入
cef_args 空 仅渲染进程参数，如 show-background-color background-color=0x00000000（透明背景）

5.1 透明背景

需要透明页面叠加到三维场景时：

cef_args=show-background-color background-color=0x00000000

同时网页本身需要：

html, body { background: transparent; }

5.2 关闭跨域限制

开发期调试跨域接口可临时移除 disable-web-security 之外的限制（默认值已包含 no-proxy-server 等，生产环境请按安全策略评估）。

6. 常见配置组合

场景 推荐配置
通用业务 UI 保持默认即可
大屏/展厅（多开） multi_open=true、gpu_shared_mutex_per_adapter=false
虚拟机/国产 GPU 兼容 offgpu=true（或 Widget 关闭 GPU 加速）、linux_single_process=true
严格权限的产品 permission_prompt_policy=deny + 按需开启单项权限
性能分析 show_cef_performance_monitor=true

下一步

Clone this wiki locally