导读：
- 理解错误代码的体系
- 系统级网络错误（NSURLErrorDomain）
- TLS/SSL 证书错误（-1200 / -9806 / -9807）
- 代理协议特定错误
- 订阅与配置类错误
- 高级诊断与日志分析
- 系统性排障流程图
- 预防性配置建议
Shadowrocket（小火箭）常见错误代码深度解析与排障指南
理解错误代码的体系
Shadowrocket 作为 iOS 平台最主流的代理客户端，其错误提示主要来源于三个层面：
- iOS 系统层（NSURLErrorDomain）：网络基础设施错误
- 代理协议层（Shadowsocks/VMess/Trojan 等）：协议握手失败
- 应用逻辑层：配置解析、规则匹配、订阅更新等
本文将按错误代码的数值区间和实际场景进行分类,提供从现象到根因的完整诊断链路。
系统级网络错误（NSURLErrorDomain）
超时类错误（-1001 / -1003）
错误表现：The request timed out. 或 Cannot find host
深度解析：
- -1001：TCP 三次握手阶段超时，通常意味着节点 IP 被封锁或端口不通
- -1003：DNS 解析失败，可能是本地 DNS 污染或节点域名已失效
排障步骤：
切换 DNS 为 8.8.8.8 或 1.1.1.1 → 排除本地 DNS 污染
3. 检查节点地址是否为域名 → 尝试替换为 IP 地址测试解决方案：
- 更换节点端口（避开 443/80 等高危端口）
- 启用「允许不安全」仅用于测试，确认是否为证书问题
- 检查是否开启「IPv6 优先」导致连接异常
连接被拒绝（-1004 / -10061）
错误代码：Cannot connect to host 或 Connection refused
根因分析：
- -1004：服务端未运行或防火墙拦截
- -10061：Windows/Linux 服务端未监听对应端口（常见于自建节点）
关键排查点：
- 时间同步：VMess/VLESS 协议对时间敏感，客户端与服务端时间差需 < 90 秒
- 端口连通性：使用在线端口检测工具确认端口状态
- IP 被墙：通过
tcping测试，若丢包 100% 需更换 IP
TLS/SSL 证书错误（-1200 / -9806 / -9807）
证书验证失败（-1200）
典型场景：使用 Trojan/Trojan-Go 或 VMess+TLS 时
错误信息：An SSL error has occurred
技术细节：
- 证书域名与 SNI 不匹配
- 自签名证书未导入信任
- 系统时间错误导致证书有效期验证失败
修复方案：
- 检查 SNI 设置：确保与证书 CN 字段一致（特别是使用 CDN 时）
- 证书导入：在 Shadowrocket → 配置 → 证书 → 安装并信任根证书
- 临时绕过（仅测试）：开启「允许不安全 TLS」，确认连接成功后回退排查证书
加密套件不匹配（-9806）
现象：iOS 14+ 系统出现，提示 bad access
原因：服务端启用了旧版 TLS 1.0/1.1 或弱加密算法，iOS 13+ 已默认禁用
解决：升级服务端至支持 TLS 1.3，或在 Shadowrocket 的「TLS」设置中启用「兼容模式」
代理协议特定错误
Shadowsocks 协议错误
错误代码：Invalid protocol 或 Stream error
常见原因：
- 加密方式不匹配：服务端为
aes-256-gcm，客户端误设为aes-256-cfb - 插件参数错误：使用
obfs或v2ray-plugin时，参数格式错误（如obfs-host未填写） - UDP 转发问题：游戏加速场景下，节点不支持 UDP 或未开启 UDP relay
调试技巧： 在「节点」→「编辑」→「高级」中：
- 关闭「UDP 转发」测试基础连接
- 检查「插件」选项中的 JSON 参数格式（注意转义字符）
VMess/VLESS 协议错误
错误提示：Invalid user / Bad request / malformed HTTP response
诊断矩阵：
| 错误提示 | 可能原因 | 解决方案 |
|---|---|---|
Invalid user |
UUID 错误/AlterID 不匹配 | 核对 UUID 大小写（必须小写），AlterID 设为 0（VMess AEAD） |
Bad request |
传输层设置错误 | 检查 WebSocket Path 是否以 开头，Host 是否匹配 |
TLS handshake failed |
XTLS 流控设置错误 | VLESS 使用 XTLS 时，确保服务端支持，或改用普通 TLS |
特别注意：
- VMess MD5 校验：2022 年后服务端若启用
alterId: 0（AEAD），旧版客户端需更新 - Mux 多路复用：开启 Mux 后若出现断流，尝试关闭或调整
concurrency为 8-16
Trojan 协议错误
特征：连接后立即断开，无明确错误码
排查重点：
- 密码错误：Trojan 无 UUID 概念，密码必须完全一致（区分大小写）
- TLS 指纹：服务端若开启
shadowtls或utls模拟，客户端需匹配设置 - 回落（Fallback）配置：若 443 端口被占用或回落域名错误，表现为连接后无响应
订阅与配置类错误
订阅更新失败（-1009 / -1011）
错误代码：The Internet connection appears to be offline（实际有网）
根因：
- User-Agent 被拦截：部分机场订阅需要特定 UA，在「订阅」→「编辑」→「User-Agent」填入
Shadowrocket或Clash - 302 重定向过多：订阅链接跳转次数超过 5 次，需使用最终 URL
- 证书 Pinning：订阅域名使用自签名证书，需在「全局路由」→「证书」中信任
配置导入错误
现象：二维码扫描后提示 Invalid configuration
常见格式错误：
- URL Scheme 错误：SS 链接中 符号被 URL 编码为
%40，需解码 - Base64 填充 Base64 解码失败（缺少 填充），手动补 至长度为 4 的倍数
- JSON 格式：手动编辑配置时，引号未闭合或存在中文符号
高级诊断与日志分析
开启详细日志
路径：设置 → 高级 → 日志级别 → Verbose
关键日志标识：
TCP relay: 表示 TCP 流量已开始转发，若此后断开，多为协议层问题TLS handshake started: 证书交换阶段，若卡住则为 TLS 错误WebSocket handshake: 检查 Path 和 Host 是否匹配服务端 Nginx/Cloudflare 配置
抓包分析（极端情况）
使用 iOS 的 RVI（Remote Virtual Interface） 配合 Wireshark：
# macOS 上执行，抓取 iPhone 流量 rvictl -s [设备UDID] # 过滤 Shadowrocket 流量 tcp.port == 1080 || tls.handshake.type == 1
系统性排障流程图
连接失败
│
├─→ 测试其他 App 网络 → 不通 → 检查系统 VPN 权限/蜂窝数据权限
│
└─→ 仅 Shadowrocket 失败
│
├─→ 所有节点失败 → 检查「全局路由」模式/DNS 设置/证书
│
└─→ 仅特定节点失败
│
├─→ 超时错误 (-1001) → 检查 IP 端口/防火墙
│
├─→ SSL 错误 (-12xx) → 检查证书/SNI/时间同步
│
└─→ 协议错误 → 检查加密方式/UUID/传输层设置预防性配置建议
-
DNS 防污染：在「全局路由」→「DNS」中配置
DoH（如https://dns.google/dns-query），避免本地 DNS 泄露导致的连接异常 -
自动故障转移：在「节点」→「编辑」→「高级」中设置
Timeout为 5 秒，并开启「自动切换」避免卡在死节点 -
配置备份：定期导出
.conf配置文件，防止订阅失效后丢失节点信息 -
版本兼容性：关注服务端更新（如 Xray-core v1.8.0+ 弃用 XTLS Old），及时更新 Shadowrocket 至 TestFlight 最新版
Shadowrocket 的错误代码虽多源于系统底层，但绝大多数问题集中在 TLS 证书配置、时间同步和传输层参数匹配三个维度，掌握「分层排查法」（先网络层、再传输层、最后协议层），可快速定位 90% 以上的连接故障，对于持续存在的协议错误，建议对比服务端配置（如 Xray/V2Ray 的 access.log）进行双向验证。
