一、引言

1.1 欢迎使用CEF

欢迎您关注并使用HarmonyOS CEF！CEF是一个将Chromium嵌入到其他应用程序的开源框架。它提供简单的API，允许开发者将完整的浏览器功能集成到现有应用中。CEF对HarmonyOS平台进行了适配，可助力开发者在HarmonyOS上更高效、更稳定地构建应用。

1.2 本篇文档目的

本文档旨在向开发者清晰地传达以下关键信息：

1. CEF在HarmonyOS上的支持状态。

2. 提供快速上手和深入使用CEF的开发指导。

3.建议开发者在开始使用CEF进行开发前，仔细阅读本文档。

二、支持声明

2.1 支持确认

CEF框架已获得HarmonyOS生态合作伙伴的支持，当前CEF框架HarmonyOS版已开源，欢迎访问CEF分支进行使用，对应分支为pc_chromium_132。

特别注意：本资源库专为独立运行的CEF设计，不支持与其他框架组合使用，若需嵌入其他框架，请咨询技术支持。

2.2 开箱即用

开发者现在可以在HarmonyOS5.0上放心地集成和使用CEFHarmonyOS化版本进行项目开发。该框架已深度适配平台环境，并在HarmonyOS5.0环境中经过严格测试与验证，确保核心功能的稳定运行和兼容性。

2.3 持续维护和演进

CEF HarmonyOS版本已于2025年6月在OH社区上正式开源，后续更新计划正在规划中，我们将持续投入资源对CEF HarmonyOS版本进行维护、升级和优化，及时修复问题，并根据平台发展和开发者反馈引入新特性，确保其长期的生命力和竞争力。

三、CEFHarmonyOS化开发指导

3.1 环境配置

操作系统：Ubuntu 22.04 磁盘空间：大于100G 内存：大于16G CPU架构：x86_64

3.2 编译源码构建应用

3.2.1 源码与工具下载安装

3.2.1.1 工具安装

（1）安装工具git-lfs, ccache（注：该步骤仅需要在首次拉取代码时执行）

# 安装 git-lfs，确保仓库中的大文件能拉取到本地。ccache 为编译器缓存。
$ sudo apt install git-lfs ccache

（2）配置工具repo（注：该步骤仅需要在首次拉取代码时执行，执行该步骤前请确保已经配置好了python3环境）

# 下载码云repo工具(可以参考码云帮助中心：https://gitee.com/help/articles/4316)
$ mkdir -p ~/bin
$ curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo
$ chmod a+x ~/bin/repo
$ echo 'export PATH=~/bin/:$PATH' >> ~/.bashrc
$ source ~/.bashrc
$ pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests

3.2.1.2 拉取chromium-cef仓库代码

（1）从代码仓克隆chromium-cef仓库：

# 使用https拉取chromium-cef代码
$ cd [path_to_chromium_cef]
$ git clone -b pc_chromium_132 https://gitcode.com/openharmony-tpc/chromium_cef.git

# 执行命令`git lfs pull`，确保仓库中的大文件已经下载完成
$ git lfs pull

# 拉取chromium-cef对应的ohos chromium代码
$ cd [path_to_chromium]   # 切换目录到chromium根目录
$ repo init -u  https://gitcode.com/openharmony-tpc/manifest.git -b pc_chromium_132 -m pc_chromium_132_20251106.xml --no-repo-verify
$ repo sync -c  # 可以执行多次，以确保代码全部拉取成功
$ repo forall -c 'git lfs pull'  # 可执行多次，以确保大文件全部拉取成功

# 应用chromium-cef的patch到ohos chromium
$ cd [path_to_chromium_cef]   # 切换目录到chromium-cef根目录
$ chmod +x apply_cef_patchs.sh
$ ./apply_cef_patchs.sh [path_to_chromium]/src [path_to_chromium_cef]  #脚本需要输入两个路径，第一个是chromium代码下的src的路径，第二个是下载的cef的路径

（2）运行CEF实际目录/src/build/install-build-deps.sh脚本，安装编译所需的软件包（注：该步骤仅需要在首次拉取代码时执行）：

$ sudo ./src/build/install-build-deps.sh --no-chromeos-fonts

（3）运行脚本build.sh编译CEF：

$ ./build.sh

3.2.2 输出结果

编译完成后，会在src/out/musl_64目录下输出的编译产物文件如下：

• cefclient_files
• ceftests_files
• locales
• chrome_100_percent.pak
• chrome_200_percent.pak
• icudtl.datresources.pak
• v8_context_snapshot.bin
• libadapter.so
• libcef.so
• libcefsimple.so

可以通过如下脚本拷贝所需资源（注：请参考修改为自己的source_path）：

#!/bin/sh
source_path=./cef实际目录/src/out/musl_64
destination_path=./cef
if [ -d ${destination_path} ];then
rm -rf ${destination_path}
fi
mkdir ${destination_path}
cp -r ${source_path}/cefclient_files ${destination_path}
cp -r ${source_path}/ceftests_files ${destination_path}
cp ${source_path}/chrome_100_percent.pak ${destination_path}
cp ${source_path}/chrome_200_percent.pak ${destination_path}
cp ${source_path}/icudtl.dat  ${destination_path}
cp ${source_path}/v8_context_snapshot.bin ${destination_path}
cp ${source_path}/libadapter.so ${destination_path}
cp ${source_path}/libcef.so ${destination_path}
cp ${source_path}/libcefsimple.so ${destination_path}
mkdir ${destination_path}/locales
cp ${source_path}/locales/zh-CN.pak ${destination_path}/locales
cp ${source_path}/locales/en-US.pak ${destination_path}/locales

将脚本保存为copy.sh放置于编译文件夹chromium文件夹同级，并执行，执行脚本后会将所需资源拷贝到同级的cef中。

3.3 HAP包构建与使用

HAP包工程位置：源码目录src/ohos/app/文件夹内。

3.3.1 编译未签名的HAP包

在工程中新建chromium/libs/arm64-v8a文件夹，替换chromium/libs/arm64-v8a目录与web_engine/src/main/resources/resfile目录下的资源，并使用DevEco Studio进行编译安装。

注：libc++_shared.so位于OHOS系统sdk中，路径：/src/ohos_sdk/openharmony/native/llvm/lib/aarch64-linux-ohos。

资源文件放置后，目录结构如下：

so库与resfile都放入指定位置后，点击Build -> Build Hap(s)/APP(s) -> Build Hap(s)按钮编译生成未签名的hap包或点击右上角运行按钮启动应用。

编译完成后，未签名的HAP包会被保存到ohos_hap/chromium/build/default/outputs/default/下，文件名chromium-default-unsigned.hap。

3.3.2 签名与权限

（1）可以选择自动签名或手动签名方式，参考：配置调试签名。

（2）权限配置文件位置：ohos_hap\web_engine\src\main\module.json5文件中requestPermissions字段，以下是当前声明的权限及说明，若需要了解更多权限，参考：应用权限列表。

查看权限申请官方流程：申请应用权限，权限申请邮件内容示例如下：请根据实际需要的授权申请权限，示例内容仅供参考

cef中需要ACL签名的权限包括（如果未申请到证书导致签名未通过，可以暂时将这几个权限注释掉）：

"requestPermissions": [
      {
        "name": "ohos.permission.SYSTEM_FLOAT_WINDOW"
      },
      ...
      {
        "name": "ohos.permission.READ_PASTEBOARD",
        "reason": "$string:access_pasteboard",
      },
      ...
      {
        "name": "ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY",
        "reason": "$string:reason_download",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when":"always"
        }
      },
      {
        "name": "ohos.permission.READ_WRITE_DOCUMENTS_DIRECTORY",
        "reason": "$string:reason_documents",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when":"always"
        }
      },
      {
        "name": "ohos.permission.READ_WRITE_DESKTOP_DIRECTORY",
        "reason": "$string:reason_desktop",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when":"always"
        }
      }
    ]

3.3.3 运行已签名的HAP包

申请证书后在DevEco Studio中配置：

配置完成后点击右上角的run按钮即可运行：

或者在命令行中执行命令安装HAP包：

hdc app install <已签名hap包路径>
# e.g: hdc app install pc_entry-default-signed.hap

四、坚盾守护模式特别说明

4.1 坚盾守护模式

坚盾守护模式是为高安全需求用户设计的系统级安全防护方案。该模式通过实施严格的功能限制，显著增强系统安全性，有效防范针对远程攻击面的各类威胁。在坚盾安全模式下，系统增加了功能限制，需要开发者评估应用在坚盾模式下的可用性。

4.2 启用坚盾守护模式

要启用坚盾守护模式，请按以下路径操作：

（1）进入电脑系统设置。

（2）选择"隐私和安全"选项。

（3）点击"坚盾守护模式"并开启。

4.3 坚盾守护模式下的功能限制

为降低应用受攻击风险，坚盾守护模式将实施以下关键安全限制：

• 全面禁用即时编译(JIT)功能，包括已获取 ACL 权限的应用程序。
• 暂停 WebAssembly 支持（当前版本中 WebAssembly 依赖 JIT 功能实现）。

4.4 应用兼容性评估指南

在坚盾守护模式下运行应用程序时，建议进行以下兼容性检查：

（1） JavaScript 性能评估：

• 测试应用在限制环境中的运行效率。
• 优化可能存在的性能瓶颈。

（2）WebAssembly 兼容性检查：

• 静态代码分析：检查项目中的 WebAssembly 相关API调用，与第三方库的 Wasm 依赖情况。
• 运行时验证：在坚盾守护模式下执行全功能测试。

  参考链接：坚盾守护模式，查询设备安全模式(C/C++)，JSVM-API 坚盾守护模式。