根据 Microsoft Edge 中新的本地网络访问限制调整网站

上次更新时间：2026 年 3 月 9 日

默认情况下，本地网络访问限制将在 Microsoft Edge 143 中开始交付。 有关什么是本地网络访问以及要求用户权限发出本地网络请求的动机的更多背景信息，请参阅 本地网络访问规范。

如果你有一个网站需要连接到运行 localhost 的服务器或用户本地网络上的某个位置， (可能通过第三方库) ，本文档将尝试回答常见问题，并提供有关如何使网站适应这些新限制的指导。

在许多情况下，本地网络请求应像以前一样继续工作，但用户在站点上第一次出现时会看到权限提示。 在某些情况下，你需要调整这些请求的网站，以继续 (工作，并且不会被阻止为混合内容) 。 例如，如果向解析为本地网络地址的公共域名发出提取 () 请求，则需要将提取 () 调用显式标记为转到本地地址。 或者，如果目前由于混合内容阻塞而必须在 HTTP (而不是 HTTPS) 上托管网站，则希望注册我们的 Origin 试用版 ，暂时免除网站请求 LNA 权限的 HTTPS 要求。

Microsoft Edge 中 LNA 限制的当前范围是什么？

当与本地网络或 localhost 上的目标建立连接时，将触发权限提示。 从 Microsoft Edge 143 开始，LNA 限制适用于：

• 子资源请求
• 提取 () 请求
• 导航子帧

LNA 限制最初不会应用于以下连接类型，但我们计划尽快包括这些限制：

• WebSockets
• WebTransport
• WebRTC

我们目前没有计划对主框架导航应用 LNA 限制。 (尽管 Edge 139 及更早版本中的草稿实现中的 bug 意外影响了主框架导航。)

我们目前没有计划对扩展应用 LNA 限制。 目前，允许具有必要 主机权限 的扩展发出本地网络请求。

LNA 限制不适用于 Android WebView。 嵌入发出本地网络请求的 WebView 的 Android 应用受 Android 的新 本地网络权限的约束。

如何为用户提供 LNA 权限提示的其他上下文？

请求权限时，最好在 Web 应用中为用户提供一些附加上下文，了解需要权限的原因及其用途。 权限 API 允许你查询用户是授予 (还是拒绝) 给定权限，从而相应地自定义 UI。

由于权限 API 的工作方式，查询本地网络访问权限的状态将返回“提示”，无论是否启用了 LNA 功能标志，如果用户未被授予或拒绝该权限。 功能标志在 Microsoft Edge 143 中默认启用，因此你可以根据用户代理字符串中的主版本调度不同的行为。

为了在触发 LNA 权限提示之前提供更多上下文，我们当前的指南是使用如下所示的模式：

• 如果客户端是 Edge < 143，则本地网络请求应以无提示方式工作
• 如果客户端为 Edge >= 143，则查询权限 API (请参阅以下示例调用)
  • 如果授予了权限，请继续请求尝试
  • 如果权限被拒绝，可以选择显示 UI 来帮助用户根据需要进行修正
  • 如果权限状态为“prompt”，请在应用中将出现提示的上下文化

示例权限 API 调用：

navigator.permissions.query({ name: "local-network-access" })
.then((result) => {
  console.log(`LNA permission state: ${result.state}`)
});

注意：从 HTTP 页面调用权限 API 时，始终返回“拒绝”。

如何以编程方式触发权限提示？

如果未与远程终结点建立连接，则不会触发 LNA 权限提示。 如果工作流在尝试与本地设备建立连接之前更容易触发权限提示，那么解决此问题的一种方法是向主机名发出提取 () 请求，该主机名可通过直观检查主机名 (验证为位于本地地址空间或环回地址空间中 localhost 或环回或本地 IP 地址文本) 。

实际上，这意味着，如果要触发与 localhost 连接的权限提示，则在 JavaScript 中触发提取 () 调用，如下所示：

fetch("http://localhost")

或者，如果要触发与本地设备连接的权限提示，则：

fetch("https://10.0.0.1")

一些说明：

• 适用于 Microsoft Edge 144 或更高版本
• 如果用户接受 (或拒绝) 权限，则用户不会看到其他权限提示。
• 如果执行提取 () 的上下文不需要联系 localhost (或本地网络)

如何从 iframe 内部发出本地网络请求？

从 iframe 内部发出本地网络请求需要嵌入文档在 iframe 上指定本地网络访问权限 策略 标志。 例如，如果 domainA.example 包含 domainB.example 的 iframe，则需要将权限显式委托给 iframe，如下所示：

<iframe src="domainB.example" allow="local-network-access"></iframe>

从嵌入文档发出本地网络请求时，会将其视为 嵌入 文档请求了 LNA 权限，并且用户的任何权限决策都将绑定到嵌入文档的来源。

如果 iframe 中的文档导航到同时发出本地网络请求的其他文档，则必须指定所有文档的所有源，这些文档可能针对权限策略标志发出本地网络请求。 若要扩展上面的示例，如果 domainB.example 将 iframe 导航到 domainC.example，并且 domainB.example 和 domainC.example 都发出本地网络访问请求，则需要将权限显式委托给这两个源，如下所示：

<iframe src="domainB.example" allow="local-network-access domainB.example domainC.example"></iframe>

还可以指定 allow=“local-network-access *”，以允许 iframe 中加载的所有源 (即使不一定提前知道本地网络请求) 。 例如，在重定向回 localhost 之前，iframe 可能会任意重定向到另一个源 (例如 SSO) ，这非常有用。

其他注意事项：

• 嵌入页和 iframe 都必须是 安全上下文 ，才能请求 LNA 权限。
• 从嵌套 iframe 内部请求 LNA 权限 (例如，domainA.example 嵌入 domainB.example 的 iframe，该 iframe 嵌入 domainC.example 的 iframe，这使得本地网络请求) 要求所有 iframe 指定本地网络访问权限策略标志。
• 必须在发出本地网络请求的 iframe 上设置权限策略，即使 通过企业策略绕过权限提示也是如此。

如何从服务辅助角色或共享辅助角色发出本地网络请求？

只要已在主窗口上下文中向辅助角色源授予 LNA 权限，就支持来自服务辅助角色和共享辅助角色的本地网络请求。 你想要通过从主应用程序窗口发出初始本地网络请求来尝试请求权限，然后辅助角色可以使用该权限 (包括从后台) 。

如何从专用辅助角色发出本地网络请求？

专用辅助角色完全归现有主窗口所有，因此来自专用辅助角色的本地网络请求将在拥有窗口中触发 LNA 权限提示。

如何避免将本地网络请求阻止为混合内容？

使用 LNA 时，某些本地网络请求现在不受混合内容阻止，从而允许 HTTPS 站点向以下 HTTP 终结点发出本地网络请求：

• .local domains (例如， http://printer.local)
• 专用 IP 文本 (例如， http://192.168.0.1/)

此外，使用提取 () API 时，可以指定 targetAddressSpace 选项，以标记请求发往本地网络或环回地址。 例如：

• fetch ('http://domainA.example'， {targetAddressSpace： 'local'} ) 如果 domainA.example 解析为本地 IP 地址（如 192.168.10.1）
• fetch ('http://domainB.example'， {targetAddressSpace： 'loopback'} 如果 domainB.example 解析为环回地址 127.0.0.1，) 将正常工作

这些内容都将被排除在混合内容阻止中。

如何从 HTTP 页面发出本地网络请求？

若要请求 LNA 权限，通过 HTTPS (（即 LNA）提供的网站需要一个安全的上下文) 。 但是，由于发出本地网络请求的复杂性，有时目标当前不支持公开受信任的 HTTPS，这意味着这些 HTTP 本地网络请求可能会作为混合内容被阻止。

虽然 LNA 尝试为常见情况制定例外 (请参阅上面关于 “如何避免将我的本地网络请求阻止为混合内容？” 部分) ，但调整网站以避免混合内容问题可能并不简单。

如果你发现自己需要更多时间来切换网站以使用 HTTPS，或者遇到 LNA 混合内容异常的阻止问题，因为它们当前在 Microsoft Edge 中实现，你可以注册 源试用版 ，以暂时允许 HTTP 站点请求 LNA 权限。

注意：必须通过 HTTP 标头提供源试用令牌。 此源试用版不支持通过元标记或通过 JS 以编程方式传递的令牌。

如何最好地维护跨浏览器兼容性？

由于不同的浏览器在不同时间推出这些限制，因此可能需要实现一些用户代理检测逻辑，以最大程度地提高兼容性。

支持新的本地网络访问规范的浏览器与尚不支持的浏览器之间的主要兼容性差异是 围绕混合内容。 在支持 LNA、本地网络访问和 LNA 权限的浏览器上，只能从安全源访问。 来自不安全源的请求失败。

在尚不支持 LNA 规范的浏览器上，大多数本地网络访问很可能是从不安全的源执行的，以避免对本地资源的不安全请求被标识为混合内容。

如果当前由于这种混合内容阻塞而通过 HTTP 提供页面服务，你可能希望为 Microsoft Edge 143 及更高版本提供 HTTPS 重定向，但请继续通过 HTTP (为其他浏览器提供服务，直到它们也附带 LNA 限制和混合内容例外) 。

如果仅向 localhost 发出本地网络请求，则应已经能够通过 HTTPS 为站点提供服务，因为 localhost 在混合内容规范中被视为安全来源，并且不会作为混合内容被阻止。

Microsoft Edge 推出期间，可以在 源试用版 中注册，以便在不安全 (HTTP) 源上 暂时 启用 LNA 权限提示。 详细了解 如何注册原始试用版。 此源试用版只能通过 Microsoft Edge 146 (（计划于 2026) 年 3 月转到稳定频道）提供。 源试用版的用户应打算在该时间之前迁移到 HTTPS。

如何在 EdgeDriver/Selenium/etc 中测试 LNA 权限？

本地网络访问权限可以通过 WebDriver/EdgeDriver 进行管理。 请参阅有关 特定于 Edge 的功能 的 Selenium 文档和有关 使用 WebDriver 自动执行 Microsoft Edge 的 Microsoft Edge 文档。 若要专门管理权限，请参阅 WebDriver setPermissions 命令 和 协议规范。

如何在本地测试中触发 LNA 提示符？

由于 LNA 限制尚不适用于本地→本地或本地→loopback 请求，因此典型的本地开发设置 (（如在 localhost) 上运行服务器）不会在 Microsoft Edge 中触发权限提示。

但是，它对于在本地测试中触发的权限提示很有用，例如，如果你正在自定义 UI 以在提示之前添加更多上下文，或者在用户已拒绝权限时帮助其恢复 (请参阅 如何为 LNA 权限提示为用户提供更多上下文？ 高于) 。

Microsoft Edge 提供了两种方法，可将页面视为从公共地址提供页面：

• HTML 文档上的 Content-Security-Policy： 将文档视为公共地址，导致该文档被视为从公共地址提供。
• --ip-address-space-overrides 命令行标志可用于强制将特定 IP 地址视为特定地址空间， (公共、本地或环回) 。

地址空间替代标志示例： 主本地开发服务器在 192.168.10.11 上运行，然后向在 192.168.10.12 上运行的单独服务器发出请求。 运行 Microsoft Edge 时，可以传递 --ip-address-space-overrides=192.168.10.11：0=public，强制将 192.168.10.11 视为公共地址， (端口 0 表示“应用于所有”端口“) 。 然后，当向运行于 192.168.10.12 的服务器发出请求时，它们将被视为本地网络请求并触发权限提示。

如何 避免 在自动测试中触发 LNA 提示符？

LNA 限制尚不适用于本地→本地或本地→loopback 请求，但某些基于浏览器的测试设置可能涉及可能导致 LNA 提示触发的本地服务器。 如果这是意外的，并且与 (测试的实际用户旅程不匹配，例如，生产站点只会向公共服务) 发出请求，则可以将 Microsoft Edge 配置为使用 --ip-address-space-overrides=ip-address>:<port>=<address-space 命令行标志将特定 IP 地址视为公共地址，因此从公共站点向其发出的请求不会触发 LNA 提示符。

可以指定端口 0 以将替代应用于该 IP 地址上的所有端口。 可以指定多个替代规则，以逗号 (例如 ip-address-space-overrides=192.168.0.1：8080=public，10.0.1.20：0=环回) 。 可 在此处找到标志的完整语法。

示例：暂存服务器在 23.220.75.232 上运行， (公共 IP 地址) 但向内部运行 10.0.1.108 的服务发出请求 (专用 IP 地址) 。 在生产环境中，此服务在公共 IP 地址上运行，因此预期实际用户不会看到 LNA 提示符。 在此服务的自动测试工具中，传递命令行标志 --ip-address-space-overrides=10.0.1.108：0=public，以便与该 IP 地址的所有连接都被视为公共连接，并且测试中不会触发 LNA 提示。

如何确定 LNA 阻止站点的原因

每当 Web 应用程序尝试访问被视为位于本地网络中的资源时，都会触发提示，让用户允许或阻止此类请求：

允许访问通常会取消阻止 Web 应用程序所需的功能。 目前，当本地网络访问尝试将 (或来自被视为在本地网络中) 跨源 iframe 时，手动或通过组策略) 免除 Web 应用程序 (将不起作用。

此 iframe 方案通常伴随着 DevTools 控制台错误：

Access to fetch at 'http://127.0.0.1:8080/data' from origin 'https://example.com'  

has been blocked by CORS policy: Permission was denied for this request to access the `unknown` address space. 

标识为 iframe 定义的跨源主机和顶级主机。 虽然建议 调整受影响的 Web 应用程序以在 iframe 中添加“本地网络访问”权限，但如果不直接控制 Web 应用程序代码，则可能无法执行此操作。

可在跨源 iframe 中使用的 Web 应用程序中使用的某些库已发布修补程序，以支持 4.26.1 或更高版本中包含的所需 LNA 权限，例如 MSAL-browser。

如何缓解跨源 iframe 的影响

当顶级主机或 iframe 主机被视为位于本地网络中时，根据特定的网络条件，在不执行代码更改的情况下缓解影响的唯一方法是使用 LocalNetworkAccessRestrictionsTemporaryOptOut 策略设置。

借助 Microsoft Edge 146 稳定版，以下附加策略可用于缓解本地网络访问限制影响跨源 iframe 的情况：

• LocalNetworkAccessIpAddressSpaceOverrides – 允许管理员将 IP 地址范围定义为公共、本地或环回。

• LocalNetworkAccessPermissionsPolicyDefaultEnabled - 允许跨源 iframe 继承通过 LocalNetworkAccessAllowedForUrls 顶级主机或域的策略定义的本地网络访问权限。

当某些网络配置需要时， LocalNetworkAccessIpAddressSpaceOverrides 策略还可用于将运营商级 NAT (CGN) 地址范围视为公共地址范围。 例如，若要免除 CGN 地址范围，请使用值配置策略：

100.64.0.0/10=public

常见本地网络访问方案的策略指南

通常，应根据导致本地网络访问限制的方案使用以下策略设置。

1. CGN IP 地址方案

   如果问题是由运营商级 NAT (CGN) IP 地址分类为本地的，则使用 LocalNetworkAccessIpAddressSpaceOverrides 策略将 CGN 地址范围重新分类为公共就足够了。

2. 本地 IP 地址方案

   如果问题是由实际本地 IP 地址引起的，则使用 LocalNetworkAccessAllowedForUrls 策略免除顶级域可能会解决此问题，前提是：

   • 网站不包含跨源 iframe。
   • 网站包含跨源 iframe，这些 iframe 权限包含在 local-network-access 网站代码中。

3. 没有所需权限的跨源 iframe 方案

   如果跨源 iframe 不包括 local-network-access iframe 权限，则只能通过以下方法解决问题：

   • 更新网站代码以将 local-network-access 权限添加到所需的跨源 iframe。
   • 将 LocalNetworkAccessPermissionsPolicyDefaultEnabled 策略与 LocalNetworkAccessAllowedForUrls 策略结合使用，以允许顶级主机或域。

企业环境测试指南

若要在环境中适应这些策略设置，请在广泛部署之前定义测试计划。 以下步骤可用作常规基线：

• 验证哪些主机解析为 CGN 地址范围，并确定使用它们的网站。

• 如果配置了 LocalNetworkAccessAllowedForUrls 策略， (暂时删除除 SharePoint 或 OneDrive) 所需的条目之外的所有条目。 然后使用 LocalNetworkAccessIpAddressSpaceOverrides 策略将 CGN 地址空间重新分类为公共（如果适用）。

• 测试受影响的网站，如果显示本地网络访问提示，则可能需要使用 LocalNetworkAccessAllowedForUrls 策略允许顶级主机。

• 对于问题仍然存在 (这意味着允许 LNA 提示，但网站仍然失败，除非) 使用选择退出策略，请考虑同时启用 LocalNetworkAccessPermissionsPolicyDefaultEnabled 策略和 LocalNetworkAccessAllowedForUrls 。

• 使用来自不同部门（依赖于不同 Web 应用程序并根据需要调整策略配置）的代表组测试这些配置。

如何通常提供有关 LNA 的反馈？

在 GitHub 上的本地网络访问规范存储库中提交反馈问题。

如何报告 Microsoft Edge 的 LNA 实现中的 bug？

对于特定于Microsoft Edge 实现本地网络访问的问题，请使用 Microsoft Edge 反馈渠道或联系企业客户的Microsoft 支持部门。

[企业]如何为本地网络请求列出允许列表或阻止列表 URL

LNA 有两个企业策略： LocalNetworkAccessAllowedForUrls 和 LocalNetworkAccessBlockedForUrls。 它们可用于允许来自 URL 的本地网络请求而不显示权限提示，或阻止 URL 发出本地网络请求。

这些策略还支持使用 URL 模式 语法的通配符。

LocalNetworkAccessAllowedForUrls 策略适用于发出请求的站点的顶级源。 如果实际本地网络访问是在嵌入该页面 (或嵌套 iframe) 的 iframe 内进行的， 则所有 iframe 都必须设置权限策略标志。

[企业]我设置了 LocalNetworkAccessAllowedForUrls，但我仍然遇到问题

如果已正确设置 LocalNetworkAccessAllowedForUrls 策略，但应用程序仍无法工作，则可能需要修复 iframe。 请参阅上面标题为 “如何从 iframe 内部发出本地网络请求？”

还有一个临时企业策略 LocalNetworkAccessRestrictionsTemporaryOptOut，允许企业选择退出所有 LNA 限制。 此策略是临时策略，将在 Edge 152 之后删除。

注意：可以通过 ADMX 模板) 组策略 (、Microsoft Intune (设置目录) 或其他移动设备管理 (MDM) 解决方案来配置这些策略。 有关配置 Microsoft Edge 策略的详细信息，请参阅 配置 Microsoft Edge 策略设置。