> For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt.

# @lynx-js/cef-webview


`@lynx-js/cef-webview` 是 Lynxtron 官方维护的原生能力库，用来提供基于 CEF 的
[`<webview>`](/next/zh/api/elements/built-in/webview.md) 元素。它包含平台相关的 Lynxtron
原生产物，并提供 `./lynxtron` 入口，用来加载当前平台产物，让其中的 Lynx
静态注册在宿主进程中生效。

:::note 工具链版本

配套的 AutoLink 工具链和自动打包配置，详见 [webview 入门](/next/zh/lynxtron/Native-Libraries/Officially-Maintained-Libraries/cef-webview-getting-started.md)。

:::

## 安装


```sh [npm]
npm install @lynx-js/cef-webview
```

```sh [yarn]
yarn add @lynx-js/cef-webview
```

```sh [pnpm]
pnpm add @lynx-js/cef-webview
```

```sh [bun]
bun add @lynx-js/cef-webview
```

```sh [deno]
deno add npm:@lynx-js/cef-webview
```

## 宿主入口

在创建 `LynxWindow` 或加载 Lynx bundle 之前，在主进程中导入 Lynxtron 入口：

```ts
import { app } from '@lynx-js/lynxtron';
import cefWebview from '@lynx-js/cef-webview/lynxtron';

app.whenReady().then(() => {
  cefWebview.initialize();
  // 在此之后创建 LynxWindow。
});
```

`initialize()` 方法会为当前进程初始化 Chromium Embedded Framework (CEF)。AutoLink
在为 Lynxtron 宿主构建收集包时，也会使用 `./lynxtron` 入口。

### 初始化结果与进程限制

`initialize(): boolean` 成功时返回 `true`，原生初始化失败时抛出异常。失败后不要继续创建 WebView，应查看原生日志定位原因。

CEF 根据宿主应用标识选择存储目录；使用相同标识的多个实例可能发生存储冲突。同一宿主可以创建多个 WebView。存储冲突只是初始化失败的一种可能原因。

根入口与 `./lynxtron` 入口均提供该宿主 API 的 TypeScript 声明。

## 导出

| 导出               | 说明                          |
| ---------------- | --------------------------- |
| `.`              | CommonJS 包入口。               |
| `./lynxtron`     | 加载当前平台原生二进制的 Lynxtron 宿主入口。 |
| `./package.json` | package metadata。           |

## 包元数据

包内包含带 Lynxtron 元数据的 `lynx.lib.json`。下面的节选省略了完整平台矩阵和
Windows 运行时文件列表：

```json
{
  "platforms": {
    "lynxtron": {
      "targets": [
        {
          "os": "darwin",
          "arch": "arm64",
          "files": ["dist/darwin/arm64/cef_extension.node"],
          "frameworks": [
            "dist/darwin/arm64/frameworks/Chromium Embedded Framework.framework"
          ],
          "appBundles": [
            "dist/darwin/arm64/frameworks/LynxtronWebview Helper.app",
            "dist/darwin/arm64/frameworks/LynxtronWebview Helper (Alerts).app",
            "dist/darwin/arm64/frameworks/LynxtronWebview Helper (GPU).app",
            "dist/darwin/arm64/frameworks/LynxtronWebview Helper (Plugin).app",
            "dist/darwin/arm64/frameworks/LynxtronWebview Helper (Renderer).app"
          ]
        },
        {
          "os": "win32",
          "arch": "x64",
          "files": [
            "dist/win32/x64/cef_extension.node",
            "dist/win32/x64/cef_subprocess.exe",
            "dist/win32/x64/libcef.dll",
            "dist/win32/x64/locales"
          ]
        }
      ]
    }
  }
}
```

`files` 列出在安装包中保持相邻位置的 payload；`frameworks` 和 `appBundles`
列出由 builder 放入 `Contents/Frameworks` 的 macOS bundle，其中嵌套应用也会
进入宿主签名流程。

完整接入流程见
[在 Lynxtron 中使用 webview](/next/zh/lynxtron/Native-Libraries/Officially-Maintained-Libraries/cef-webview-getting-started.md)。
