微信小程序 HTTPS 配置 SSL CA 证书实战:证书链、Nginx 与 443 排查
问题背景与根因:小程序为什么卡在 HTTPS
微信小程序通过 wx.request 访问后端时,平台强制要求 HTTPS,且域名必须提前在“开发管理-开发设置-服务器域名”中配置为 request 合法域名。规则很严格:只支持 https,默认 443 端口,不能填 IP、localhost 或带路径,中国大陆主体的服务器域名还需完成 ICP 备案。很多“证书买了却调不通”的问题,原因往往在于链路中某一环不满足微信校验,而不是证书没签发。
最常见根因有六类:一是只部署了站点证书,未带中间证书,导致证书链不完整;二是证书 SAN 不含实际请求域名,或使用了不被微信后台接受的通配符写法;三是证书已过期,公网 TLS 证书最长有效期已缩短为 398 天,Let’s Encrypt 免费证书有效期为 90 天,“一年一装”早已过时;四是服务器仍开启 TLS 1.0/1.1 或弱套件;五是 ECS 安全组、云防火墙未放行 443;六是 CDN/WAF 回源证书与源站不一致,或 SNI 未正确配置。
先做一条最小化诊断,直接看证书链和协议版本:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts < /dev/null
输出中重点看 Verify return code 是否为 0、证书链是否包含中间 CA、Protocol 是否为 TLSv1.2 或 TLSv1.3。若返回 Verify return code: 21 (unable to verify the first certificate),基本可判定为中间证书缺失,而不是微信客户端“挑证书”。
前置检查与证书选型:域名、备案、CSR 一次做对
动手前先确认三件事:域名解析是否指向目标 ECS/CDN;域名是否已完成 ICP 备案;微信后台是否已添加 request 合法域名。命令检查解析与 80/443 连通性:
dig +short api.example.com
curl -I http://api.example.com
ss -lntp | grep -E ':80|:443'
证书选型上,小程序 API 用 DV 单域名证书即可,微信不会因为 OV/EV 给额外权重;EV 证书在主流浏览器中也不再展示绿色地址栏,不必为“小程序加分”购买高价 EV。需要覆盖多个子域时可买通配符证书,但通配符只匹配一级,*.example.com 不覆盖 api.test.example.com;且微信后台服务器域名通常要求填写具体域名,不能直接填 *.example.com。证书最长有效期 398 天,Let’s Encrypt 为 90 天,建议直接规划自动续期。
商业 CA 通常要求提交 CSR。生成私钥与 CSR 时把 SAN 一次写全,避免后续因缺少 www 或备用域名重签:
openssl req -new -newkey rsa:2048 -nodes -keyout api.example.com.key -out api.example.com.csr -subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example/CN=api.example.com' -addext 'subjectAltName=DNS:api.example.com,DNS:www.example.com'
检查 CSR 的 SAN 与公钥长度:
openssl req -in api.example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
openssl req -in api.example.com.csr -noout -verify
通过标准:SAN 包含所有实际请求域名,私钥权限为 600,CSR 签名验证成功。若使用 Let’s Encrypt,可跳过 CSR 手工步骤,直接进入下一节用 certbot 签发。
完整实操步骤:从签发到微信后台生效
第一步,放行 443。云厂商安全组入方向添加 TCP:443,源地址按业务填 0.0.0.0/0 或微信出口;系统防火墙同步放行:
sudo ufw allow 443/tcp
sudo firewall-cmd --add-service=https --permanent && sudo firewall-cmd --reload
第二步,签发证书。以 Let’s Encrypt webroot 为例,先把验证目录准备好,再执行:
sudo mkdir -p /var/www/html/.well-known/acme-challenge
sudo certbot certonly --webroot -w /var/www/html -d api.example.com --email ops@example.com --agree-tos --no-eff-email
成功后证书在 /etc/letsencrypt/live/api.example.com/fullchain.pem,私钥在 privkey.pem。商业证书则把签发邮件中的站点证书与中间 CA 按“站点证书在前、中间证书在后”合并:
cat api.example.com.crt intermediate.crt > fullchain.pem
sudo mkdir -p /etc/nginx/ssl/api.example.com
sudo cp fullchain.pem privkey.pem /etc/nginx/ssl/api.example.com/
sudo chmod 600 /etc/nginx/ssl/api.example.com/privkey.pem
第三步,写入 Nginx 配置并重载。不要只 reload 不检查,先跑 nginx -t:
sudo nginx -t
sudo systemctl reload nginx
第四步,微信后台配置。进入公众平台“开发管理-开发设置-服务器域名”,request 合法域名填 https://api.example.com,不要带端口、路径、通配符;保存后等待配置生效,开发者工具执行“清缓存并重新编译”,并关闭“不校验合法域名”选项。真机再测一次,因为 Android 与 iOS 的信任链和 TLS 能力并不完全一致。最后用 curl -I https://api.example.com/health 确认 200,且 http:// 返回 301 到 https。
配置示例:Nginx 与 Apache 的可执行模板
Nginx 推荐把 80 端口统一 301 到 HTTPS,443 只启用 TLS 1.2/1.3,证书必须指向 fullchain。以下配置可直接改域名和 upstream 后使用:
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/api.example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
add_header Strict-Transport-Security max-age=31536000 always;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
}
}
注意两个细节:ssl_certificate 用 fullchain,不是单张站点证书;http2 on; 适用于 Nginx 1.25.1 及以上,老版本可改为 listen 443 ssl http2;。如果使用 CDN,回源协议也要选 HTTPS,且回源证书同样要带中间链。
Apache 2.4 可用如下片段,SSLCertificateFile 直接指向 fullchain:
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5
SSLCertificateFile /etc/httpd/ssl/api.example.com/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/api.example.com/privkey.pem
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>
改完执行 apachectl configtest 再 systemctl reload httpd。不要在生产环境使用自签名证书,也不要只配 SSLCertificateFile 指向站点证书而漏掉中间 CA。
证书与服务对比:DV、OV、通配符怎么选
小程序场景优先看“是否被信任、链是否完整、能否自动续期”,而不是证书品牌堆料。对比如下:
| 类型 | 微信/浏览器信任 | 有效期 | 适用场景 | 参考成本 |
|---|---|---|---|---|
| 自签名证书 | 否 | 自定义 | 内网测试 | 0 元,不可上线 |
| Let’s Encrypt DV 单域名 | 是 | 90 天 | 小程序 API、测试、生产 | 0 元,自动续期 |
| 商业 DV 单域名 | 是 | 最长 398 天 | 生产 API | 约百元级/年 |
| 商业 OV | 是 | 最长 398 天 | 企业展示、合规 | 数百至千元/年 |
| 通配符 DV | 是 | 最长 398 天 | 多子域 | 约 600 元级/年 |
| 多域名 SAN | 是 | 最长 398 天 | 多域名 | 按域名数计价 |
说明:EV 证书已不再带来浏览器绿色地址栏,小程序也不会因 OV/EV 提升排名或跳过校验;DV 只要链完整、域名匹配、TLS 1.2+ 即可。通配符证书能降低多子域运维成本,但微信后台仍要填具体域名,且不能覆盖二级子域。公网证书最长 398 天,Let’s Encrypt 90 天,建议把续期检查阈值设为剩余 30 天。
若购买第三方“证书+配置”服务,常见报价参考:单纯配置服务 110 元,单域名证书+配置 115 元,通配符证书+配置 660 元;价格随服务商和验证类型变化,签约前确认是否包含证书链部署、301 跳转、续期提醒和回滚。
常见错误排查:真实报错与修复命令
下面这些报错在小程序 HTTPS 接入中出现频率最高,按“先链、再域名、再协议、最后网络”的顺序排查。
curl: (60) SSL certificate problem: unable to get local issuer certificate:缺少中间证书。把站点证书与 intermediate 合并为 fullchain,Nginx 的ssl_certificate指向 fullchain,然后nginx -t && systemctl reload nginx。Verify return code: 21 (unable to verify the first certificate):同上,证书链不完整。用openssl s_client -showcerts数证书张数,正常至少 2 张。NET::ERR_CERT_COMMON_NAME_INVALID或微信提示“此服务器的证书无效”:证书 SAN 不含请求域名。检查openssl x509 -in fullchain.pem -noout -ext subjectAltName,重签时把api.example.com写入 SAN。nginx: [emerg] cannot load certificate ... BIO_new_file() failed:路径错、权限不足或 SELinux 拦截。用namei -l /etc/nginx/ssl/api.example.com/fullchain.pem看权限,SELinux 环境执行chcon -t httpd_sys_content_t fullchain.pem。SSL_CTX_use_PrivateKey ... key values mismatch:证书与私钥不匹配。分别取 modulus 比对:openssl x509 -noout -modulus -in fullchain.pem | openssl md5与openssl rsa -noout -modulus -in privkey.pem | openssl md5,两值必须一致。request:fail ssl hand shake error:常见于 TLS 1.0/1.1、弱套件、SNI 缺失或手机时间错误。用openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2验证 TLS 1.2 握手。curl: (7) Failed to connect to api.example.com port 443: Connection refused:Nginx 未监听或安全组未放行。检查ss -lntp | grep :443与云安全组入方向 TCP:443。
排查时不要只看浏览器“能打开”,浏览器可能缓存了旧证书或走了不同 CDN 节点。以 openssl s_client 和微信真机结果为准。
效果验证与自动化续期:上线前必须跑完的检查
配置完成后,按下面顺序验收,任何一项失败都不要把域名填进微信后台。第一,验证证书链与协议:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts < /dev/null
openssl x509 -in /etc/nginx/ssl/api.example.com/fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
期望看到 Verify return code: 0 (ok)、Protocol : TLSv1.3 或 TLSv1.2,且 SAN 包含实际域名。第二,验证 HTTP 跳转与业务响应:
curl -I http://api.example.com
curl -vI https://api.example.com/health
第一条应返回 301 Moved Permanently 且 Location 为 https;第二条应出现 SSL certificate verify ok 和 HTTP/2 200。第三,微信侧验证:开发者工具关闭“不校验合法域名”,真机打开调试模式,观察 wx.request 是否还有 request:fail;同时确认后台 request 合法域名与实际请求完全一致,不能带端口和路径。
第四,自动化续期。Let’s Encrypt 只有 90 天,必须用 timer 或 cron 自动续:
sudo certbot renew --dry-run
sudo certbot renew --deploy-hook 'systemctl reload nginx'
用 systemctl list-timers | grep certbot 确认定时器存在;商业证书最长 398 天,也应在剩余 30 天时告警。可加一条到期检查:openssl s_client -connect api.example.com:443 -servername api.example.com < /dev/null | openssl x509 -noout -enddate,把结果接入监控。最后建议用 SSL Labs 或内部扫描确认无 TLS 1.0/1.1、无弱套件、无证书链缺失。
常见问题
微信小程序必须使用 OV 或 EV 证书吗?
不需要。微信校验的是证书是否由受信任 CA 签发、域名是否匹配、证书链是否完整、TLS 是否达到 1.2 及以上。DV 证书只要满足这些条件即可正常请求;EV 证书在主流浏览器已不展示绿色地址栏,也不会让小程序跳过合法域名校验。
浏览器能打开,小程序却报 ssl hand shake error,为什么?
优先查证书链、TLS 版本和 SNI。用 openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 看握手;若只有 TLS 1.3 正常而 TLS 1.2 失败,老 Android 微信就会报握手错误。其次检查中间证书是否缺失、手机系统时间是否准确、CDN 回源是否用了自签名证书。
通配符证书能否在微信后台直接填 *.example.com?
通常不能。微信服务器域名要求填写具体域名,不能使用 IP、localhost、端口、路径或通配符;通配符证书只解决证书覆盖问题,后台仍应填 https://api.example.com。另外 *.example.com 只覆盖一级子域,不覆盖 api.test.example.com。
Let’s Encrypt 只有 90 天,会不会很麻烦?
不会,前提是自动化。用 certbot 的 systemd timer 或 cron 每天检查续期,配合 --deploy-hook 'systemctl reload nginx' 重载服务;上线前执行 certbot renew --dry-run。不要手工到期前替换,否则容易漏掉证书链和私钥权限。
证书链到底要部署哪些文件?
部署站点证书加中间证书,通常合并为 fullchain.pem,私钥单独放 privkey.pem。根证书一般不需要下发,也不建议把根证书塞进 fullchain。Nginx 的 ssl_certificate 指向 fullchain;Apache 2.4 的 SSLCertificateFile 也指向 fullchain。
HTTP 301 会不会影响小程序接口?
小程序请求本身应直接使用 https,不要依赖 301。301 主要给浏览器和 SEO 用;部分客户端在 301 后会把 POST 改成 GET,导致接口异常。API 场景若必须做跳转,优先考虑 308 保留方法和请求体,并在小程序端固定 https 域名。