uni.connectSocket iOS连接失败，证书校验严格导致

Question

在使用 `uni.connectSocket` 时，iOS 端常因证书校验严格导致 WebSocket 连接失败。iOS 系统对 HTTPS 及 WSS 证书要求较高，若服务器证书存在自签名、过期、域名不匹配或非可信 CA 颁发等问题，会直接中断连接，而 Android 可能仍可降级连接。此问题在真机调试时尤为明显，表现为连接超时或 `onError` 回调返回证书信任错误。解决需确保使用有效、完整链的 SSL 证书，并在 Apple ATS 配置中合规。

Answer 1

1. 问题背景与现象描述

在使用 uni.connectSocket 建立 WebSocket 安全连接（WSS）时，iOS 平台相较于 Android 表现出更高的安全校验标准。开发者常反馈：同一套代码在 Android 设备上可正常连接 WSS 服务，但在 iOS 真机运行时出现连接失败、超时或触发 onError 回调。

典型错误信息包括：

• WebSocket connection failed with error: Invalid SSL certificate
• CFNetwork SSLHandshake failed (-9806)
• NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9802)

这些提示均指向底层 TLS 握手阶段被系统中断，核心原因在于 iOS 对 SSL/TLS 证书的严格校验机制。

2. iOS 安全机制深度解析：ATS 与 Trust Store

iOS 自 iOS 9 起引入了 App Transport Security（ATS），默认强制要求所有网络请求使用 HTTPS，并对证书链完整性、加密算法强度、证书有效期等进行严格验证。即使开发者通过 H5 或 WebView 方式发起请求，该策略依然生效。

ATS 的主要校验维度如下表所示：

校验项	ATS 要求	常见违规情况
证书签发机构	必须由 Apple 信任的根 CA 颁发	自签名证书、私有 CA 签发
证书链完整性	需包含中间证书，形成完整信任链	仅部署终端实体证书
域名匹配	CN 或 SAN 必须精确匹配主机名	使用 IP 地址连接、通配符未覆盖子域
证书有效期	必须在有效期内	过期或尚未生效
加密套件	支持 TLS 1.2+，禁用弱算法	使用 RC4、SHA-1、NULL 密码套件

此外，iOS 内置的信任存储（Trust Store）更新频率较低，某些新近被主流浏览器信任的 CA 可能尚未纳入 iOS 系统信任列表，导致连接失败。

3. 分析过程：如何定位证书问题

面对 uni.connectSocket 在 iOS 上的 WSS 连接异常，建议按以下流程排查：

1. 确认是否为 WSS 协议（而非 WS）
2. 使用 Safari 浏览器访问目标 WSS URL 的 HTTPS 页面，查看地址栏是否有锁形图标及“此网站不安全”警告
3. 通过 macOS 的 Keychain Access 工具手动导入并验证服务器证书链
4. 使用在线工具如 SSL Labs SSL Test 检测服务器配置得分
5. 抓包分析 TLS 握手过程（可用 Charles Proxy 或 Wireshark）
6. 检查 uni-app 编译后的原生日志输出（Xcode 控制台）
7. 比对 Android 与 iOS 的实际行为差异，判断是否为平台级限制

例如，在 Xcode 日志中若出现 NSURLSessionTask finished with error - code: -9813，则明确表示证书不受信任。

4. 解决方案：从开发到运维的多维应对

针对不同场景，提供以下几种可行路径：

4.1 使用合规的公共 CA 证书

推荐使用 Let's Encrypt、DigiCert、Sectigo 等广受信任的 CA 提供的免费或商业证书。确保部署时包含完整的证书链文件（如 fullchain.pem），避免遗漏中间证书。

# 示例：Nginx 配置完整证书链
server {
    listen 443 ssl;
    server_name wss.example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
}

4.2 配置 ATS 白名单（仅限调试）

在 manifest.json 中配置 app-plus 的 distribute 节点，临时放宽 ATS 限制：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "cfbundleurltypes": [],
        "usesAppleSignIn": false,
        "backgroundModes": [],
        "entitlements": {
          "aps-environment": "development"
        },
        "description": "",
        "UIRequiresFullScreen": true,
        "UIStatusBarStyle": "UIStatusBarStyleDefault",
        "minimumAge": "4",
        "ATS": {
          "NSAllowsArbitraryLoads": true,
          "NSExceptionDomains": {
            "wss.example.com": {
              "NSExceptionMinimumTLSVersion": "TLSv1.2",
              "NSExceptionRequiresForwardSecrecy": false,
              "NSIncludesSubdomains": true
            }
          }
        }
      }
    }
  }
}

注意：NSAllowsArbitraryLoads 不应长期开启，否则可能影响 App Store 审核。

5. 架构设计层面的优化建议

为保障跨平台兼容性与未来可维护性，建议在系统架构中加入以下设计原则：

graph TD A[客户端 uni.connectSocket] --> B{目标协议} B -->|WSS| C[负载均衡器] C --> D[证书统一管理] D --> E[自动续期 Let's Encrypt] D --> F[OCSP Stapling 启用] C --> G[后端 WebSocket 服务] B -->|WS| H[仅限内网调试] style A fill:#f9f,stroke:#333 style G fill:#bbf,stroke:#333

通过将证书管理集中于边缘层（如 Nginx、ALB、CDN），实现前端透明化升级，降低客户端耦合度。