Network Information API 是浏览器提供的一套用于感知用户网络状况的接口，核心对象是 navigator.connection。它包含 effectiveType、downlink、rtt、saveData 等属性，可以帮助前端判断用户正处于 2G 弱网还是 WiFi 环境，从而动态调整资源加载策略、关闭动画或降低图片质量。然而 TypeScript 的标准库对这部分 API 的类型支持并不稳定，很多版本的 lib.dom 里 navigator.connection 可能不存在，或者属性类型不够精确，直接访问时会遇到类型错误提示。想要在项目里安全使用网络质量监控，最直接的办法就是自行补全类型定义，并把读取和监听逻辑封装成独立模块。
类型补全的核心并不复杂，但需要兼顾三点：一是精确描述有效连接类型，二是定义清楚连接信息对象的字段，三是为后续的事件监听预留类型空间。下面先给出一个基础的类型声明示例。
type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
interface NetworkConnectionInfo {
effectiveType: EffectiveConnectionType;
downlink: number;
rtt: number;
saveData: boolean;
}
这里用字符串字面量联合类型把 effectiveType 限制在 Network Information API 规范中定义的几个值里，避免因为拼写错误而引入无效状态。同时把 downlink 定义为 number 类型，表示下行带宽估算值，单位是 Mbps；rtt 表示往返时间，单位是毫秒；saveData 用于判断用户是否开启了省流量模式。这些字段在真实浏览器中不一定全部存在，所以接口定义还可以结合可选属性进行更宽松的处理。实际项目中建议根据目标浏览器覆盖范围决定是否使用可选属性，比如 downlink?: number 能兼容旧版本实现。
从内置类型到自定义扩展：深入理解类型缺口
很多人以为升级 TypeScript 版本之后 navigator.connection 就应该自动获得完整类型，但实际情况并非如此。标准库 lib.dom 对 Network Information API 的支持在不同版本之间存在差异，有时虽然声明了 Navigator.connection 属性，但属性类型被定义为 any 或者缺少 saveData 字段。更常见的情况是，开发者通过 navigator.connection 访问时会得到 Property 'connection' does not exist on type 'Navigator' 之类的编译错误。这类问题在严格模式或者开启 noImplicitAny 的项目里尤其突出。
要解决这个类型缺口，一种做法是直接扩展全局 Navigator 接口。例如在项目的类型声明文件（通常是以 d.ts 结尾的文件）中加入以下代码。
declare global {
interface Navigator {
connection?: NetworkConnectionInfo;
}
}
export {};
这段代码通过声明合并的方式给 Navigator 接口增加了一个可选的 connection 属性，类型指向我们自定义的 NetworkConnectionInfo 接口。使用可选属性是为了兼容那些不支持该 API 的浏览器，在访问时可以通过 navigator.connection?.effectiveType 这样的可选链语法安全读取。注意文件末尾的 export {} 是必须的，它让这个文件成为一个模块，从而允许 declare global 生效。如果没有这个导出语句，TypeScript 会把该文件视为全局脚本，declare global 会被忽略。
不过采用全局扩展也有一个潜在问题：如果项目依赖的某个类型库已经对 Navigator.connection 做了类似声明，并且类型不一致，就可能产生接口合并冲突。因此在团队协作或引入第三方库时，更推荐的方式是不修改全局类型，而是通过类型断言或辅助函数来访问 navigator.connection。下面这个工具函数就展示了如何在不污染全局类型的前提下安全获取连接信息。
function getConnectionInfo(): NetworkConnectionInfo | null {
const nav = navigator as Navigator & { connection?: NetworkConnectionInfo };
const connection = nav.connection;
if (!connection) {
return null;
}
return {
effectiveType: connection.effectiveType ?? '4g',
downlink: connection.downlink ?? 0,
rtt: connection.rtt ?? 0,
saveData: connection.saveData ?? false
};
}
这段代码先把 navigator 断言成带有自定义 connection 属性的交叉类型，然后检查 connection 是否存在，不存在时直接返回 null。存在时则读取各字段并使用 ?? 运算符设置默认值。这样做的好处是类型声明完全局部化，不会与全局类型冲突，同时也方便在读取阶段对缺失字段做兜底处理。对于任何需要支持旧浏览器的项目，这种模式都更可控。
设计可复用的连接质量监控类型与工具函数
有了基础的类型定义和获取函数之后，下一步就是设计一套真正可复用的监控工具。监控不仅要能读取当前的网络状态，还要能在网络状态发生变化时通知调用方。Network Information API 规定 navigator.connection 对象继承自 EventTarget，当网络条件变化时会触发 change 事件。因此我们可以封装一个订阅函数，把事件监听和类型安全结合起来。
为了提升类型的可维护性，建议把事件处理函数也纳入类型体系。可以定义一个处理函数类型 NetworkChangeHandler，它接收一个 NetworkConnectionInfo 参数并返回 void。订阅函数则返回一个取消订阅的函数，方便在组件卸载或页面销毁时清理监听器，避免内存泄漏。下面是完整的实现代码。
type NetworkChangeHandler = (info: NetworkConnectionInfo) => void;
function subscribeNetworkChanges(handler: NetworkChangeHandler): () => void {
const nav = navigator as Navigator & { connection?: NetworkConnectionInfo & EventTarget };
const connection = nav.connection;
if (!connection) {
return () => {};
}
const listener = () => {
const info = getConnectionInfo();
if (info) {
handler(info);
}
};
connection.addEventListener('change', listener);
return () => {
connection.removeEventListener('change', listener);
};
}
注意这里把 connection 的类型断言成了 NetworkConnectionInfo & EventTarget，因为 NetworkConnectionInfo 本身只描述了数据字段，并没有声明事件相关的方法。通过交叉类型补上 EventTarget，我们就能合法地调用 addEventListener 和 removeEventListener。监听器内部再次调用 getConnectionInfo 去获取最新状态，这样回调中拿到的总是最新的连接信息，而不是事件对象本身。返回的清理函数会在调用时移除监听器，确保不会残留无用的事件绑定。
这个订阅函数已经可以满足大多数场景，例如结合 React 的 useEffect 或者 Vue 的 onMounted/onUnmounted 使用。在 React 函数组件中，可以在 useEffect 里调用 subscribeNetworkChanges 并返回清理函数，状态变化时更新组件状态，从而驱动界面重新渲染。这种模式比直接暴露 navigator.connection 更符合前端框架的数据流习惯，也让网络监控逻辑与 UI 层解耦。
完善事件处理与降级策略，让监控更稳健
网络监控模块在实际生产环境中最容易被忽视的环节就是降级处理。虽然现代 Chrome、Edge 等浏览器对 Network Information API 支持较好，但 Firefox 和 Safari 长期未完整实现该接口，部分移动端浏览器也只暴露了少量字段。如果监控代码没有做好防御，很可能在用户量较大的浏览器上直接抛错，影响页面主流程。因此我们不仅要在读取时判断 connection 是否存在，还要对字段类型进行二次校验。
例如某些旧版浏览器虽然提供了 connection 对象，但 effectiveType 的值可能不是规范中的四个枚举之一，而是返回了未定义的字符串。针对这种情况，可以在 getConnectionInfo 中增加运行时校验，把不合法的值归一到 unknown 类型。下面的代码展示了如何对 effectiveType 做安全转换。
function normalizeEffectiveType(value: string | undefined): EffectiveConnectionType | 'unknown' {
const validTypes: EffectiveConnectionType[] = ['slow-2g', '2g', '3g', '4g'];
return validTypes.includes(value as EffectiveConnectionType) ? value as EffectiveConnectionType : 'unknown';
}
这个函数接收一个可能为 undefined 的字符串，检查它是否属于已知的联合类型，如果不在列表中则返回 unknown。虽然 TypeScript 的 includes 类型推断在数组上不一定能完全收窄，因此这里用了 as EffectiveConnectionType 进行断言，并返回联合类型 EffectiveConnectionType | 'unknown'。调用方拿到这个结果后，可以进一步判断是否为 unknown 来决定是否启用降级策略，比如默认按 4G 网络处理或暂停预加载。
除了字段归一化，事件监听的降级也同样重要。在不支持 addEventListener 的极老版本浏览器中，直接调用会报错。由于我们已经把 connection 断言为包含 EventTarget 的交叉类型，运行时仍然需要确认方法存在。可以在 subscribeNetworkChanges 里增加一层判断，如果 connection 上不存在 addEventListener 方法，就返回一个空的清理函数，并可选地降级为定时轮询。下面的改进版本展示了这一思路。
function subscribeNetworkChanges(handler: NetworkChangeHandler): () => void {
const nav = navigator as Navigator & { connection?: NetworkConnectionInfo & Partial<EventTarget> };
const connection = nav.connection;
if (!connection || typeof connection.addEventListener !== 'function') {
return () => {};
}
const listener = () => {
const info = getConnectionInfo();
if (info) {
handler(info);
}
};
connection.addEventListener('change', listener);
return () => {
connection.removeEventListener('change', listener);
};
}
这里将 connection 的类型改为 NetworkConnectionInfo & Partial<EventTarget>，这样 addEventListener 就变成了可选方法，要求调用前进行检查。代码中用 typeof connection.addEventListener !== 'function' 判断方法是否存在，不存在则返回空函数。这种写法既保留了类型安全，又兼容了运行时差异。对于完全没有 Network Information API 的环境，nav.connection 本身就是 undefined，函数会直接返回空清理函数，不会产生任何副作用。
另一个值得注意的细节是 change 事件的触发频率。网络状态变化并不频繁，但在移动端切换基站或 WiFi 与蜂窝网络之间切换时可能会连续触发。如果监控回调中包含昂贵的操作，例如重新请求数据或重建复杂组件，建议加入防抖或节流处理。由于本文的重点是类型定义，这里不再展开，但读者可以在 listener 内部自行加入防抖逻辑，确保回调不会在短时间内被密集调用。
总体来看，TypeScript 中定义 Network Information API 网络连接质量监控类型并不复杂，关键是把类型边界划定清楚，并通过辅助函数将类型断言与运行时校验结合起来。自定义 NetworkConnectionInfo 接口、EffectiveConnectionType 联合类型以及订阅/清理函数，可以让网络监控逻辑在强类型约束下保持简洁和可维护。在不支持该 API 的浏览器里，借助可选属性和函数判断可以优雅降级，避免影响页面核心功能。这样一来，无论是根据网络质量动态加载资源，还是向用户展示网络状态提示，都有了扎实的类型基础。
Network Information APITypeScript网络质量监控修改时间：2026-09-22 18:50:52