跳转到内容

能力中的概念

Local Network Access

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)WICG 草案

Local Network Access 是浏览器权限,允许公网页面访问本地网络设备(如路由器、打印机、开发服务器)或本机。它没有单独的申请 API。页面第一次向这类地址发起 fetch()、加载子资源或导航 iframe 时,浏览器就会提示授权;用户拒绝后,请求失败。脚本能看到的主要接口是 fetch() 与 Request 上的 targetAddressSpace 选项,用来声明请求的去向,让浏览器据此免除混合内容拦截。Explainer 还计划接入 Permissions API,让页面读取授权状态。

Chrome 142 默认显示该提示;Chrome 138 起可通过把 chrome://flags/#local-network-access-check 设为「Enabled (Blocking)」提前启用。Request.targetAddressSpace 兼容性数据记录 Chrome 142 起支持,Firefox、Safari 和 Android WebView 未记录支持。这一设计取代了 Private Network Access。后者靠本地设备必须应答的 CORS 预检来把关同类请求,Chrome 已将其搁置。

规范将 IP 地址分为三个地址空间,分别是 loopback(127.0.0.0/8、::1/128、0.0.0.0/32、::/128、198.18.0.0/15)、local(10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、运营商级 NAT 的 100.64.0.0/10、链路本地的 169.254.0.0/16、fc00::/7、fe80::/10、fec0::/10、0.0.0.0/8,以及 IPv6 文档前缀 2001:db8::/32 与 3fff::/20),其余全部为 public。IPv4 映射的 IPv6 地址(::ffff:0:0/96)按其内嵌 IPv4 地址归类。本地网络请求的目标空间比发起文档所在空间更不公开,包括 public 到 local、public 到 loopback、local 到 loopback。

这类请求受两项策略控制,默认允许列表都是 'self'。local-network 管去往 local 地址的请求,loopback-network 管去往 loopback 地址的请求。旧的单一名称 local-network-access 在 Chromium 中仍作为两者的别名保留,Permissions-Policy 响应头和 iframe 的 allow 属性里都能用。因此需要该能力的跨源 iframe 必须嵌入时委托:访问 local 地址用 allow="local-network",访问 loopback 地址用 allow="loopback-network",两者都要就用 allow="local-network-access";未委托时其请求直接失败,不出现提示。只有安全上下文才能获得这项权限,所以经由 http:// 提供的公网页面会被拦截。Chromium 暂时不限制本身就位于本地网络、又处在非安全上下文的页面访问 localhost(规范 § 4.4)。

很多本地服务器不跑 HTTPS,规范称迁移到 HTTPS 很难,有时甚至做不到。因此规范规定,浏览器若能在 DNS 解析前判断这是本地网络请求,就免除混合内容检查。主机名为私有 IP 字面量(http://192.168.0.1/)、主机名以 .local 结尾,或调用带有 targetAddressSpace: "local" 或 "loopback",均符合这个条件。建立连接后还要核验声明。解析出的地址不在声明的空间内时请求失败,而不是悄悄变成公网请求。一个恰好解析到 192.168.0.1 的公网主机名若未加注解,仍算混合内容。

Chrome 对 fetch()、子资源加载(<img>、<script>、CSS)和 iframe 导航执行检查;Service Worker 与 Shared Worker 只有在同源文档已经获得授权后才能发起这类请求(Worker 无法弹出提示,crbug.com/404887282 跟踪修复)。在 Chrome 138 的可选测试阶段,WebSocket、WebTransport 和 WebRTC 连接尚未纳入权限管控(crbug.com/421156866、crbug.com/421216834、crbug.com/421223919)。Chrome 的第一阶段只管控从公网地址发起的请求;https://router.local 这样的本地源访问另一台本地设备或访问回环地址时不会弹出提示,Chrome 博客把这列为计划中的扩展。

DevTools 显示 ERR_LOCAL_NETWORK_PERMISSION_MISSING 时,先检查站点的本地网络权限。Chromium 将它与 ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECKS 分开定义;仅凭 fetch() 失败,不能判断是哪项检查未通过。本地网络错误排查按权限、iframe 策略、地址空间声明和 CORS 区分原因,可先据此定位,再调整设备设置。

示例需要在 https:// 页面运行。请求本身会触发提示,因此要处理 fetch() 拒绝的情况,提供手动访问方式,不自动重试。

从已安装的 PWA 读取路由器状态页

链接到“从已安装的 PWA 读取路由器状态页”一节

'targetAddressSpace' in Request.prototype 是检测该选项的快捷办法,BCD 记录它从 Chrome 142 起提供。它不存在时(Firefox、Safari、Chrome 142 之前),该请求在 HTTPS 页面里就是普通混合内容,浏览器在任何网络活动之前就会拦下。Chrome 138 到 141 只有在用户启用 chrome://flags/#local-network-access-check 后,才会执行这些检查,并对私有 IP 字面量和 .local 免除混合内容拦截(Chrome 博客)。下面的回退逻辑在新标签页打开设备自己的页面,那里不涉及跨源请求。

const ROUTER = 'http://192.168.1.1/status.json';
function browserGatesLocalNetwork() {
return typeof Request !== 'undefined' && 'targetAddressSpace' in Request.prototype;
}
async function readRouterStatus() {
if (!window.isSecureContext || !browserGatesLocalNetwork()) {
return { ok: false, reason: 'unsupported' };
}
try {
const res = await fetch(ROUTER); // IP 字面量:免除混合内容检查,提示只出现一次
if (!res.ok) return { ok: false, reason: `http-${res.status}` };
return { ok: true, status: await res.json() };
} catch {
return { ok: false, reason: 'blocked-or-offline' }; // 提示被拒、CORS 失败或设备离线
}
}
document.querySelector('#check-router').addEventListener('click', async () => {
const result = await readRouterStatus();
if (!result.ok) {
window.open('http://192.168.1.1/', '_blank', 'noopener');
return;
}
renderStatus(result.status);
});

用户拒绝授权、设备的 CORS 检查失败、路由器断电,都会让 fetch() 以 TypeError 拒绝。可以记录错误,但错误本身分不出原因。Explainer 说这项权限将可通过 Permissions API 读取,要按授权被拒来分支处理,就走这条路。

为解析到本地地址的主机名声明地址空间

链接到“为解析到本地地址的主机名声明地址空间”一节

devbox.example.com 这样解析到 10.0.0.5 的公网主机名本身并不豁免混合内容。给调用加上 targetAddressSpace: "local" 后,浏览器允许建立 http:// 连接,再核验解析出的地址确实在 local 空间。不支持该选项的浏览器会忽略这个未知的 RequestInit 成员,浏览器会按混合内容拦截同一调用;因此代码在选项缺失时改走 https:// 备选地址。

async function callDevBox(path) {
const supportsOption = 'targetAddressSpace' in Request.prototype;
const url = supportsOption
? `http://devbox.example.com${path}`
: `https://devbox.example.com${path}`; // 设备上需要有效证书
const init = supportsOption ? { targetAddressSpace: 'local' } : {};
const res = await fetch(url, init);
return res.json();
}
callDevBox('/api/health').catch((err) => {
document.querySelector('#devbox-note').textContent =
`无法连接开发机(${err.name})。请确认你在办公网络内。`;
});

如果 devbox.example.com 日后迁到公网 IP,带注解的请求会以 ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECKS 失败,防止请求泄露到互联网上。

规范

规范状态
本地网络访问(Request.targetAddressSpace)WICG 草案
Local Network Access: permission promptWICG 草案
Local Network Access: IP address spaceWICG 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
Chrome (Desktop)#支持142高来源—
Chrome (Android)#支持142高来源1
Edge (Desktop)#支持142高来源2
Firefox (Desktop)#不支持—高来源3
Firefox (Android)#不支持—高来源45
Safari (macOS)#不支持—高来源6
Safari (iOS)#不支持—高来源78
Samsung Internet#支持30.0高来源9
WebView (Android)#不支持—高来源10
  1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Firefox for Android 的支持。
  5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  6. browser-compat-data 未记录 Safari 的支持。
  7. browser-compat-data 未记录 iOS 版 Safari 的支持。
  8. 由 browser-compat-data 镜像自 Safari 的数据推导。
  9. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  10. browser-compat-data 未记录 WebView Android 的支持。

源数据: /compatibility/local-network-access.json · 全球使用占比: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-28 · 置信度: 高 (由来源计算)