微信小程序 HTTPS 配置全流程:SSL 证书申请、Nginx 安装部署与握手报错排查
一、小程序 HTTPS 报错的真实根因
微信小程序的网络请求(wx.request、wx.uploadFile、wx.connectSocket)在开发者工具与真机上都强制走 HTTPS,并对服务端证书做一整套硬性校验:必须是受信任 CA 签发的证书、必须下发完整证书链、必须支持 TLS 1.2 及以上、域名必须完成 ICP 备案、端口只允许 443。很多用户以为“买了证书装上就行”,结果依然报错,根因通常落在下面几类:
- 使用自签证书或内部 CA 证书,系统信任库不认,报
net::ERR_CERT_AUTHORITY_INVALID。 - 只部署了域名证书,没有拼接中间 CA(Intermediate CA)。PC 浏览器因缓存能打开,但 iOS/Android 真机握手失败,小程序报
request:fail ssl handshake failed。 - 服务端仍开启 TLS 1.0/1.1,或只配置 RC4、3DES 等弱套件,被微信客户端直接拒绝。
- 证书 SAN 与请求域名不一致,例如用
*.example.com去请求m.api.example.com,报ERR_CERT_COMMON_NAME_INVALID。 - 域名未备案,或未在小程序后台“开发设置 – 服务器域名”中登记,报“不在以下 request 合法域名列表中”。
- 证书已过期,或服务器系统时间偏差过大,报
ERR_CERT_DATE_INVALID。
排错顺序建议固定为:先用 openssl s_client -connect example.com:443 -servername example.com -showcerts 看链是否完整、协商出的协议版本;再核对 SAN 列表与有效期;最后才去查小程序后台配置。这三步做完,绝大多数“配了 HTTPS 还是不行”的问题都能定位到具体一层。
二、申请前的四项准备与 CSR 生成
动手前先把四件事做完:域名完成 ICP 备案(小程序硬性要求);A 记录解析到服务器公网 IP,用 dig +short example.com 确认;安全组与防火墙放行 80/443(80 端口用于 HTTP-01 验证与跳转);确定证书类型——只做接口的选 DV 单域名,子域多的选通配符,需要展示企业主体的选 OV。
私钥与 CSR 必须在自己的服务器上生成,不要使用服务商代生成的私钥,否则等于把私钥交给了第三方。RSA 2048 兼容性最好;ECDSA P-256 握手更快,但 Android 7 以下老设备可能不支持,可用双证书方案。
# RSA 2048:私钥 + CSR,SAN 一次写全,避免后续补域名重新签发
openssl genrsa -out example.com.key 2048
openssl req -new -key example.com.key -out example.com.csr
-subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Tech Co.,Ltd/CN=example.com'
-addext 'subjectAltName=DNS:example.com,DNS:www.example.com,DNS:m.example.com'
# ECDSA P-256(可选)
openssl ecparam -genkey -name prime256v1 -out example.com.key
openssl req -new -key example.com.key -out example.com.csr
-subj '/CN=example.com' -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
# 自检:确认 CN 与 SAN 写对了
openssl req -in example.com.csr -noout -text | grep -A2 'Subject Alternative Name'
chmod 600 example.com.key
注意 CN 字段最长 64 字符,超过就只能靠 SAN 承载;通配符只能写成 *.example.com 这种一级形式,写成 *.api.example.com 是否被接受取决于 CA 政策,采购前务必确认。CSR 里的信息一旦提交就无法修改,填错只能重新签发,所以自检这一步不要省。
三、SSL 证书申请:商业 CA 与免费 ACME 两条路径
商业 CA 流程:提交 CSR → 选择验证方式 → CA 签发 → 下载 Nginx 格式证书包(必须含 fullchain)。DV 证书一般 10 分钟内自动签发;OV 与 OV 通配符需要营业执照、企业电话回访,通常 1-3 个工作日。域名验证有三种方式:DNS TXT(最稳,支持通配符)、HTTP 文件(需 80 端口可访问)、管理员邮箱。用 DNS 验证时把 CA 给的 TXT 记录加到 _dnsauth.example.com,用 dig +short TXT _dnsauth.example.com 确认生效后再点验证。
免费路径用 acme.sh(Let’s Encrypt / ZeroSSL 均可,90 天有效期,靠自动续期维持):
curl https://get.acme.sh | sh -s email=ops@example.com
# 方式一:webroot 文件验证
acme.sh --issue -d example.com -d www.example.com --webroot /www/wwwroot/example.com
# 方式二:DNS API(以阿里云为例),可签发通配符
export Ali_Key='LTAI5t****' Ali_Secret='****'
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com'
# 安装证书到 Nginx 目录并自动 reload
acme.sh --install-cert -d example.com
--key-file /www/server/panel/vhost/cert/example.com/privkey.pem
--fullchain-file /www/server/panel/vhost/cert/example.com/fullchain.pem
--reloadcmd 'nginx -s reload'
certbot 用户可用 certbot certonly --webroot -w /www/wwwroot/example.com -d example.com -d www.example.com,续期交给 certbot renew 的 systemd timer。无论走哪条路径,最终落盘给 Nginx 的一定是 fullchain.pem(域名证书 + 中间证书),只放域名证书是后续所有握手失败的源头。
四、证书安装与 Nginx 配置示例
把 fullchain.pem 与 privkey.pem 上传到服务器(宝塔面板的站点证书目录是 /www/server/panel/vhost/cert/域名/),然后写入如下配置,可直接复制修改域名与路径:
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on; # nginx < 1.25.1 改写为 listen 443 ssl http2;
server_name example.com www.example.com;
ssl_certificate /www/server/panel/vhost/cert/example.com/fullchain.pem;
ssl_certificate_key /www/server/panel/vhost/cert/example.com/privkey.pem;
ssl_trusted_certificate /www/server/panel/vhost/cert/example.com/chain.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
add_header X-Content-Type-Options nosniff always;
root /www/wwwroot/example.com;
index index.php index.html;
}
执行 nginx -t 通过后再 nginx -s reload。Apache 对应三行:SSLCertificateFile 指向域名证书、SSLCertificateKeyFile 指向私钥、SSLCertificateChainFile 指向中间证书(2.4.8 之后也可把链直接拼进 SSLCertificateFile)。HSTS 头建议在 HTTPS 稳定运行一周后再启用,否则一旦需要回退 HTTP,用户在 max-age 有效期内会直接无法访问。
五、证书选型对比:DV、OV、通配符与品牌价格
先明确两个概念:DV 只验证域名控制权,签发快、价格低,适合小程序接口域名;OV 需核验企业主体,证书详情里带公司名,适合对外官网与支付回调域名。通配符(Wildcard)只覆盖同一级子域,*.example.com 能匹配 api.example.com,但匹配不了 m.api.example.com。
| 品牌 / 产品 | 验证类型 | 覆盖范围 | 参考价(元/年) | 适用场景 |
|---|---|---|---|---|
| AlphaSSL DV 单域名 | DV | 1 个域名 | 350 | 测试环境、个人接口 |
| RapidSSL DV 单域名 | DV | 1 个域名 | 400 | 小程序后端 API |
| Comodo(Sectigo)DV 单域名 | DV | 1 个域名 | 700 | 中小型业务系统 |
| GeoTrust DV 单域名 | DV | 1 个域名 | 800 | 对 CA 品牌有要求 |
| Thawte DV 单域名 | DV | 1 个域名 | 900 | 同上 |
| GlobalSign DV 单域名 | DV | 1 个域名 | 1800 | 金融、强合规场景 |
| AlphaSSL 通配符 | DV | *.example.com | 700 | 多子域共用 |
| RapidSSL 通配符 | DV | *.example.com | 1200 | 多子域、多环境 |
| Comodo(Sectigo)通配符 | DV | *.example.com | 1800 | 中大型业务 |
| Thawte DV 通配符 | DV | *.example.com | 2000 | 品牌 + 多子域 |
| GeoTrust DV 通配符 | DV | *.example.com | 2100 | 品牌 + 多子域 |
| GlobalSign DV 通配符 | DV | *.example.com | 6800 | 高预算、强合规 |
| GlobalSign OV 单域名 | OV | 1 个域名 | 3800 | 企业官网、支付回调 |
| GeoTrust OV 通配符 | OV | *.example.com | 4800 | 企业多子域统一入口 |
几点提醒:第一,价格随渠道与年限浮动,上表为单年版参考价;多年期购买通常是按年签发、到期重签,不是“一张证书用三年”。第二,Comodo 的 CA 业务已被 Sectigo 收购,市面上的“Comodo 证书”实际签发主体是 Sectigo,看证书 Issuer 字段即可确认。第三,EV 证书在主流浏览器中早已取消绿色地址栏,小程序场景没有任何额外收益,不建议采购。第四,自 2026 年 3 月 15 日起,公有信任 TLS 证书最长有效期已从 398 天降为 200 天,采购时必须同步规划自动续期,否则再贵的证书也会在半年内过期。
六、常见错误排查:真实报错与修复命令
1. request:fail ssl handshake failed / net::ERR_CERT_AUTHORITY_INVALID:九成是中间证书缺失。验证命令:
openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
返回 1 说明只下发了叶子证书,必须改用 fullchain 配置;修复后应返回 2 或 3。
2. unable to get local issuer certificate:链顺序错误或根证书过期。openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem cert.pem,若仍报错,重新下载 CA 提供的完整链(旧的 AddTrust 根证书过期是经典案例)。
3. ERR_CERT_COMMON_NAME_INVALID:域名与 SAN 不匹配。查看实际 SAN:openssl x509 -in fullchain.pem -noout -text | grep -A1 'Subject Alternative Name',确认请求域名在列表中。
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- HTTPS配置 · SSL证书安装服务(各种服务器)
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
- APP/小程序 HTTPS · SSL网站加密证书 · CA证书配置
4. 不在以下 request 合法域名列表中:这不是证书问题。去小程序后台“开发管理 – 开发设置 – 服务器域名”添加,域名必须已备案、不能带端口与路径、不能是 IP 地址。
5. ERR_SSL_PROTOCOL_ERROR / handshake failure:协议或套件不匹配。分别用 openssl s_client -connect example.com:443 -tls1_2 与 -tls1_3 测试,若只开了 TLS 1.3 而客户端是 Android 6,就会直接失败;低版本微信基础库同样只支持到 TLS 1.2。
6. ERR_CERT_DATE_INVALID:证书过期或服务器时间错误。先 date -u 校时(timedatectl set-ntp true),再用 openssl x509 -in fullchain.pem -noout -dates 查看 notAfter。
7. Mixed Content:页面已是 HTTPS,但引用了 http 的图片/JS,控制台报 Mixed Content: The page at 'https://...' was loaded over HTTPS, but requested an insecure resource,需把资源地址改为 https 或协议相对路径。
七、配置完成后的效果验证清单
按下面顺序逐项验证,全部通过再交付:
# 1. 状态码与协议版本
curl -I https://example.com
curl -sI --http2 https://example.com | head -n1
# 2. 协商出的协议与套件
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher'
# 3. 确认 TLS1.0 已被拒绝(应出现 alert handshake failure)
openssl s_client -connect example.com:443 -servername example.com -tls1 </dev/null 2>&1 | grep -i 'alert|failure'
# 4. 有效期与 SAN
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -dates -ext subjectAltName
# 5. 证书链完整性(应为 2 或 3)
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
再用 SSL Labs 做整体评级:curl 'https://api.ssllabs.com/api/v3/analyze?host=example.com&publish=off&all=done',返回 JSON 中的 endpoints[0].grade 应为 A 或 A+;若出现 Chain issues: Incomplete,就是中间证书没配好。
最后在微信侧验证:取消开发者工具“详情 – 本地设置 – 不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”的勾选后重新编译,再用真机预览走一遍 wx.request、wx.uploadFile 与图片加载。只有真机通过才算真正完成——开发者工具对证书链的宽容度远高于真机,这是最常见的“工具里好好的,上线就挂”的原因。
八、证书续费与到期监控(200 天有效期时代)
有效期规则已经变了:CA/Browser Forum SC-081 落地后,公有信任 TLS 证书最长有效期自 2026 年 3 月 15 日起由 398 天降为 200 天,2027 年 3 月 15 日起降为 100 天,2029 年 3 月 15 日起降为 47 天;Let’s Encrypt 免费证书仍为 90 天。这意味着“一年装一次证书”的做法彻底失效,必须自动化。
acme.sh 安装时会自动写入 crontab(crontab -l | grep acme 可查),每日检查并在到期前 30 天续签;certbot 用 systemctl list-timers | grep certbot 确认 timer 已启用。商业证书没有 ACME 接口的,用脚本加告警兜底:
#!/bin/bash
DOMAIN='example.com'
END=$(echo | openssl s_client -servername "$DOMAIN" -connect "$DOMAIN":443 2>/dev/null
| openssl x509 -noout -enddate | cut -d= -f2)
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
echo "$DOMAIN 证书剩余 $DAYS 天"
if [ "$DAYS" -lt 15 ]; then
echo "SSL 证书将于 $END 到期,请立即续签" | mail -s "[告警] $DOMAIN SSL 到期" ops@example.com
fi
保存为 /etc/cron.daily/ssl-check 并 chmod +x 即可。换证流程固定为:备份旧证书 → 上传新 fullchain 与私钥 → nginx -t → nginx -s reload → 重跑第七节验证命令。切勿只覆盖文件不 reload,Nginx 会继续使用内存中的旧证书直到下次重启,这类“明明换了证书还报过期”的故障非常常见。
常见问题
小程序必须用付费证书吗?免费的 Let’s Encrypt 行不行?
行。微信校验的是证书是否由受信任 CA 签发、证书链是否完整、是否支持 TLS 1.2 及以上、域名是否备案,与证书价格无关。Let’s Encrypt、ZeroSSL 等免费证书完全可用,只是有效期 90 天,必须配置自动续期,否则到期当天小程序接口会全线报错。
买了通配符证书,为什么 m.api.example.com 还是报证书不匹配?
通配符只覆盖同一级子域。*.example.com 能匹配 api.example.com,但不能匹配 m.api.example.com。多级子域需要为该级单独签发 *.api.example.com,或改用多域名(SAN)证书把这些域名全部列进去。
浏览器打开正常,小程序却报 ssl handshake failed,问题在哪?
优先查三点:一是中间证书是否缺失(用 openssl s_client -showcerts 数证书条数);二是服务端是否还开着 TLS 1.0/1.1 或只配了弱套件;三是证书链顺序是否颠倒。浏览器有缓存和 AIA 自动补链能力,真机没有,所以问题只在真机暴露。
证书最长有效期到底是多久?
398 天已是历史。按 CA/Browser Forum SC-081,2026 年 3 月 15 日起公有信任 TLS 证书最长有效期为 200 天,2027 年 3 月 15 日起为 100 天,2029 年 3 月 15 日起为 47 天。采购多年期套餐时,实际仍是按年(未来按更短周期)重签,必须配合自动续期方案。
小程序可以用 IP 地址或 443 以外的端口访问吗?
不行。小程序服务器域名必须是已备案的域名,不支持 IP 地址,不支持自定义端口,只允许 443(HTTPS)与 80(HTTP,仅用于跳转)。域名也不能带路径,例如 https://example.com/api 只能填 https://example.com。
证书过期了如何紧急恢复?
立即重新签发(免费证书重跑 acme.sh –issue,商业证书走加急重签),拿到新的 fullchain 与私钥后成对替换,nginx -t 通过再 nginx -s reload,随后用第七节的命令验证有效期与链完整性。注意私钥与证书必须成对替换,只换其中一个会导致 key values mismatch 错误。