networkquality 是一次性标准化网络质量探针测试，输出上/下行理论容量、延迟、丢包率等链路级质量指标，非实时带宽监控；关键诊断字段为 uplinkcapacitymbps、downlinkcapacitymbps、latencyms 和 packetloss。
networkquality 不是实时带宽监控器，也不输出“当前正在用多少 mbps”这种瞬时速率。它做的是**一次性的、标准化的网络质量探针测试**，结果反映的是设备到 apple cdn 节点这一段路径的理论通道能力与稳定性，适合诊断链路级问题，而非秒级流量观察。
看懂关键指标：不是速度，是质量潜力
执行 networkQuality 后输出的 JSON 中，真正用于诊断的字段是：
- uplinkCapacityMbps / downlinkCapacityMbps：Apple 估算的上/下行理论容量（单位 Mbps），不是实时占用值，但若远低于你签约带宽（如显示 12 而你办了 500M），说明链路存在瓶颈（如 Wi-Fi 干扰、中间设备限速、MTU 异常）
- latencyMs：应用层往返延迟（比 ping 更贴近真实 HTTPS 请求），持续高于 50ms 且波动大，可能指向 DNS 解析慢、TLS 握手卡顿或中间节点拥塞
- packetLoss：基于 HTTP/3 流量估算的丢包率（非 ICMP），>0.5% 就值得警惕，常见于弱信号 Wi-Fi、老旧路由器或企业防火墙过度拦截
用 -v 参数定位异常环节
加 -v 能看到每阶段耗时和失败细节，比如：
- 卡在 “Resolving networkquality.apple.com” → DNS 问题或域名被屏蔽
- 长时间停在 “Starting TLS handshake” → 本地证书信任异常、中间人设备干扰、或 QUIC 被禁用
- “Retransmission count” 持续上升 → 物理层不稳定（Wi-Fi 信号差、网线接触不良）或路由丢包
绕过默认节点验证特定链路
如果你怀疑问题出在某台自建服务器或 CDN 上，用 -s 指定目标：
- networkQuality -s api.yourcompany.com -p 443：直连内部服务，对比默认结果。若 latencyMs 突增、packetLoss 飙升，说明问题在业务链路本身，而非公网接入
- 搭配 -L 8 -n 1 可快速采样，避免干扰前台应用：“networkQuality -s cn.example.com -L 8 -n 1”
排除常见误判场景
以下情况会导致结果失真，需先确认：
- macOS 版本低于 12.3：命令不存在；10.15–12.2 版本存在但行为略有差异
- 公司网络屏蔽 networkquality.apple.com 或禁用 QUIC 协议 → 报错 “No network connectivity” 或超时
- 使用 USB-C 扩展坞或老旧网卡驱动 → uplinkCapacityMbps 持续偏低且 ul_target_bitrate 波动剧烈
- 测试时后台有大文件上传（如 iCloud 同步）→ 结果会被拉低，建议关闭同步再测
