ChroviaChrovia

SDK 开发入门

启动独立的 Chrovia 浏览器实例，创建 Provision 扩展，并调用第一个内核 JavaScript API。

Chrovia SDK 是带有扩展配置和 JavaScript API 的 Chromium 浏览器运行时。chrovia 对象由浏览器内置提供，不是需要在网站或 Node.js 应用中导入的 npm 包。

你的应用负责启动浏览器、准备实例文件。Chrovia License 授权能力，Extended Preferences 配置实例，Provision 扩展运行需要内核特权 API 的浏览器端逻辑。

1. 准备浏览器和 License

先按照下载和安装试用 License获取浏览器压缩包和已签发的 License。本例需要勾选 Extended Preferences（extendedPrefs）。保留随浏览器附带的 Chrovia Infra 扩展，它负责需要在线授权的许可证的联网流程。

完整解压浏览器。不要修改已签名的 License 来增加能力，应重新申请包含所需能力的 License。

2. 选择实例目录

为测试实例创建独立目录，将已签发的许可证放入其中，文件名必须为 Chrovia License，不带扩展名：

sdk-profile/
  Chrovia License

启动时通过 --user-data-dir 传入该目录的绝对路径。目录会保存这个实例的浏览器数据，包括 Cookie 和已保存的密码。不同的独立实例应使用不同目录。

浏览器优先读取用户数据目录中的 Chrovia License。只有该文件不存在时，才使用 Provision 根目录中的同名文件。用户数据目录中存在但无效的 License 不会回退到 Provision 副本。

如果 License 包含 signedExtendedPrefs，启动前还需要放入正确签名的 Extended Preferences 文件。如果只是测试不需要签名的配置，请申请不包含该能力的 License，不要从已签发的文件中自行删除它。详见 Extended Preferences。

3. 添加 Provision 扩展

标准 Chrovia 发行包的 Provision 根目录，在 Windows 上是可执行文件旁的 Chrovia 文件夹，在 macOS 上是 Chrovia.app/Contents/Chrovia。自定义品牌发行包可能使用不同的目录名。

在 Extensions 下新增目录，保留原有文件和扩展：

Chrovia/
  manifest.json
  Extensions/
    chrovia-infra/
    sdk-example/
      manifest.json
      background.js

根目录的 manifest.json 是发行包元数据。sdk-example 内的 manifest.json 才是 Chrome 扩展清单，内容如下：

{
  "manifest_version": 3,
  "name": "SDK Example",
  "version": "1.0.0",
  "background": {
    "service_worker": "background.js"
  }
}

创建 background.js：

const prefs = globalThis.chrovia?.prefs;

async function runExample() {
  if (!prefs) {
    console.error('SDK Example: extendedPrefs is unavailable');
    return;
  }

  await prefs.set('sdk_example.message', 'Hello from Chrovia SDK');
  console.log(await prefs.get('sdk_example.message'));
}

runExample().catch(console.error);

不需要在 Chrome 扩展清单中添加名为 extendedPrefs 的权限：它是 License 能力，不是扩展权限。标准 chrome.* API 和扩展中的网络请求仍需遵守各自的清单权限要求。

浏览器启动时自动加载 Extensions 直接子目录中的插件。更新插件时保持目录名不变，不需要点击加载已解压的扩展程序。

4. 启动并调试

更换文件或启动参数后，先完全退出测试实例，再重新启动。请按实际安装位置调整路径。

Windows PowerShell

& 'C:\SDK\Chrome-bin\chrovia.exe' --user-data-dir='C:\SDK\sdk-profile' --show-component-extension-options

macOS 终端

./Chrovia.app/Contents/MacOS/Chrovia \
  --user-data-dir="$HOME/chrovia-sdk-profile" \
  --show-component-extension-options

打开 chrome://extensions，启用开发者模式，找到 SDK Example 并检查其 Service Worker。在该控制台运行：

await chrovia.prefs.get('sdk_example.message')

预期返回 Hello from Chrovia SDK。上述调试参数用于显示组件扩展，正常运行不需要。请勿使用已通过 License 和配置禁用 DevTools 的实例进行本教程的调试。

代码运行位置很重要

默认只有 Provision 扩展的 Service Worker 能使用 chrovia，普通网页、扩展弹出窗口和扩展标签页都不能直接访问。弹出窗口应通过 chrome.runtime.sendMessage 请求自己的 Service Worker 执行具体操作。

unrestrictedApi 能力可以将 API 开放到页面上下文，但不会同时授予各个 API 的能力。本例不需要它。即使拥有 unrestrictedApi，passwords API 仍只对 Provision Service Worker 开放。

Service Worker 空闲时可能停止，之后再启动。应在每次脚本执行时注册监听和拦截逻辑，不要只放在 chrome.runtime.onInstalled 中。不要依赖全局变量跨越 Worker 重启保存状态。

开发循环与排查

  1. 修改扩展，将构建后的 JavaScript 复制到实际启动的浏览器所使用的 Provision 目录。
  2. 完全退出该浏览器实例，然后重新启动。
  3. 检查扩展的 Service Worker，而不是网页或弹出窗口的控制台。

如果没有 chrovia，检查执行上下文和 Provision 位置。如果仅 chrovia.prefs 不存在，检查 License 是否包含 extendedPrefs。如果 API 存在但读取返回 undefined，检查键名、已安装的 License 和 Extended Preferences 签名。API 对象存在不代表在线租约授权一定正常。

可以从下载页面获取 Chrovia Studio，运行各项能力的演示。有些 Studio 页面演示会申请 unrestrictedApi，不要将这种页面访问方式误认为 SDK 的默认集成方式。

接下来阅读 SDK 文档与能力索引，其中包含 License、租约、EP、Provision、插件安装及各项能力的独立指南。