排查 Chrome 源试用问题

解决与元标记、标头和脚本中的试用令牌有关的常见问题。

核对清单

如需排查源试用问题,请使用提供的链接解决以下各个问题。

试试看!

以下演示展示了提供来源试用令牌和访问试用功能的每种方式:

使用 Chrome 开发者工具检查令牌

从 Chrome 93 开始,DevTools 会在“应用”面板中为所选帧提供源试用信息。

Chrome DevTools 的“Application”面板中的源试用信息。

展开顶部帧,以检查可用于子帧的源试用令牌。例如,对于 ot-iframe.glitch.me 中的演示页面,您可以看到 iframe 中的页面提供了令牌。

Chrome DevTools 
  “Application”面板,显示 iframe 中网页的源试用令牌。

  • 令牌状态:网页是否具有有效的令牌。请注意,对于某些来源试用,可能存在其他因素(例如地理限制),导致即使存在有效令牌,来源试用功能也不可用。Chrome DevTools 状态代码介绍了来源试验的每个代码的含义。
  • 来源:为令牌注册的网络来源
  • Expiry Time:令牌可能的最长(最新)过期日期/时间,通常与试验结束时间一致。这与我的注册中显示的令牌有效期截止日期不同,后者显示的是令牌的当前有效期,并且可以延长
  • 使用限制:使用限制,可针对某些试用设置
  • 第三方:是否为令牌启用了第三方匹配。此功能适用于某些来源试用,在这种情况下,需要通过第三方脚本在多个网站上访问试用功能。
  • 匹配子网域:是否为令牌启用了子网域匹配。这样一来,您就可以在来源的多个子网域上测试来源试用功能,而无需为每个子网域使用不同的令牌。

如果当前用户无法使用试用版、令牌已过期或存在其他限制,Chrome DevTools 会在试用版名称旁边显示警告。

Chrome DevTools 的“Application”面板中显示源试用信息

Chrome DevTools 状态代码

  • 已过期:令牌已过期。您需要续订令牌,以生成具有新到期日期的新令牌。
    源代码

  • FeatureDisabled:试用版目前已停用。
    源代码

  • FeatureDisabledForUser:系统已通过替代使用限制将此令牌指定为当前用户停用。请参阅设计文档的“用户子集排除”部分。
    源代码 1
    源代码 2

  • 不安全:请求来源不安全,且不安全来源不支持试用。如源试用令牌验证程序代码中所述:“对于第三方令牌,当前源和脚本源都必须是安全的。由于子网域匹配,令牌来源可能与所提供的某个脚本来源不完全匹配,并且结果不会指明匹配的是哪个具体来源。这意味着,系统不会直接查找相应的脚本来源。为避免重新执行所有源代码比较,我们提供了一些快捷方式,具体取决于提供的脚本来源数量。必须至少有一个,否则第三方令牌将无法成功验证。”
    源代码

  • InvalidSignature:令牌的签名无效或格式有误。
    源代码

  • 格式错误:令牌格式错误,无法解析。
    源代码

  • NotSupported:Chromium“嵌入程序”(Chrome 或 Edge 等浏览器、WebView 或某些其他用户代理)不支持由令牌定义的来源试用。
    源代码

  • 成功:令牌格式正确、未过期、与来源试用功能匹配,并且是从预期来源发出的请求。
    源代码

  • TokenDisabled:令牌已被标记为已停用,无法使用。
    源代码

  • TrialNotAllowed当前用户无法使用来源试用
    源代码

  • UnknownTrial:该令牌指定的功能名称与任何已知的试用版都不匹配。
    源代码

  • WrongOrigin:请求来源与令牌中指定的来源不匹配。这可能包括方案、主机名或端口。如果第三方令牌是在 HTTP 标头、元标记或内嵌脚本(而非外部 JavaScript 文件)中提供的,系统也会显示此状态。
    源代码

  • WrongVersion:令牌版本有误:目前仅支持令牌版本 2 和 3。
    源代码


不起作用!🤔

如果您的源试用未按预期运行,请确保您已满足以下条件。

您是在 Chrome 中进行测试,而不是在 Chromium 或其他浏览器中进行测试

Chrome 源试用版专为 Chrome 用户设计。请勿依赖 Chrome 源试用令牌在其他浏览器(包括 Chromium 和其他基于 Chromium 的浏览器)中启用试用功能。这是因为 Chrome 源试用仅适用于在 Chrome 中提供以供实验的功能。

起源试用版也适用于 FirefoxMicrosoft Edge。在 Firefox 或 Edge 源试用中注册不会在 Chrome 中启用此功能。

已针对访问您网站的 Chrome 版本启用源试用

只有特定版本的 Chrome 用户才能试用。在某些情况下,这可能意味着试用功能仅适用于 Chrome 的非稳定版渠道:Canary 版、开发者版和 Beta 版。

您可以在试用版注册页面查看版本可用性:

突出显示 Chrome 适用性的 First-Party Sets 和 SameParty 的 Chrome 源试用页面

您可以前往 chrome://version 查看自己使用的 Chrome 版本。

Chrome 设置不会停用源试用

如果个别用户报告某项功能无法正常运行,请检查该功能在用户的 Chrome 设置中是否已停用。例如,您可以在 chrome://settings/privacySandbox 页面中停用 Privacy Sandbox 功能。

关键字和语法正确

请务必为来源试用令牌使用适当的关键字和语法。

对于第一方使用,可以在 origin-trial 元标记中提供令牌:

<meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">

或者,您也可以在 Origin-Trial 响应标头中提供令牌。下面是一个在 Node.js 中使用 Express 的示例:

app.use(function(req, res, next) {
  res.setHeader('Origin-Trial', 'Aj4DysCv3VjknU3...')
  next();
});

您还可以使用 JavaScript 提供令牌:

function addTrialToken(tokenContents) {
  const tokenElement = document.createElement('meta');
  tokenElement.httpEquiv = 'origin-trial';
  tokenElement.content = tokenContents;
  document.head.appendChild(tokenElement);
}

第一方令牌来源与网页来源匹配

确保在注册试用时选择的 Web Origin 值与具有可提供令牌的元标记或标头的网页的来源一致。

例如,如果您选择 https://example.com 作为网站来源

Chrome 源试用页面,其中显示了已选择 https://example.com 作为 Web 源。

您可能会获得如下所示的令牌值:

显示令牌值的 Chrome 源代码试用页面。

请检查此值是否与您要排查问题的页面中使用的令牌一致。

对于元标记中提供的令牌,请检查 HTML:

  <meta http-equiv="origin-trial" content="Aj4DysCv3VjknU3...">

对于标头中提供的令牌,您可以在 Chrome DevTools Network 面板Response Headers 下查看令牌值:

显示源试用响应标头的 Chrome DevTools Network 面板。

第一方令牌由使用它的来源提供

如需为从您的来源提供的网页中包含的代码启用来源试用功能,请在元标记、标头中提供试用令牌,或通过来自同一来源的 JavaScript 提供试用令牌。

为令牌注册的来源必须与提供令牌的来源一致。

第三方令牌来源与脚本来源匹配

您可以注册参与针对在其他来源注入的脚本的源试用。

例如,如果您希望通过 javascript-library.example 提供的脚本参与源试用,则需要向 javascript-library.example 的第三方匹配注册一个令牌。

Chrome 源试用注册页面,其中显示了已选择第三方匹配的选项。

第三方令牌的来源值必须与注入该令牌的脚本的来源一致。

第三方脚本使用第三方令牌

仅仅为来源(而非脚本)注册令牌,并不能让第三方脚本在您的网站上参与来源试用。

第三方脚本需要使用启用了第三方匹配的令牌,并使用类似以下代码通过脚本本身(而非网站上的元标记或标头)注入:

function addTrialToken(tokenContents) {
  const tokenElement = document.createElement('meta');
  tokenElement.httpEquiv = 'origin-trial';
  tokenElement.content = tokenContents;
  document.head.appendChild(tokenElement);
}

第三方令牌是通过外部脚本(而非元标记、HTTP 标头或内嵌脚本)提供的

系统会根据注入第三方令牌的脚本的来源对这些令牌进行验证,但静态标记中的内嵌脚本和 <meta> 标记没有来源(即来源网址)。

这意味着,第三方令牌必须通过外部脚本提供,而不是在 <meta> 标记或内嵌脚本中提供。无论注入令牌的外部脚本来自包含网页的来源还是其他来源,只要脚本的来源与为试用注册的来源匹配,就没有关系。

您可以访问 ot-iframe-3p.glitch.me 查看此演示。

用于提供试用令牌的方法支持源试用功能访问

若要访问某些类型的源试用功能,您需要以特定方式提供试用令牌。例如,若要为服务工作器和共享工作器启用来源试用权限,唯一的方法是在 Origin-Trial 标头中提供令牌。

已为子网域上使用的令牌启用子网域匹配

如果某个来源测试功能似乎不适用于您网站上的某些网页,请检查是否已为投放这些网页的子网域正确设置了令牌。

在注册参与源试用时,您可以选择匹配源站的所有子网域:

显示已选择子网域匹配的 Chrome 源试用注册页面

您还可以为第三方令牌匹配子网域:

Chrome 源试用注册页面,其中显示了已选择的第三方匹配和子网域匹配

系统不会为公共后缀列表中的来源颁发子网域令牌。例如,您无法注册 https://appspot.com 或 https://github.io 等来源,但可以注册该来源下的域名,例如 https://example.appspot.com 或 https://example.github.io。

令牌仍有效

令牌的有效期为六周。此外,您必须提交反馈,才能延长有效期。面向 Web 开发者的源代码试用指南介绍了如何确保您的令牌在整个源代码试用期间有效。

您可以在 Chrome 源试用版的“我的注册”页面上查看有效令牌:

Chrome 源代码试用版
“我的注册”页面,其中显示了“有效期截止日期”

如果令牌仍有效,Chrome DevTools 会显示状态 Success

Chrome DevTools 的“Application”面板中的源试用信息,其中突出显示了“Status: Success”。

如果令牌已过期,开发者工具会显示状态 Expired,并且您的“My Registrations”页面会显示 Expired Tokens 部分。

Chrome 源试用
“我的注册”页面,其中显示了过期的令牌。

来源试用期尚未结束

您可以通过其注册页面查看来源试用期的结束日期:

突出显示“试用版已推出”详细信息的 Chrome 源试用页面,其中显示了 First-Party Sets 和 SameParty。

对于已结束的试用,DevTools 会显示如下内容:

Chrome DevTools 的“Application”面板中显示“ValidTokenNotProvided”和“Status Expired”的源试用信息

当需要反馈或令牌即将过期时,系统会自动向您发送电子邮件,但不会在试用期结束时发送。

当前用户可以使用来源试用版

某些用户无法使用某些来源试用版,即使提供有效的令牌也是如此。

如果当前用户无法进行试用,Chrome 开发者工具会显示 TrialNotAllowed 警告:

Chrome DevTools 的“Application”面板中显示 TrialNotAllowed 警告的源试用信息。

我们会为每个来源试用提供有关使用限制和适用范围的信息。

与任何 Web 平台功能一样,您应先使用功能检测来确认是否支持来源试用功能,然后再使用该功能。

未超出来源试用用量限制

默认情况下,如果网页具有有效的试用令牌,则该网页上的来源试用功能将处于启用状态。

不过,除极少数情况外,源试用用量最多仅占所有 Chrome 网页加载量的 0.5%。如果所有 Chrome 用户的总使用量超过该数量,系统会停用来源试用功能。 开发者工具将显示令牌状态为“已停用”。

废弃功能试用没有使用限制,因为这些试用不会引入新功能,因此不会造成大量网站依赖于试用功能。

某些试用还提供了限制使用情况的选项,这意味着系统会为部分用户停用初始试用功能。您可以在提供此选项的来源试用版的注册页面上找到此选项:

显示使用限制的 Chrome 初始试用注册页面。

如果您发现用户对某个来源试用功能的访问量低于预期,请确保已选择“标准限制”。

iframe 会提供自己的令牌

如需允许访问来源试用功能,iframe 必须在元标记、HTTP 标头或程序化方式中提供令牌。iframe 不会继承对包含它们的网页启用的功能的访问权限。

ot-iframe.glitch.me 演示了如何从 iframe 访问源试用功能。ot-iframe-3p.glitch.me 提供了多个跨源 iframe 示例。

权限政策配置正确

部分来源测试功能可能会受到 Permissions-Policy 标头(以前称为 Feature-Policy 标头)的影响。您可以在试用功能的实验意向中查看此信息,也可以在 web.devdeveloper.chrome.com/blog 上查看该功能的开发者文档。

确保您尝试访问的功能未被 Permissions-Policy 指令屏蔽。您可以在 Chrome DevTools 的 Network 面板中查看响应标头,并在“Application”面板中查看允许的功能的完整列表。

Chrome DevTools 的 Application 面板,其中显示了权限政策允许的功能。

那么工作器呢?

您可以将源试用功能提供给服务工作器、共享工作器和专用工作器。但是,为 Service Worker 和共享 Worker 启用访问权限的唯一方法是在 Origin-Trial 标头中提供令牌。

专用 Worker 会继承其父级文档启用的功能的访问权限。

在访问功能之前提供令牌

请务必在访问试用功能之前提供来源试用令牌。例如,如果某个网页通过 JavaScript 提供令牌,请确保用于提供令牌的代码在尝试访问试用功能的代码之前运行。

源试用演示

了解详情