常见坑

每一章对着一个报错或一个现象：先用最小的程序复现，再到源码里找它从哪一行来，最后给出修法和检查办法。前面几部分讲过的机制，这里只链过去。

复现环境都是 M2 Max、macOS 27、rustc 1.99.0、rustls 0.23.46、rustls-webpki 0.103.16；握手都在内存里或 127.0.0.1 上做，对照用本机的 OpenSSL 4.1.0。

provider 与 feature

1. Could not automatically determine the process-level CryptoProvider：依赖图里同时有 ring 和 aws-lc-rs，builder() 直接 panic。
2. 只开 ring，却编进了 aws-lc-rs：prefer-post-quantum 或某个依赖的默认 feature 把 aws-lc-rs 带进来，二进制大了约 700 KB。
3. install_default 第二次调用失败：返回的 Err 里是你传进去的 provider；测试里互相抢、晚装的配置静默不生效。
4. linker cc not found / failed to find tool：ring 和 aws-lc-sys 都要 C 编译器，不要 cmake；交叉编译还要配 AR_<target>。

证书与名字

5. invalid peer certificate: UnknownIssuer：中间证书没发、自签证书、空的根证书库，报的都是同一个错。
6. certificate not valid for name：IP 和 DNS 名字分开比，只看 SAN 不看 CN。
7. 内网 CA 的站点连不上：只用 webpki-roots 时要自己加根证书，或者换系统 / 平台校验器。
8. CaUsedAsEndEntity / UnknownRevocationStatus：openssl req -x509 生成的证书默认是 CA；中间证书的 EKU；只给了一部分 CRL。
9. certificate not valid yet / certificate expired：时钟为 0 只会报「还没生效」；测试里用固定时间的 TimeProvider。
10. no items found / peer sent no certificates：加密私钥被静默跳过，把私钥文件当证书读得到空链。
11. 跳过证书校验，中间人照样握手成功：空校验器连 CertificateVerify 签名也不验；固定叶子证书才是可用的替代。

驱动循环与缓冲

12. 握手卡住，没有任何报错：按 is_handshaking() 写循环，客户端最后一组消息还没发出去循环就退出了。
13. 出过一次错，之后永远是同一个错：连接出错后不能恢复，只能重建。
14. peer closed connection without sending TLS close_notify：对端没调 shutdown()；靠长度分帧区分「读完了」和「被截断」。
15. write 返回 Ok(0)，read_tls 报 received plaintext buffer full：发送 64 KiB、接收 16 KiB 两个上限，不会阻塞，只会返回 0 或报错。

握手与对端

16. 0-RTT 没生效，早期数据不见了：服务端默认不收早期数据，被拒时 write 照样返回成功，要看 is_early_data_accepted()。
17. received fatal alert: HandshakeFailure / ProtocolVersion：老服务器只有 RSA 密钥交换、CBC 或旧版本时，客户端只看到告警。
18. received fatal alert: AccessDenied：服务端按 SNI 找不到证书，客户端只看到 AccessDenied。