怎么在 Apache 中自定义 SSL 握手失败的报错页面

不能为 SSL 握手失败自定义错误页面，因为该失败发生在 TLS 协商早期、HTTP 协议尚未启动，Apache 无法生成 HTTP 响应，ErrorDocument 指令不生效；只能通过日志排查原因并优化配置确保握手成功。

不能在 Apache 中为 SSL 握手失败自定义错误页面。

SSL 握手失败发生在 TLS 连接建立的最早阶段——此时 TCP 连接刚建立，但尚未完成加密协商，HTTP 协议层甚至还没启动。Apache 的 ErrorDocument 指令只对已进入 HTTP 处理流程的请求生效（比如返回 404、500 等状态码），而握手失败时，连接被 OpenSSL 直接中断，Apache 根本不生成任何 HTTP 响应，也就无法触发 ErrorDocument 或返回任何 HTML 页面。

你看到的“SSL handshake failed”类错误，本质是客户端（浏览器、curl、小程序等）收不到有效 TLS 响应，通常表现为：

• 浏览器显示 NET::ERR_SSL_PROTOCOL_ERROR、ERR_SSL_VERSION_OR_CIPHER_MISMATCH 等
• curl 报错：SSL connect error、SSL routines:ssl3_get_record:wrong version number
• 小程序报 request:fail ssl hand shake error

这些都不是 Apache 返回的 HTTP 错误，而是客户端 TLS 栈主动终止连接的结果。

真正能做的只有两件事：

• 定位并修复握手失败原因

  • 开启详细 SSL 日志：在 Apache 配置中添加

    LogLevel info ssl:info

  • 查看 /var/log/apache2/error.log（Ubuntu）或 /var/log/httpd/error_log（CentOS）
  • 关键线索包括：
    • SSL_do_handshake() failed 或 SSL_accept() failed
    • error:1408A0C1（协议不匹配）、error:1407609C（明文请求）、error:14094410（证书问题）
    • no shared cipher、unknown protocol、bad certificate
  • 用 openssl errstr 1408A0C1 解析错误码含义

• 避免用户看到裸错，从外围改善体验

  • 确保证书链完整（含中间 CA），私钥权限正确（chmod 600）
  • 启用兼容的协议和密码套件（如保留 TLSv1.2，谨慎启用 TLSv1.3）
  • 检查系统时间准确（证书验证依赖时间）
  • 对于小程序或 App 客户端，在代码中捕获网络异常并提示友好文案，而非依赖服务端返回页面

换句话说：没有“SSL 握手失败页”这个概念，它不属于 HTTP 错误范畴。你能控制的，是让握手成功，而不是给失败兜底。