Permissions-Policy 头

实验性： 这是一项实验性技术
在生产中使用此技术之前，请仔细检查浏览器兼容性表格。

HTTP Permissions-Policy 响应头提供了一种机制，用于允许和拒绝在文档或文档中的任何 <iframe> 元素中使用浏览器功能。

有关更多信息，请参阅主要权限策略文章。

头类型	响应头
禁止请求头	是

语法

http

Permissions-Policy: <directive>=<allowlist>

<directive>

要应用 allowlist 的权限策略指令。请参阅下面的指令，了解允许的指令名称列表。

<allowlist>

允许列表是一个源列表，它包含以下一个或多个用括号括起来的值，并用空格分隔

* (通配符): 此功能将在当前文档和所有嵌套的浏览上下文（<iframe>）中被允许，无论其来源如何。
() (空允许列表): 此功能在顶级和嵌套浏览上下文中被禁用。对于 <iframe> 的 allow 属性，其等效值为 'none'。
self: 此功能将在此文档和所有同源的嵌套浏览上下文（<iframe>）中被允许。此功能不允许在嵌套浏览上下文中的跨源文档中使用。self 可视为 https://your-site.example.com 的简写。对于 <iframe> 的 allow 属性，其等效值为 self。
src: 此功能将在该 <iframe> 中被允许，只要加载到其中的文档源自其 src 属性中的 URL 的相同源。此值仅在 <iframe> 的 allow 属性中使用，并且是 <iframe> 中 allowlist 的默认值。
"<origin>": 特定来源（例如，"https://a.example.com"）允许使用该功能。来源应以空格分隔。请注意，<iframe> 允许属性中的来源不带引号。

值 * 和 () 只能单独使用，而 self 和 src 可以与一个或多个来源组合使用。

注意：指令有一个默认的允许列表，对于 Permissions-Policy HTTP 头，它始终是 *、self 或 none 之一，并控制如果未在策略中明确列出时的默认行为。这些在各个指令参考页面中指定。对于 <iframe> 的 allow 属性，默认行为始终是 src。

在支持的情况下，你可以在权限策略源中包含通配符。这意味着，你无需在允许列表中显式指定几个不同的子域，而是可以通过一个带有通配符的源来指定它们。

所以，不是

http

("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

你可以指定

http

("https://example.com" "https://*.example.com")

注意： "https://*.example.com" 不匹配 "https://example.com"。

指令

accelerometer 实验性: 控制当前文档是否允许通过 Accelerometer 接口收集设备加速度信息。
ambient-light-sensor 实验性: 控制当前文档是否允许通过 AmbientLightSensor 接口收集设备周围环境光照信息。
aria-notify 实验性非标准: 控制当前文档是否允许使用 ariaNotify() 方法触发屏幕阅读器公告。
attribution-reporting 实验性: 控制当前文档是否允许使用 Attribution Reporting API。
autoplay 实验性: 控制当前文档是否允许通过 HTMLMediaElement 接口请求自动播放媒体。当此策略被禁用且没有用户手势时，HTMLMediaElement.play() 返回的 Promise 将以 NotAllowedError DOMException 拒绝。 <audio> 和 <video> 元素上的 autoplay 属性将被忽略。
bluetooth 实验性: 控制是否允许使用 Web 蓝牙 API。当此策略被禁用时，Navigator.bluetooth 返回的 Bluetooth 对象的方法将返回 false 或以 SecurityError DOMException 拒绝返回的 Promise。
browsing-topics 实验性非标准: 控制对 Topics API 的访问。如果策略明确禁止使用 Topics API，则任何调用 Document.browsingTopics() 方法或发送带有 Sec-Browsing-Topics 头的请求都将以 NotAllowedError DOMException 失败。
camera 实验性: 控制当前文档是否允许使用视频输入设备。如果未允许权限，则 getUserMedia() 返回的 Promise 将以 NotAllowedError DOMException 拒绝。
captured-surface-control 实验性: 控制文档是否允许使用捕获表面控制 API。如果未允许权限，API 主要方法返回的 Promise 将以 NotAllowedError DOMException 拒绝。
compute-pressure 实验性: 控制对计算压力 API 的访问。
cross-origin-isolated 实验性: 控制当前文档是否可以被视为跨源隔离。
deferred-fetch 实验性: 控制顶级源的 fetchLater() 配额的分配。
deferred-fetch-minimal 实验性: 控制共享的跨源子帧 fetchLater() 配额的分配。
display-capture 实验性: 控制当前文档是否允许使用 getDisplayMedia() 方法捕获屏幕内容。当此策略被禁用时，如果未获得捕获显示内容权限，getDisplayMedia() 返回的 Promise 将以 NotAllowedError DOMException 拒绝。
encrypted-media 实验性: 控制当前文档是否允许使用加密媒体扩展 API (EME)。当此策略被禁用时，Navigator.requestMediaKeySystemAccess() 返回的 Promise 将以 SecurityError DOMException 拒绝。
fullscreen 实验性: 控制当前文档是否允许使用 Element.requestFullscreen()。当此策略被禁用时，返回的 Promise 将以 TypeError 拒绝。
gamepad 实验性: 控制当前文档是否允许使用游戏手柄 API。当此策略被禁用时，调用 Navigator.getGamepads() 将抛出 SecurityError DOMException，并且 gamepadconnected 和 gamepaddisconnected 事件将不会触发。
geolocation 实验性: 控制当前文档是否允许使用 Geolocation 接口。当此策略被禁用时，调用 getCurrentPosition() 和 watchPosition() 将导致这些函数的콜back函数以 PERMISSION_DENIED 的 GeolocationPositionError 错误码被调用。
gyroscope 实验性: 控制当前文档是否允许通过 Gyroscope 接口收集设备的姿态信息。
hid 实验性: 控制当前文档是否允许使用 WebHID API 连接到不常见或特殊的等人机接口设备，例如替代键盘或游戏手柄。
identity-credentials-get 实验性: 控制当前文档是否允许使用联邦凭证管理 API (FedCM)。
idle-detection 实验性: 控制当前文档是否允许使用空闲检测 API 来检测用户何时与他们的设备互动，例如在聊天应用程序中报告“在线”/“离开”状态。
language-detector 实验性: 控制对翻译器和语言检测器 API 的语言检测功能的访问。
local-fonts 实验性: 控制当前文档是否允许通过 Window.queryLocalFonts() 方法收集用户本地安装的字体数据（另请参阅本地字体访问 API）。
magnetometer 实验性: 控制当前文档是否允许通过 Magnetometer 接口收集设备的姿态信息。
microphone 实验性: 控制当前文档是否允许使用音频输入设备。当此策略被禁用时，MediaDevices.getUserMedia() 返回的 Promise 将以 NotAllowedError DOMException 拒绝。
midi 实验性: 控制当前文档是否允许使用 Web MIDI API。当此策略被禁用时，Navigator.requestMIDIAccess() 返回的 Promise 将以 SecurityError DOMException 拒绝。
on-device-speech-recognition 实验性: 控制对 Web Speech API 的设备上语音识别功能的访问。
otp-credentials 实验性: 控制当前文档是否允许使用 WebOTP API 从应用服务器发送的特殊格式短信中请求一次性密码 (OTP)，即通过 navigator.credentials.get({otp: ..., ...})。
payment 实验性: 控制当前文档是否允许使用支付请求 API。当此策略启用时，PaymentRequest() 构造函数将抛出 SecurityError DOMException。
picture-in-picture 实验性: 控制当前文档是否允许通过相应的 API 以画中画模式播放视频。
publickey-credentials-create 实验性: 控制当前文档是否允许使用 Web 身份验证 API 创建新的非对称密钥凭证，即通过 navigator.credentials.create({publicKey: ..., ...})。
publickey-credentials-get 实验性: 控制当前文档是否允许使用 Web 身份验证 API 检索已存储的公钥凭证，即通过 navigator.credentials.get({publicKey: ..., ...})。
screen-wake-lock 实验性: 控制当前文档是否允许使用屏幕唤醒锁定 API 来指示设备不应关闭或调暗屏幕。
serial 实验性: 控制当前文档是否允许使用 Web Serial API 与串行设备通信，无论是通过串行端口直接连接，还是通过 USB 或蓝牙设备模拟串行端口。
speaker-selection 实验性: 控制当前文档是否允许使用音频输出设备 API 列出并选择扬声器。
storage-access 实验性: 控制在第三方上下文（即嵌入在 <iframe> 中）加载的文档是否允许使用存储访问 API 请求访问未分区 cookie。
translator 实验性: 控制对翻译器和语言检测器 API 的翻译功能的访问。
summarizer 实验性: 控制对摘要器 API 的访问。
usb 实验性: 控制当前文档是否允许使用 WebUSB API。
web-share 实验性: 控制当前文档是否允许使用 Web Share API 的 Navigator.share() 方法将文本、链接、图像和其他内容共享到用户选择的任意目的地，例如移动应用程序。
window-management 实验性: 控制当前文档是否允许使用窗口管理 API 来管理多个显示器上的窗口。
xr-spatial-tracking 实验性: 控制当前文档是否允许使用 WebXR Device API 与 WebXR 会话交互。

示例

基本用法

Permissions-Policy 头

要允许所有来源访问地理位置，你可以这样做

http

Permissions-Policy: geolocation=*

或者，要允许访问部分来源，你可以这样做

http

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

可以通过发送带有逗号分隔的策略列表的头，或者为每个策略发送单独的头，同时控制多个功能。

例如，以下是等效的

http

Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=*

Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self https://example.com/)
Permissions-Policy: camera=*

iframe

要使 <iframe> 启用某个功能，其允许的来源也必须在父页面的允许列表中。由于这种继承行为，最好在 HTTP 头中指定对某个功能最广泛的可接受支持，然后在每个 <iframe> 中指定所需的子集支持。

要允许所有来源访问地理位置，你可以这样做

html

<iframe src="https://example.com" allow="geolocation *"></iframe>

要将策略应用于当前来源和其他来源，你可以这样做

html

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

这很重要：默认情况下，如果 <iframe> 导航到另一个来源，策略不会应用于 <iframe> 导航到的来源。通过在 allow 属性中列出 <iframe> 导航到的来源，应用于原始 <iframe> 的权限策略将应用于 <iframe> 导航到的来源。

可以通过在 allow 属性中包含以分号分隔的策略指令列表来同时控制多个功能。

html

<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

值得特别提一下 src 值。我们上面提到，使用此允许列表值意味着只要加载到此 <iframe> 中的文档源自其 src 属性中的 URL 的相同源，相关功能就将被允许。此值是 allow 中列出的功能的默认 allowlist 值，因此以下是等效的

html

<iframe src="https://example.com" allow="geolocation 'src'">
  <iframe src="https://example.com" allow="geolocation"></iframe
></iframe>

拒绝访问强大功能

SecureCorp Inc. 希望在其应用程序中禁用麦克风（例如 MediaDevices.getUserMedia()）和 Geolocation API。它可以使用以下响应头来实现：

http

Permissions-Policy: microphone=(), geolocation=()

通过为来源列表指定 ()，无论其来源如何，指定的功能将对所有浏览上下文（包括所有 <iframe>）禁用。

结合 HTTP 头和 `<iframe>` 策略

例如，假设我们希望在自己的源中启用地理位置使用，并在来自我们信任的广告网络的嵌入内容中启用。我们可以像这样设置页面范围的权限策略：

http

Permissions-Policy: geolocation=(self https://trusted-ad-network.com)

在我们的广告 <iframe> 中，我们可以这样设置对 https://trusted-ad-network.com 源的访问权限：

html

<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

如果不同的来源最终加载到 <iframe> 中，它将无法访问地理位置

html

<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

规范

规范
权限策略 # permissions-policy-http-header-field

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

本页面最后由 MDN 贡献者在 2025 年 9 月 30 日修改。

在 GitHub 上查看此页面 • 报告此内容问题