Chromium Settings 自启动开关：三种 pref 同步方案深度对比

Chromium Settings 自启动开关：三种 pref 同步方案深度对比

在浏览器设置页实现「开机自启动」时，一个看似简单的问题——开关状态重进页面后恢复默认关闭——背后其实是两套完全不同的数据通道在打架。本文从机制层面对比三种实现，并给出推荐做法。

---

背景：我们要解决什么

需求可以拆成两件事：

职责	说明
写/读 pref	browser.autostart ↔ PrefService ↔ config.ini
装服务	用户开启时触发 srv.exe /install

HTML 侧已经用了标准绑定：

<settings-toggle-button
    pref="{{prefs.browser.autostart}}"
    label="开机自启动"
    on-settings-boolean-control-change="onAutostartChange_">
</settings-toggle-button>

问题出在：pref 从哪来、往哪写——选错了通道，就会出现「磁盘上有值，UI 却显示关」。

---

Chromium Settings 的标准 pref 闭环

在讨论三种方案前，先看清 Settings 页的设计约定。

渲染错误: Mermaid 渲染失败: Parse error on line 9: ...lPrefs() API->>C++: 遍历 allowlist ----------------------^ Expecting 'NEWLINE', ',', '()', 'SOLID_OPEN_ARROW', 'DOTTED_OPEN_ARROW', 'SOLID_ARROW', 'SOLID_ARROW_TOP', 'SOLID_ARROW_BOTTOM', 'STICK_ARROW_TOP', 'STICK_ARROW_BOTTOM', 'SOLID_ARROW_TOP_DOTTED', 'SOLID_ARROW_BOTTOM_DOTTED', 'STICK_ARROW_TOP_DOTTED', 'STICK_ARROW_BOTTOM_DOTTED', 'SOLID_ARROW_TOP_REVERSE', 'SOLID_ARROW_BOTTOM_REVERSE', 'STICK_ARROW_TOP_REVERSE', 'STICK_ARROW_BOTTOM_REVERSE', 'SOLID_ARROW_TOP_REVERSE_DOTTED', 'SOLID_ARROW_BOTTOM_REVERSE_DOTTED', 'STICK_ARROW_TOP_REVERSE_DOTTED', 'STICK_ARROW_BOTTOM_REVERSE_DOTTED', 'BIDIRECTIONAL_SOLID_ARROW', 'DOTTED_ARROW', 'BIDIRECTIONAL_DOTTED_ARROW', 'SOLID_CROSS', 'DOTTED_CROSS', 'SOLID_POINT', 'DOTTED_POINT', 'TXT', got '+'

读（页面初始化）

// chrome/browser/resources/settings_shared/prefs/prefs.ts
this.settingsApi_.getAllPrefs().then((prefs) => {
  this.updatePrefs_(prefs);
  CrSettingsPrefs.setInitialized();
});

写（用户操作）

// chrome/browser/resources/settings_shared/controls/settings_boolean_control_mixin.ts
notifyChangedByUserInteraction() {
  this.dispatchEvent(new CustomEvent('settings-boolean-control-change', ...));
  if (!this.pref || this.noSetPref) {
    return;
  }
  this.sendPrefChange();
}

// prefs.ts
this.settingsApi_.setPref(key, prefObj.value, /* pageId */ '');

门禁：allowlist

// chrome/browser/extensions/api/settings_private/prefs_util.cc
std::optional<settings_api::PrefObject> PrefsUtil::GetPref(
    const std::string& name) {
  if (GetAllowlistedPrefType(name) == settings_api::PrefType::kNone) {
    return std::nullopt;
  }
  // ...
}

不在 allowlist 里的 pref，前端根本读不到、也写不进去——这是许多 bug 的根因。

---

方案一：allowlist + pref 绑定（推荐）

思路

完全走 Settings 标准链路：加 allowlist，让 getAllPrefs / setPref 能操作 browser.autostart；WebUI message 只管装服务。

代码形态

C++：加入 allowlist

#ifdef USE_HACK
  // browser autostart
  (*s_allowlist)[::prefs::kAutoStart] =
      settings_api::PrefType::kBoolean;
#endif

前端：开关变更只触发装服务（开启时）

// chrome/browser/resources/settings/basic_page/basic_page.ts
private onAutostartChange_(event: Event) {
  const target = event.target as HTMLElement&{checked?: boolean};
  if (!target.checked) {
    return;
  }
  chrome.send('checkAndInstallService', [true]);
}

C++：handler 不再写 pref

// chrome/browser/ui/webui/settings/settings_startup_pages_handler.cc
void StartupPagesHandler::HandleCheckAndInstallService(
    const base::Value::List& args) {
  CHECK_EQ(1U, args.size());
  if (!args[0].GetBool()) {
    return;
  }
  base::ThreadPool::PostTask(
      FROM_HERE,
      {base::MayBlock(), base::TaskPriority::BEST_EFFORT,
       base::TaskShutdownBehavior::BLOCK_SHUTDOWN},
      base::BindOnce(&CheckAndInstallServiceOnFileThread));
}

数据流

读：getAllPrefs → prefs.browser.autostart → 开关显示
写：sendPrefChange → setPref → PrefService → SeProfile → config.ini
副作用：chrome.send → 装 服务（仅开启）

优点

• 与 Settings 里其它开关（书签栏、拼写检查等）完全一致
• 读写同一通道，重进页面自然正确
• onPrefsChanged 自动同步外部变更（策略、同步等）
• handler 职责单一，易维护

缺点

• 必须记得加 allowlist（漏了就会复现「显示关」）
• 需要理解 settingsPrivate 机制，不能只写 C++ handler

---

方案二：allowlist + 进页显式 getPref（冗余加固）

思路

在方案一基础上，进入 /onStartup 路由时再手动拉一次 pref：

const AUTO_START_PREF = 'browser.autostart';

private refreshAutostartPrefIfNeeded_() {
  if (!routes.ON_STARTUP || this.currentRoute_ !== routes.ON_STARTUP) {
    return;
  }
  CrSettingsPrefs.initialized.then(() => {
    return chrome.settingsPrivate.getPref(AUTO_START_PREF);
  }).then((pref: chrome.settingsPrivate.PrefObject) => {
    if (!pref || !this.prefs) {
      return;
    }
    this.set('prefs.browser.autostart', pref);
  });
}

// connectedCallback / currentRouteChanged 中调用

与方案一的对比

	方案一	方案二
页面加载读 pref	getAllPrefs 一次	getAllPrefs + 进路由 getPref
代码量	少	多
与同类开关一致性	高	低（特殊处理）
修 bug 必要性	足够	通常不必要

何时可能有用

• dom-if restamp 与 pref 初始化存在极端竞态（实测少见）
• 直链 chrome://settings/onStartup 且怀疑 binding 未更新

结论

方案二是方案一的子集 + 防御代码。若方案一实测通过，建议删除 refreshAutostartPrefIfNeeded_，避免维护两套「读」逻辑。

---

方案三：WebUI handler 直写 SetBoolean（不推荐）

思路

用户点开关 → chrome.send → C++ 直接 prefs->SetBoolean，不依赖 settingsPrivate。

代码形态（问题版本）

前端

private onAutostartChange_(event: Event) {
  const target = event.target as HTMLElement&{checked?: boolean};
  chrome.send('checkAndInstallService', [!!target.checked]);
}

C++

void StartupPagesHandler::HandleCheckAndInstallService(
    const base::Value::List& args) {
  CHECK_EQ(1U, args.size());
  bool enabled = args[0].GetBool();

  PrefService* prefs = Profile::FromWebUI(web_ui())->GetPrefs();
  prefs->SetBoolean(prefs::kAutoStart, enabled);  // 只写，不读

  if (enabled) {
    base::ThreadPool::PostTask(..., CheckAndInstallServiceOnFileThread);
  }
}

为什么「写了 pref，UI 还是关」

┌──────────────────────────────────────────────┐
│  UI 读通道（pref 绑定）                        │
│  prefs.browser.autostart                │
│       ↑ getAllPrefs（需 allowlist）           │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  WebUI 写通道（旁路）                          │
│  chrome.send → SetBoolean(kAutoStart)        │
│       ↓ 写入 PrefService ✓                    │
│       ✗ 不更新 prefs 对象                      │
│       ✗ 无 getPref 回流                       │
└──────────────────────────────────────────────┘

allowlist 未加时：

1. getAllPrefs 不含 browser.autostart
2. prefs.browser.autostart 为 undefined
3. resetToPrefValue() 走默认分支 → checked = false
4. 用户看到永远关，尽管 PrefService 里可能是 true

allowlist 加了之后，方案三还会出现：

• 双写：sendPrefChange 和 handler 都在写 pref
• 职责混乱：同一个 message 既写 pref 又装服务
• 无标准同步：外部改 pref 时，除非另写监听，UI 不更新

若坚持用 WebUI 写，要补多少活？

至少要再造「读」通道之一：

// 需要新增
void HandleGetAutostartPref(const base::Value::List& args) {
  bool value = Profile::FromWebUI(web_ui())->GetPrefs()
                   ->GetBoolean(prefs::kAutoStart);
  // ResolveJavascriptCallback...
}

或前端：

chrome.settingsPrivate.getPref('browser.autostart'); // 仍要 allowlist

等于重造 settingsPrivate，不如直接用方案一。

---

三方案总览

维度	① allowlist + 绑定	② + 进页 getPref	③ WebUI SetBoolean
读 pref	getAllPrefs	getAllPrefs + getPref	无（需另造）
写 pref	setPref	setPref	C++ SetBoolean
重进页面状态	✅	✅	❌（无 allowlist 时）
与 Settings 惯例	✅	△ 多特殊逻辑	❌
装服务	独立 chrome.send	独立 chrome.send	混在同一 handler
推荐度	⭐⭐⭐	⭐⭐	❌

---

推荐架构（最终形态）

最小必要改动：

1. prefs_util.cc 加 kAutoStart allowlist
2. handler 去掉 SetBoolean，只装服务
3. HTML 保持 pref="{{prefs.browser.autostart}}"

不必做：

• 进页 getPref（除非实测有边界 case）
• handler 里写 pref

---

给 Code Review 的一句话

Settings 页的 pref 读写必须走 settingsPrivate + allowlist 闭环；WebUI message 适合命令式副作用（装服务），不适合替代 pref 的 CRUD。之前「设完重进仍显示关」，不是缺一段前端获取逻辑，而是 allowlist 未开导致读通道断路；C++ SetBoolean 写的是另一条线，和 UI 的 prefs 模型无关。

---

验证清单

1. 开开关 → browser.autostart = true，config.ini autostart_browser=1
2. 关设置页再开 → 开关仍为开（方案一即可验证）
3. 关开关 → pref false，config.ini 0
4. 控制台 chrome.settingsPrivate.getPref('browser.autostart') 有返回值
5. 开启时日志出现 LaunchServiceInstall（服务通道独立工作）

---

相关文件

文件	作用
chrome/browser/extensions/api/settings_private/prefs_util.cc	allowlist
chrome/browser/resources/settings/basic_page/basic_page.html	开关 UI
chrome/browser/resources/settings/basic_page/basic_page.ts	装服务触发
chrome/browser/ui/webui/settings/settings_startup_pages_handler.cc	WebUI handler
chrome/browser/profile.cc	pref 监听 → config.ini
chrome/common/pref_names.cc	kAutoStart = browser.autostart

---

推荐：方案一。 它改动最小、机制最正、和 Chromium Settings 生态一致；方案二是可选加固；方案三应作为反例避免回归。