SSL 错误 WRONG_VERSION_NUMBER 的解决方法

问题描述

当尝试通过 HTTPS 进行 POST 请求时，可能会遇到以下错误：

Error: write EPROTO 34557064:error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER:../../third_party/boringssl/src/ssl/tls_record.cc:242:

这个 SSL 错误通常表明客户端和服务器之间的 SSL/TLS 版本不匹配，或者通信双方在 SSL/TLS 协商过程中出现了协议版本不一致的问题。

常见原因及解决方法

1. HTTPS 与 HTTP 协议混淆

最常见的原因是错误地使用了 HTTPS 协议访问仅支持 HTTP 的服务。

WARNING

确保使用正确的协议：开发环境通常使用 HTTP，而生产环境使用 HTTPS

// 错误：使用 HTTPS 访问本地开发服务器
// https://localhost:3000/api/users

// 正确：开发环境使用 HTTP
http://localhost:3000/api/users

2. Postman 中的重定向设置

当服务器返回 302 重定向时，Postman 的自动重定向功能可能导致此错误。

解决方法

在 Postman 设置中关闭 "Automatically follow redirects" 选项

1. 打开 Postman 设置 (Settings)
2. 在 General 标签页中
3. 取消勾选 "Automatically follow redirects"

3. 错误的请求头配置

手动设置了 Host 头可能导致 SSL 版本协商问题。

// 避免手动设置 Host 头
// 错误示例：
headers: {
  'Host': 'custom-value'  // 手动设置可能导致问题
}

// 正确做法：让客户端自动计算 Host 值
headers: {
  'Content-Type': 'application/json'
}

4. Nginx 配置问题

后端服务器配置不当也可能导致此错误，特别是在使用 Nginx 作为反向代理时。

# 错误配置：缺少 ssl 指令
listen 443;

# 正确配置：明确指定 ssl
listen 443 ssl;
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;

5. SSL 证书验证问题

在开发和测试环境中，可以暂时关闭 SSL 证书验证（生产环境不推荐）。

安全提示

仅在开发和测试环境中禁用 SSL 验证，生产环境应始终保持验证开启

在 Postman 中：

1. 进入 Settings → General
2. 关闭 "SSL certificate verification"

6. 证书端口配置

在 Postman 中配置证书时，需要明确指定端口号，即使它是默认的 443 端口。

INFO

即使端口字段显示默认值 443，也需要手动输入以确保配置生效

系统化排查步骤

当遇到 WRONG_VERSION_NUMBER 错误时，建议按以下顺序排查：

1. 确认协议是否正确：检查是否误用 HTTPS 访问 HTTP 服务
2. 验证服务器配置：确保服务器正确配置了 SSL/TLS
3. 检查客户端设置：确认客户端工具（如 Postman）的 SSL 相关设置
4. 审查请求头：避免手动设置可能干扰 SSL 协商的头部信息
5. 测试网络环境：排除代理或防火墙导致的协议干扰

总结

WRONG_VERSION_NUMBER 错误通常源于 SSL/TLS 协议版本不匹配或配置问题。通过系统化地检查协议使用、服务器配置和客户端设置，大多数情况下可以快速定位并解决这个问题。在开发环境中，确保使用正确的协议（HTTP）访问本地服务；在生产环境中，则需仔细验证 SSL/TLS 配置的正确性。