跳到主要内容
SSL 证书付费服务

微信小程序 HTTPS 配置 SSL CA 证书实战:证书链、Nginx 与 443 排查

微信小程序 HTTPS 配置 SSL CA 证书实战:证书链、Nginx 与 443 排查 — 微信小程序 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 域名。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。