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

微信小程序 HTTPS 配置全流程:SSL 证书申请、Nginx 安装部署与握手报错排查

微信小程序 HTTPS 配置全流程:SSL 证书申请、Nginx 安装部署与握手报错排查 — 微信小程序 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',确认请求域名在列表中。

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 错误。

内容审核

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