networkquality测速失败可能因系统版本、网络限制或参数误用；可通过基础测速、详细日志、自定义服务器、限时测试及管道提取五种方式排查与优化。
如果您在Mac终端中运行networkQuality命令但未获得预期的网络质量评估结果，则可能是由于系统版本兼容性、网络连通性限制或参数误用所致。以下是针对networkQuality测速的多种可行思路：
一、执行基础测速获取默认网络质量指标
该方法调用系统内置逻辑，向Apple指定CDN节点发起HTTP/3+QUIC连接，同步采集上行与下行理论通道能力、延迟及丢包率，输出JSON格式结果，适用于快速判断当前链路基础质量。
1、打开“应用程序 > 实用工具 > 终端”。
2、输入命令：networkQuality，然后按回车键执行。
3、等待约15–30秒，终端将输出包含uplinkCapacityMbps、downlinkCapacityMbps、latencyMs和packetLoss字段的JSON数据。
二、启用详细日志模式定位连接异常环节
添加-v参数可展开底层测试过程，显示DNS解析、TLS握手、QUIC协商、RTT采样及重传行为等调试信息，便于识别是否因防火墙拦截、代理干扰或证书验证失败导致测速中断。
1、在终端中输入：networkQuality -v，回车执行。
2、观察输出中是否出现“Failed to connect”、“TLS handshake failed”或“QUIC negotiation timeout”等错误标记行。
3、若发现目标域名networkquality.apple.com无法解析或连接超时，需检查本地DNS设置或企业网络策略是否屏蔽该地址。
三、指定自定义HTTPS服务器验证特定链路质量
使用-s参数可将测速目标切换至任意支持HTTPS的域名，绕过Apple默认节点，用于评估企业内网API网关、私有CDN或云服务出口的实际传输能力，尤其适用于受控网络环境下的定向诊断。
PyCharm 2026.2.0.1 Mac版提供 JetBrains 官方 2026.2.0.1 版本安装包，适合在macOS系统上进行 Python 项目开发、运行、调试和测试。
1、确认目标服务器已启用HTTPS并开放对应端口（如443或8443）。
2、在终端中输入：networkQuality -s example.com -p 443，将example.com替换为实际域名。
3、命令将尝试建立TLS连接并执行完整上传/下载/延迟测试流程，输出字段结构与基础模式一致。
四、限制测试持续时间以适配低功耗或后台监控场景
通过-L参数设定最大执行时长（单位：秒），避免长时间占用网络资源，适用于自动化脚本周期性轻量探测，或在电池供电设备上降低测速对系统性能的影响。
1、在终端中输入：networkQuality -L 10，表示最长运行10秒后自动终止。
2、若需进一步降低并发压力，可追加-n 1参数：networkQuality -L 10 -n 1，仅启用单流测试。
五、结合shell管道提取数值并转换为Mbps单位
为便于脚本解析或人工快速换算，可通过awk对原始JSON输出进行数值提取与单位转换，将bps级结果自动除以1000000并保留一位小数，生成符合常规认知的Mbps格式数据。
1、在终端中输入：networkQuality | awk -F': ' '/downlinkCapacityMbps|uplinkCapacityMbps/ {gsub(/[,}]/,"",$2); printf "%.1f Mbps\n", $2/1}'。
2、该命令将直接打印两行结果，分别对应下行与上行理论能力，单位为Mbps，无需手动计算。
