能力中的概念
Local Network Access
发布于 更新于
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 失败,防止请求泄露到互联网上。
另请参阅
链接到“另请参阅”一节- WebRTC:浏览器中的点对点音视频与数据,尚未纳入该权限的连接类型之一
- WebTransport:HTTP/3 的流与数据报
- Web Bluetooth API:连接蓝牙低功耗设备,完全不经过 IP 的另一条近场设备路径
- Local Network Access: Permissions(wicg.github.io)
- New permission prompt for Local Network Access(developer.chrome.com)
- Request: targetAddressSpace property(developer.mozilla.org)
- Local Network Access explainer(github.com)
规范
| 规范 | 状态 |
|---|---|
| 本地网络访问(Request.targetAddressSpace) | WICG 草案 |
| Local Network Access: permission prompt | WICG 草案 |
| Local Network Access: IP address space | WICG 草案 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| 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 |
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- browser-compat-data 未记录 WebView Android 的支持。