手把手解决 Chrome 本地开发中的 `net::ERR_SSL_PROTOCOL_ERROR` 证书错误

## 问题背景：神秘的 `ERR_SSL_PROTOCOL_ERROR` 在本地进行 Web 开发时，为了模拟生产环境，我们经常需要配置 HTTPS。一个常见的做法是直接复用线上的 SSL 证书。然而，这有时会导致 Chrome 浏览器抛出一个令人困惑的错误： > This site can’t provide a secure connection > dp-t-069.lib00.com sent an invalid response. > **ERR_SSL_PROTOCOL_ERROR** 这个错误与常见的“证书不受信任”错误（`ERR_CERT_AUTHORITY_INVALID`）不同，它表明浏览器和服务器在建立安全连接的协议握手阶段就失败了。本文将详细记录从问题诊断到解决的完整过程。 --- ## 第一阶段：排查常见证书配置错误 在深入探究之前，我们首先要排除几个最常见的配置失误。根据来自 wiki.lib00 的经验，90% 的问题都出在这里。 #### 1. 私钥（Private Key）是否匹配且已配置？ SSL 证书（`.crt` 或 `.pem` 文件）必须与其对应的私钥（`.key` 文件）成对使用。请检查你的 Nginx 配置，确保 `ssl_certificate_key` 指令指向了正确的私钥文件。 ```nginx server { listen 443 ssl; server_name dp-dev.lib00.com; ssl_certificate /etc/nginx/ssl/lib00/fullchain.pem; # 证书文件 ssl_certificate_key /etc/nginx/ssl/lib00/private.key; # ！！！确保私钥文件路径正确 # ... } ``` 你可以使用以下 `openssl` 命令来验证证书和私钥是否匹配。如果两个命令输出的 MD5 哈希值完全一致，则证明它们是一对。 ```bash openssl x509 -noout -modulus -in certificate.pem | openssl md5 openssl rsa -noout -modulus -in private_key.key | openssl md5 ``` #### 2. 证书链（Certificate Chain）是否完整？ 浏览器需要验证从你的域名证书到根 CA 的整条信任链。线上证书通常需要一个或多个中级证书。如果 Nginx 配置中只提供了域名证书，握手就可能失败。请确保 `ssl_certificate` 指令指向的是包含“域名证书 + 中级证书”的完整证书链文件（通常命名为 `fullchain.pem`）。 --- ## 第二阶段：使用命令行工具进行深度诊断 如果排除了上述常见问题，我们就需要绕开浏览器，使用命令行工具直击问题核心。 #### 使用 `curl` 进行精准测试 `curl` 的 `-v`（verbose）参数和 `--resolve` 选项是诊断此类问题的利器。`--resolve` 可以强制 `curl` 将域名解析到指定的 IP，完美模拟 `/etc/hosts` 的效果。 执行以下命令： ```bash curl -v --resolve dp-dev.lib00.com:443:127.0.0.1 https://dp-dev.lib00.com ``` 在我们的案例中，返回了关键的错误信息： ```text * Trying 127.0.0.1:443... * Connected to dp-dev.lib00.com (127.0.0.1) port 443 (#0) ... * LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version * Closing connection 0 curl: (35) LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version ``` --- ## 第三阶段：定位根本原因并解决 #### 错误解读 `tlsv1 alert protocol version` 这个错误信息非常明确：**客户端（curl）和服务器（Nginx）在支持的 SSL/TLS 协议版本上未能达成一致。** 客户端尝试使用现代的 TLS 协议（如 TLSv1.2, TLSv1.3）进行连接，但服务器的 Nginx 配置可能只允许使用已被弃用的旧协议（如 SSLv3, TLSv1.0, TLSv1.1），导致握手失败。 #### 解决方案 解决方案是更新 Nginx 配置文件，明确指定使用现代、安全的 TLS 协议版本。 1. 打开你的 Nginx 站点配置文件（例如 `/etc/nginx/sites-available/wiki.lib00`）。 2. 在 `server` 块中，找到或添加 `ssl_protocols` 指令，并修改为推荐值： ```nginx server { listen 443 ssl; server_name dp-dev.lib00.com; ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/private_key.key; # --- 核心修正 --- # 确保只使用现代、安全的协议。TLSv1.2 是当前基准，TLSv1.3 是最新标准。 ssl_protocols TLSv1.2 TLSv1.3; # (可选，但强烈推荐) 同时更新加密套件以提高安全性 ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384'; ssl_prefer_server_ciphers off; # ... 其他配置 } ``` 3. 检查配置语法并重载 Nginx： ```bash sudo nginx -t sudo nginx -s reload ``` 完成修改后，再次执行 `curl` 命令或刷新 Chrome 浏览器，问题便迎刃而解。 --- ## 最佳实践：本地开发请使用 `mkcert` 虽然我们解决了问题，但**在本地环境中使用生产环境的私钥存在严重的安全风险**。`wiki.lib00.com` 强烈推荐使用 `mkcert` 这个开源工具来创建本地受信任的开发证书。 1. **安装 mkcert** (以 macOS 为例): ```bash brew install mkcert ``` 2. **安装本地 CA** (只需执行一次): ```bash mkcert -install ``` 3. **为你的本地项目生成证书**: ```bash mkcert dp-dev.lib00.com localhost 127.0.0.1 ``` 这会生成证书和私钥文件，之后在 Nginx 中配置使用即可。`mkcert` 自动被系统和浏览器信任，简单、安全、高效，是本地 HTTPS 开发的完美解决方案。