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

微信小程序 HTTPS 与 SSL 证书申请、配置全流程实战(含 Nginx/Apache/Tomcat/IIS 示例与报错排查)

微信小程序 HTTPS 与 SSL 证书申请、配置全流程实战(含 Nginx/Apache/Tomcat/IIS 示例与报错排查) — 微信小程序 HTTPS 与 SSL 证书申请、配置全流程实战(含 Nginx/Apache/Tomcat/IIS 示例与报错排查)

一、微信小程序为什么必须走 HTTPS:问题背景与根因

微信小程序的网络请求全部走 wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket,这些 API 在体验版与正式版中只允许访问已在微信公众平台配置的合法域名,并且强制使用 HTTPS。很多团队在开发者工具里勾选了“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”,本地联调一切正常,一上真机就报 request:fail ssl hand shake error。真正的原因通常集中在以下五类:

1)平台强制校验。微信客户端启动时会拉取域名白名单,请求域名不在白名单内直接拒绝;域名必须是已完成 ICP 备案的域名,不支持 IP 地址、不支持 localhost、不支持非标准端口(默认 443),也不接受自签名证书与私有 CA 签发的证书。

2)TLS 版本过低。微信客户端要求 TLS 1.2 及以上。TLS 1.0/1.1 已被主流 CA、浏览器与微信客户端弃用,仍在启用旧协议的服务器会直接握手失败。

3)证书链不完整。只部署了站点证书而漏掉中间证书时,iOS 往往能自动补链而正常,部分安卓机型(尤其 7.0 以下)不会,于是出现“iOS 正常、安卓报错”的经典现象。这是小程序 HTTPS 故障中占比最高的一类。

4)域名不匹配。证书的 SAN 字段未包含实际请求域名,例如给 api.example.com 申请了只含 www.example.com 的证书,或通配符 *.example.com 试图覆盖 a.api.example.com。

5)证书过期。自 2020 年 9 月 1 日起,CA/Browser Forum 规定公开信任的 SSL/TLS 证书单张有效期最长 398 天(此前为 825 天),Let’s Encrypt 免费证书有效期为 90 天。这意味着一年至少需要续签一次,免费证书一年要续签 4 次以上,任何一次漏续都会导致小程序全量请求失败。

因此,微信小程序 HTTPS 问题的本质不是“买一张证书”,而是“选对证书类型 + 生成正确 CSR + 部署完整证书链 + 开启 TLS 1.2/1.3 + 配置域名白名单 + 建立自动续期机制”这条完整链路。下面按顺序给出可直接执行的实操步骤。

二、证书选型与 CSR 生成:从申请到签发的完整实操

小程序后端 API 域名绝大多数场景使用 DV(域名验证型)即可,签发快(通常 10 分钟至 2 小时,DNS 验证最快);涉及支付、金融、企业品牌展示的域名可选用 OV(企业验证型),需提交营业执照,审核 1–3 个工作日;EV(增强验证型)主要用于 PC 站点展示企业名称,小程序端并不因 EV 获得任何额外能力,不必为小程序强行上 EV。

选型维度只有三个:域名数量(单域名 / 通配符 / 多域名 SAN)、验证等级(DV / OV / EV)、有效期(单张最长 398 天)。注意:市面上宣传的“2 年期、3 年期证书”并非单张证书有效期真的 2 年,而是多年订阅合同 + 到期自动重签,每次实际签发的证书有效期仍在 398 天以内;如需真正长期有效的证书,只能使用企业私有 CA 自签,但自签证书微信小程序不信任。

下面用 OpenSSL 生成私钥与 CSR(必须带 SAN,CN 字段已不被主流客户端采纳):

# 1. 生成 2048 位 RSA 私钥(也可用 ECDSA P-256,体积更小、握手更快)
openssl genrsa -out example.com.key 2048
chmod 600 example.com.key

# 2. 生成 CSR,必须显式写入 subjectAltName
openssl req -new -key example.com.key -out example.com.csr 
  -subj "/C=CN/ST=Guangdong/L=Shenzhen/O=Example Co., Ltd./CN=api.example.com" 
  -addext "subjectAltName=DNS:api.example.com,DNS:*.api.example.com"

# 3. 校验 CSR 内容是否正确
openssl req -in example.com.csr -noout -text | grep -A2 "Subject Alternative Name"

# 4. 检查私钥是否完好
openssl rsa -in example.com.key -check -noout

如果不想手动处理 CSR,可用 ACME 客户端全自动签发与部署。Let’s Encrypt 证书有效期 90 天,必须配合自动续期:

# certbot(webroot 模式,需 80 端口可访问)
certbot certonly --webroot -w /var/www/html 
  -d api.example.com -d www.api.example.com 
  --email ops@example.com --agree-tos -n

# acme.sh(支持 DNS API 自动验证,适合通配符)
curl https://get.acme.sh | sh
~/.acme.sh/acme.sh --issue -d example.com -d "*.example.com" --dns dns_ali

签发完成后,CA 会返回两个文件:站点证书与中间证书。部署时必须把它们按“站点证书在前、中间证书在后”的顺序合并成 fullchain.pem,且不要放入根证书(放了会导致部分客户端校验失败)。合并命令:

cat example.com.crt intermediate.crt > fullchain.pem
openssl verify -CAfile chain.pem -untrusted intermediate.crt example.com.crt

三、四大 Web 服务器证书配置示例(Nginx / Apache / Tomcat / IIS)

Nginx 是最常见的部署方式,关键是 ssl_certificate 指向 fullchain,ssl_trusted_certificate 指向 chain 以支持 OCSP Stapling:

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    ssl_certificate         /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key     /etc/nginx/ssl/example.com.key;
    ssl_trusted_certificate /etc/nginx/ssl/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;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Apache(2.4.8+ 推荐用 SSLCertificateFile 同时包含站点证书与中间证书):

<VirtualHost *:443>
    ServerName api.example.com
    SSLEngine on
    SSLCertificateFile      /etc/httpd/ssl/fullchain.crt
    SSLCertificateKeyFile   /etc/httpd/ssl/example.com.key
    SSLProtocol -all +TLSv1.2 +TLSv1.3
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
    SSLHonorCipherOrder off
</VirtualHost>

Tomcat(8.5 及以上可直接使用 PEM,无需再转 JKS):

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3">
    <Certificate certificateFile="/opt/ssl/fullchain.pem"
                 certificateKeyFile="/opt/ssl/example.com.key"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

IIS 的流程是:先在“服务器证书”中导入含私钥的 .pfx(OpenSSL 可用 openssl pkcs12 -export -out example.pfx -inkey example.com.key -in fullchain.pem 生成),再到站点“绑定”中添加 https、端口 443,并勾选“服务器名称指示(SNI)”——同一台服务器承载多个域名时若不勾选 SNI,客户端可能拿到错误域名的证书,小程序直接报域名不匹配。中间证书需导入“中间证书颁发机构”存储。

四、全站 HTTP→HTTPS 跳转与微信后台域名白名单配置

证书装好只是第一步,还要保证所有 HTTP 请求 301 到 HTTPS,否则小程序内嵌 web-view 或历史接口回调仍会走明文。Nginx 的写法是在 80 端口 server 块里直接返回 301:

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

Apache 用 Redirect permanent / https://api.example.com/;Tomcat 可在 conf/web.xml 末尾追加 <security-constraint> 配合 <user-data-constraint><transport-guarantee>CONFIDENTIAL</transport-guarantee></user-data-constraint>,但更推荐在前置 Nginx 做跳转,避免应用层额外开销。

接着在微信公众平台配置域名白名单:登录 mp.weixin.qq.com → 开发 → 开发管理 → 开发设置 → 服务器域名。要点如下:

① request 合法域名填写形如 https://api.example.com 的完整 HTTPS 地址,不能带路径、不能带端口、不能填 IP;② uploadFile / downloadFile 合法域名与 socket 合法域名(wss://)需分别配置,只配 request 不会让上传下载生效;③ 域名必须已完成 ICP 备案,境外主体账号规则不同,以平台提示为准;④ 每月修改次数有限(现行规则为每月 50 次,以平台最新公告为准),上线前务必规划好域名,不要临时改动;⑤ 配置后需重新编译并真机预览才生效,开发者工具的“不校验合法域名”勾选状态会掩盖问题,验证时务必取消勾选。

配置完成后可用命令行确认服务端协商出的协议版本,微信要求 TLS 1.2 以上:

nmap --script ssl-enum-ciphers -p 443 api.example.com
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>&1 | grep "Protocol|Cipher"

五、证书类型、有效期与服务价格对比表

下表按验证等级对比,小程序后端最常用的是 DV 与 OV;EV 在小程序场景没有额外收益。

类型 验证内容 签发时长 单张有效期上限 小程序适用场景
DV 域名型 仅验证域名控制权(DNS/HTTP/文件) 10 分钟–2 小时 398 天 绝大多数 API 域名、测试环境
OV 企业型 域名 + 营业执照 + 电话回访 1–3 工作日 398 天 支付回调、涉及企业身份的对外接口
EV 增强型 OV + 更严格的企业存续核验 3–7 工作日 398 天 小程序端无额外收益,一般不必选
Let’s Encrypt 域名控制权(ACME 自动) 分钟级 90 天 可自动化续期的中小项目,微信完全认可

按域名覆盖范围对比:

覆盖方式 示例 覆盖范围 注意点
单域名 api.example.com 仅该精确域名 加 www 或换子域需重新签发
通配符 *.example.com 仅一级子域 不覆盖 a.api.example.com,也不覆盖裸域 example.com
多域名 SAN api + m + pay 三个域名 SAN 列表内全部域名 后期追加域名通常需重新签发

若选择外包代购与配置服务,市场上常见的服务项参考价如下(价格随 CA 政策浮动,仅作预算参考):证书安装配置(不含证书)约 100 元;安装配置 + 全站 HTTP→HTTPS 跳转约 200 元;单域名 DV 证书含配置约 200 元;通配符 DV 证书含配置与跳转约 800 元;证书报错排查按次约 300 元;企业级 OV 单域名证书约 3500 元/年、OV 通配符约 6000 元/年。需要提醒的是,无论购买几年,公开信任证书单张有效期都不会超过 398 天,所谓“二年期、三年期”实质是订阅 + 多次重签,务必确认服务商是否包含后续重签与重新部署。

六、常见报错排查:真实错误信息与修复命令

报错 1:request:fail ssl hand shake error(微信小程序最常见)。根因按概率排序:证书链不全 > TLS 版本低于 1.2 > 服务器未开启 SNI > 加密套件不兼容。先用 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts 查看返回了几张证书,正常应至少 2 张(站点证书 + 中间证书)。

报错 2:curl: (60) SSL certificate problem: unable to get local issuer certificate。服务器只下发了站点证书,缺少中间证书。修复:Nginx 把 ssl_certificate 改为 fullchain.pem;Apache 配置 SSLCertificateChainFile;Tomcat 的 certificateFile 指向 fullchain.pem。

报错 3:nginx: [emerg] SSL_CTX_use_PrivateKey_file("/etc/nginx/ssl/example.com.key") failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。证书与私钥不配对,通常是重签后只换了证书没换私钥。用模数比对确认:

openssl x509 -noout -modulus -in example.com.crt | openssl md5
openssl rsa  -noout -modulus -in example.com.key | openssl md5
# 两行输出必须完全一致,否则说明文件配错

报错 4:curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure。协议或加密套件协商失败,多见于服务端只开了 TLS 1.0/1.1,或只保留了已被淘汰的 CBC 套件。修复:ssl_protocols TLSv1.2 TLSv1.3; 并启用 ECDHE GCM 套件。

报错 5:net::ERR_CERT_COMMON_NAME_INVALID。域名不在证书 SAN 中。用 openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name" 核对,若缺失需重新签发。

报错 6:curl: (60) SSL certificate problem: certificate has expired。证书过期。注意 398 天规则下证书到期非常突然,务必建立到期前 30 天告警。

报错 7(Tomcat):java.security.cert.CertificateException: No subject alternative names present。使用了只含 CN 不含 SAN 的旧证书,或客户端按 IP 访问。重新签发带 SAN 的证书,并用域名而非 IP 访问。

报错关键字 根因 一键修复
ssl hand shake error 链不全 / TLS 过低 / 无 SNI 改 fullchain + TLSv1.2/1.3 + 开 SNI
unable to get local issuer certificate 缺中间证书 部署 fullchain.pem
key values mismatch 证书与私钥不配对 modulus 比对后重新配对
sslv3 alert handshake failure 协议/套件不兼容 调整 ssl_protocols 与 ssl_ciphers
certificate has expired 证书过期 续签并 reload

七、效果验证与自动续期

配置完成后不要只看浏览器绿锁,必须从服务端实际下发的证书链验证。以下命令可直接执行:

# 1. 查看服务端下发的证书主题、签发者与有效期
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates

# 2. 验证信任链是否完整(返回 0 才算通过)
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>&1 | grep "Verify return code"

# 3. 枚举协议与套件,确认已禁用 TLS 1.0/1.1
nmap --script ssl-enum-ciphers -p 443 api.example.com

# 4. 确认 HTTP 已 301 跳转
curl -I http://api.example.com

自动续期是长期稳定运行的关键。Let’s Encrypt 90 天有效期意味着一年至少续 4 次,人工操作极易遗漏:

# certbot 续期演练(不会真正续签,用于验证配置正确)
certbot renew --dry-run
systemctl list-timers | grep certbot

# acme.sh 安装证书并配置 reload 钩子
~/.acme.sh/acme.sh --install-cert -d api.example.com 
  --key-file       /etc/nginx/ssl/example.com.key 
  --fullchain-file /etc/nginx/ssl/fullchain.pem 
  --reloadcmd      "nginx -s reload"

验证清单建议固定为五条:① Verify return code 为 0;② 服务端下发证书数量 ≥ 2;③ 协议仅含 TLS 1.2/1.3;④ HTTP 全部 301 到 HTTPS;⑤ 微信开发者工具取消“不校验合法域名”后真机请求成功。此外可用 myssl.com、Qualys SSL Labs 做 A 级评级复核,小程序真机测试覆盖 iOS 与至少一台安卓 7.0 以下机型,能提前暴露证书链问题。

最后提醒两点运维细节:一是 Nginx 修改证书后必须 nginx -s reload,否则进程仍持有旧证书;二是续期脚本要把新证书同步到所有节点(负载均衡、CDN、容器镜像),只更新一台机器会造成请求随机失败,表现为“时好时坏”的 ssl hand shake error。

常见问题

微信小程序可以使用免费的 Let’s Encrypt 证书吗?

可以。微信只校验证书是否受信任、域名是否匹配、TLS 版本是否 ≥ 1.2,并不区分 DV / OV / EV,也不要求付费证书。但 Let’s Encrypt 证书有效期只有 90 天,必须配置 ACME 自动续期与 reload 钩子,否则 90 天后小程序所有请求会同时失败。

为什么 iOS 正常,部分安卓机报 ssl hand shake error?

九成以上是证书链不完整:服务器只下发了站点证书,缺中间证书。iOS 会自动下载补链,部分安卓旧机型不会。修复方式是 Nginx 的 ssl_certificate 指向 fullchain.pem、Apache 配置 SSLCertificateChainFile、Tomcat 的 certificateFile 指向 fullchain.pem。

通配符证书能覆盖几级域名?

只覆盖一级。*.example.com 覆盖 api.example.com,但不覆盖 a.api.example.com,也不覆盖裸域 example.com。多级子域需要在 SAN 中逐个列出,或改用多域名证书。

买了“2 年期证书”,为什么 398 天就到期了?

因为 CA/Browser Forum 规定公开信任证书单张有效期上限为 398 天(自 2020 年 9 月 1 日起执行)。所谓 2 年期是订阅合同,到期由 CA 自动重签一张新证书,仍需你在到期前完成重签、重新部署并 reload 服务。

小程序合法域名可以填 IP、localhost 或带端口吗?

都不可以。必须是已完成 ICP 备案的域名,走标准 443 端口,且证书受公共信任。IP 地址、localhost、非标准端口(如 8443)、自签名证书均不被支持。内网调试请使用开发者工具的“不校验合法域名”选项,仅限开发阶段。

更换证书后需要重新在微信后台配置域名吗?

不需要。微信只校验域名白名单与证书信任链,单纯更换证书不影响已配置的合法域名。但如果更换了域名,就必须在公众平台重新配置(每月修改次数有限,现行规则为每月 50 次),并重新编译、真机预览验证。

内容审核

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