SDK JavaScript API 总览

选择正确的执行上下文，了解 API 域和返回类型，并查阅各项能力的完整参考。

浏览器直接提供 globalThis.chrovia，不需要导入 SDK。通常在 Provision 扩展的 Service Worker 使用。按开发入门和插件安装指南创建插件。

API 域与参考

API 域	能力	参考
`chrovia.prefs`	`extendedPrefs`	EP 存储、get/set/remove、Profile 设置
`chrovia.network`	`networkIntercept`	选项、请求解析、取消与 Worker 生命周期
`chrovia.messaging`	`messaging`	通道、发布订阅和启动回复
`chrovia.ui`	`nativeDialog`	Alert、confirm 和 notify
`chrovia.process`	`processManagement`	正常退出浏览器
`chrovia.automation`	`automation`	仅限 Window 的 DOM 工具和可信事件
`chrovia.passwords`	`passwords`	仅限 Provision Worker 的密码存储
`chrovia.instanceMetadata`	`instanceMetadata`	运行时和公开元数据对象
`chrovia.license`	无独立域能力	License 快照和租约集成

不是每项能力都有 JavaScript 域。指纹、代理、外观、DNR、注入凭据等配置驱动功能见完整能力索引。

执行上下文与可用性

能力未授予时，对应域返回 undefined。调用前检查根对象和域。对象存在不证明请求的所有操作都成功，也不证明在线租约正常。

默认网页、扩展标签页和 popup 没有根对象。popup 应通过 chrome.runtime.sendMessage 请求自己的 Worker 执行具体操作。unrestrictedApi 扩大开放范围，但不授予具体能力。automation 仅限 Window，passwords 即使在扩大开放后仍只对 Provision Service Worker 开放。

不要据此推断 Node.js、DedicatedWorker 或 SharedWorker 也支持这些 API。外部启动器负责启动浏览器及准备文件，它的 Node.js 全局对象不是浏览器的 chrovia。

返回值

prefs、passwords、ui、license 方法返回 Promise，需要处理拒绝并查阅各方法的无操作或失败行为。messaging.on/emit/off、network.intercept/stopIntercepting、process.exit 返回 undefined。尤其是 await intercept() 不会确认浏览器端就绪，但拦截回调本身可以返回 Promise。

instanceMetadata 是数据对象，不是方法或 Promise。自动化方法是同步的，输入无效时可能抛错。

生命周期与状态

在 Service Worker 脚本执行时注册监听和拦截，不要只在 onInstalled 中注册。空闲 Worker 可能停止，并在之后重启；JS 全局状态不会保留。进程级消息和唯一网络会话需要插件之间协调所有权。

prefs 和消息使用兼容 JSON 的值。不要把秘密记录到日志或交给页面可访问的数据。写入 Promise 正常解析不代表通用的持久化或授权保证。修改 internal 前先了解 EP 签名。