Web APIs 怎样排查权限策略阻止的功能

页面调用摄像头、定位、全屏或其他 Web API 时，如果控制台提示权限策略阻止了功能，先不要急着把用户授权弹窗当成根因。Permissions Policy 是一层独立的浏览器能力边界：响应头先决定文档可以向哪些来源委派能力，嵌入式页面的 iframe allow 再做进一步收窄，最后才轮到浏览器权限和 API 自身条件。

官方参考地址：https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy

先区分权限策略与用户授权

排查时先把“被策略阻止”和“用户拒绝授权”分成两类。比如定位 API 返回 PERMISSION_DENIED，可能是用户不允许，也可能是文档根本没有得到 geolocation 能力；摄像头则还会受到安全上下文、设备占用和浏览器设置影响。

建议先记下四个现场信息：调用的 API 名称、页面的 origin、页面是否嵌套在 iframe 中、Console 中是否出现 Permissions Policy 或 policy-controlled feature 字样。只看业务层的“权限失败”提示，通常无法判断是哪一层拒绝。

检查响应头和 iframe allow 的叠加关系

在 Network 面板选中主文档，查看 Response Headers 中的 Permissions-Policy。例如只允许本站和地图子域使用定位，可以这样表达：

Permissions-Policy: geolocation=(self "https://maps.example.com")


// 这里的响应头给出可委派来源上限，allow 只对当前 iframe 再做收窄。

两个地方必须同时满足：响应头的 allowlist 覆盖 iframe 真正加载的来源，iframe 的 allow 也要授予对应功能。如果子文档之后跳转到另一个来源，还要在 allow 中明确列出那个来源；仅写当前的 src 不代表任意后续来源都能继承。

反过来，父文档若用 geolocation=() 关闭了能力，子 iframe 不能靠 allow="geolocation *" 重新打开。修复时应先改父级上限，再把子文档配置收窄到实际需要的来源，避免直接使用过宽的通配符。

用文档检查和 Report-Only 定位是哪一层拒绝

如果页面没有 iframe，重点看主文档的响应头；如果有 iframe，先在 Elements 中确认最终 DOM 的 src 和 allow，再对照 Network 中实际响应的 origin。脚本检查可以帮助记录策略状态，但它不是用户授权结果：

const feature = "geolocation";
const policy = document.permissionsPolicy;

// 只检查当前文档的策略状态，不代表用户已经授权。
const allowed = policy?.allowsFeature(feature) ?? false;
console.log({ feature, policyAllowed: allowed, origin: location.origin });

// 真正调用时仍需处理用户拒绝、超时和浏览器环境限制。
navigator.geolocation.getCurrentPosition(
  position => console.log(position.coords.latitude, position.coords.longitude),
  error => console.warn("定位调用失败：", error)
);

为了观察而不改变线上行为，可以临时使用 Permissions-Policy-Report-Only，让浏览器报告可能的违规，再结合服务端报告端点或开发者工具中的线索缩小范围。确认规则后，再把同一条指令放入真正的 Permissions-Policy 响应头。

按层修复后再复查浏览器条件

修复完成后要完整刷新主文档和 iframe，避免只改了子页面却仍使用旧的父响应头。随后按这个顺序复查：策略是否允许、iframe 是否继承到能力、页面是否满足 HTTPS 等安全上下文要求、用户是否已授权、API 是否还要求瞬时用户激活或设备可用。

常见误区是把 allow="camera; microphone" 当成“强制授权”，或者只修改 iframe 而忽略 CDN、反向代理注入的响应头。生产环境应让服务端响应头成为清晰的能力上限，iframe 只声明必要来源；当跨域嵌入链路变复杂时，优先保留最小复现页面和每层响应头记录。

常见问题

Permissions-Policy 能替代浏览器权限弹窗吗？

不能。它只决定文档是否有资格使用某项能力，浏览器仍会单独处理用户授权、设备状态和调用时机。

父页面允许了，iframe 为什么仍然失败？

检查 iframe 的 allow、实际加载 origin 和跳转后的 origin。子文档配置比父级更窄，或来源没有被列入时，仍会被阻止。

应该直接把 allowlist 写成星号吗？

排障阶段可以用最小复现确认是否为策略问题，正式配置不应默认放大范围，应只列出实际需要的来源并保留复查记录。