Topics API 目前无法在普通HTML页面中直接调用，仅Chrome 117+在启用实验标志、HTTPS安全上下文及Origin Trial注册后才可能通过document.topics()获取有限主题，且不跨浏览器兼容，不宜用于核心业务。
Topics API 目前（2024 年中）**无法在普通 HTML 页面中直接调用**，它不是前端 JavaScript 可自由访问的 Web API，而是 Chrome 浏览器在隐私沙盒框架下、由浏览器内核在导航时主动计算并注入的上下文信息，仅对满足特定条件的页面通过 document.topics() 暴露——且该函数目前仍为实验性功能，默认禁用，需手动开启实验标志并满足来源可信性要求。
为什么 document.topics() 在你的 HTML 里返回空或报错
常见现象：控制台执行 document.topics() 得到 undefined 或 Promise {<pending>}</pending> 后始终 resolve 为空数组；或直接抛出 TypeError: document.topics is not a function。
- Chrome 版本低于 117 ——
document.topics()从 v117 起才作为 Origin Trial 功能默认内置（但仍需启用） - 未启用实验开关：
chrome://flags/#privacy-sandbox-ads-apis必须设为 Enabled（不是 Default 或 Disabled） - 页面非安全上下文：必须通过
https://（本地http://localhost或http://127.0.0.1除外）提供服务 - 未加入 Origin Trial —— 即使 flag 开启，生产环境域名还需在 Origin Trials 注册并嵌入
<meta http-equiv="origin-trial" content="..."> - 用户已关闭“广告跟踪”或“个性化广告”系统级设置（
chrome://settings/adPrivacy）
如何在本地 HTML 中验证 Topics 是否可用
仅限开发调试，不适用于上线部署。目标是确认环境是否就绪，而非模拟真实行为。
- 用 Chrome v117+ 打开
http://localhost:8000/test.html（推荐用python3 -m http.server 8000启动） - 确保已打开
chrome://flags/#privacy-sandbox-ads-apis并重启浏览器 - 在 HTML 中写一段最小验证代码：
<script>
if ('topics' in document) {
document.topics().then(console.log).catch(console.error);
} else {
console.log('document.topics not available');
}
</script>
若输出类似 [{topic: "Auto Repair", domain: "example.com", version: "1"}]，说明基础链路通了；若为空数组，大概率是用户未开启个性化广告或当前网站无足够浏览历史生成 Topics。
立即学习“前端免费学习笔记（深入）”；
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
Topics API 不是“兴趣标签获取接口”，它的设计约束远超表面
它不返回用户长期画像，也不支持按需查询任意主题。所有结果都受三重限制：
- 时间窗口：只基于过去 3 周内、用户在至少 2 个不同网站上访问过的、符合分类标准的页面生成
- 去噪与泛化：原始分类（如 “Honda Civic maintenance”）会被映射到顶层宽泛 Topic（如 “Auto Repair”），且每帧最多返回 3 个 Topic，每周轮换一次
-
不可控性：开发者无法指定要哪些 Topic，也无法触发重新计算；
document.topics()返回的是浏览器“认为可安全共享”的快照，不是数据库查询
所以，不要把它当 getUserInterests() 用。它适合做轻量级内容适配（比如把“Sports” Topic 映射为首页推荐体育栏目），但绝不适合用于精准定向广告或用户分群。
上线前必须检查的兼容性陷阱
即使你成功在本地拿到 Topics，上线后大概率失效：
-
document.topics()在 Safari、Firefox、Edge（非 Chromium 内核）中完全不存在 —— 它是 Chrome 独占的隐私沙盒实验特性 - Android WebView 和 iOS WKWebView 均不支持，任何混合 App 内嵌页都无法使用
- 若用户安装了 uBlock Origin、Privacy Badger 等扩展，可能拦截 Topics 请求或清空相关存储，导致返回空
- Chrome 正在推进 Topics 的替代方案（如
Protected Audience API），Topics API 本身已在逐步弱化，2024 年底可能被标记为 deprecated
真正关键的不是“怎么调用”，而是“是否值得依赖”——目前它只适合灰度验证和小范围 A/B 测试，任何核心业务逻辑都不应建立在其返回值之上。
