SDK Extended Preferences

配置浏览器实例，读写应用数据，并了解 Extended Preferences 的 License 与签名规则。

Extended Preferences 是位于 --user-data-dir 指定目录中的 JSON 文件，文件名必须为 Extended Preferences，不带 .json。它与 Chromium 自身的 Preferences 文件、Chrovia License 都是不同的文件。

如果还没有准备浏览器实例和 Provision 扩展，请先阅读 SDK 开发入门。

文档结构

浏览器配置放在顶层 internal 对象中，应用自有数据可以放在它旁边。需要签名时，signature 是单独的顶层对象，不是 internal 的子项。

下面是完整的未签名示例，适用于已授予 extendedPrefs 和 instanceAppearance、但没有授予 signedExtendedPrefs 的 License：

{
  "internal": {
    "instance_appearance": {
      "label": "SDK Example",
      "background_color": "#059669",
      "foreground_color": "#FFFFFF"
    }
  },
  "sdk_example": {
    "message": "Hello from Chrovia SDK",
    "counter": 0
  }
}

在启动前写入文件。各项内核功能仍需对应的 License 能力：添加 instance_appearance 不会授予 instanceAppearance。除非某项功能明确支持运行时更新，否则应将内核配置视为启动配置；通过 API 写入 JSON 并不等于所有功能都会热更新。

Provision 默认文件与实例数据

可以在 Provision 根目录中放置初始 Extended Preferences，与根目录的 manifest.json 和 Extensions 文件夹并列。

首次启动时，如果用户数据目录没有 Extended Preferences，浏览器会将 Provision 中的文件复制过去，再加载实例副本。已有实例文件不会被覆盖，因此修改 Provision 中的初始文件不会更新现有实例。复制失败时会记录警告，并按文件缺失继续处理。

复制后的文件也必须满足 License 对已签名配置的要求。

JavaScript 读取、写入与删除

需要 extendedPrefs 能力，以及允许访问 API 的上下文，通常是 Provision Service Worker。

方法	返回值
`chrovia.prefs.get(key)`	Promise，解析为保存的值；不可用或键不存在时为 `undefined`
`chrovia.prefs.set(key, value)`	Promise，解析为 `undefined`
`chrovia.prefs.remove(key)`	Promise，解析为 `undefined`

键名是从整个文档根节点开始的点分路径。读取内核配置时需要带上 internal.：

async function readAndWritePrefs() {
  const prefs = globalThis.chrovia?.prefs;
  if (!prefs) {
    throw new Error('extendedPrefs is unavailable');
  }

  const label = await prefs.get('internal.instance_appearance.label');
  await prefs.set('sdk_example.message', 'Updated by the extension');
  const message = await prefs.get('sdk_example.message');
  await prefs.remove('sdk_example.counter');
  console.log({ label, message });
}

readAndWritePrefs().catch(console.error);

使用兼容 JSON 的值。值无法转换为可保存的数据时，set() 会以 DataCloneError 拒绝 Promise；应捕获错误并修正输入。这些方法不是事务，先读后写也不是原子递增。写入 Promise 成功解析，不代表数据已保存到磁盘或授权一定有效：偏好不可用、验证失败等情况可能使写入不执行任何操作。

配置签名

License 授予 signedExtendedPrefs 时，必须提供有效签名的文件。没有该能力时，浏览器不要求 Extended Preferences 签名，但仍然验证 License。

从配置提供方获取与 License 匹配的完整已签名文件。不要自行构造或编辑 signature 对象。修改受保护的设置前，应安排获取替换文件；浏览器没有用于签名的命令或 API。

将需要修改的应用数据放在 internal 外部，例如 sdk_example。对于已签名文件，通过编辑器或 prefs.set() 修改 internal 可能使文件在下次启动时不可用；应获取替换的已签名文件。

如果必需的验证失败，浏览器会阻止所有 Extended Preferences 读写，包括未签名的应用字段。get() 可能返回 undefined，set() 和 remove() 则可能正常解析却没有修改数据。不要将这些返回值当成签名验证 API。

配置下载目录

internal.profile_prefs 接受少量白名单内的 Chromium Profile 偏好，需要 extendedPrefs 能力。它不是通用 Chrome 策略或 Local State API。

目录设置支持的键是 download.default_directory 和 savefile.default_directory。下面的 Windows 配置片段分别设置这两个值：

{
  "internal": {
    "profile_prefs": {
      "download.default_directory": "C:\\SDK\\downloads\\instance-01",
      "savefile.default_directory": "C:\\SDK\\downloads\\instance-01"
    }
  }
}

如果需要签名，应先合并完整配置，再获取已签名文件。使用符合运行机器操作系统的绝对路径；相对路径和包含 .. 的路径会被拒绝。如果下载前就需要目录存在，请由启动器创建。

建议像示例一样使用专用子目录。首次设置时，如果选择的路径恰好是桌面目录，或在 Linux 上恰好是用户主目录，浏览器可能改用默认下载目录。它们的子目录不受这一精确路径例外影响。请通过一次测试下载核对实际位置。

这些目录设置在启动时生效，并保存在档案中。它们不会锁定设置界面，不会关闭下载询问，也不会在删除 Extended Preferences 配置项后自动恢复原值。不支持的键会被跳过并记录日志。两个目录值不会自动互相同步。

配置启动页面

internal.profile_prefs 也支持整数键 session.restore_on_startup：1 表示继续浏览上次打开的网页，5 表示打开新标签页。其他值和类型会被拒绝。

{
  "internal": {
    "profile_prefs": {
      "session.restore_on_startup": 1
    }
  }
}

此设置在启动时生效，并保存在档案中。它不会锁定设置界面，也不会在删除该配置项后自动恢复原值。显式传入的启动网址和启动参数仍遵循 Chromium 的启动逻辑。

签名验证能力的独立说明见 Extended Preferences 签名验证。其他内核配置项见完整能力索引。