微信小程序 HTTPS 证书申请与配置全流程:Nginx/Apache/Tomcat 实操、398 天有效期与报错排查
一、问题背景与根因:小程序为什么强制 HTTPS
微信小程序对 wx.request、wx.uploadFile、wx.downloadFile 等网络 API 强制要求 HTTPS,这是三重校验叠加的结果:
- 传输层加密:明文 HTTP 在公共 Wi-Fi、运营商链路上可被中间人注入广告脚本,原文所说的“防广告劫持”本质就是消灭明文传输面,小程序运行环境直接拒绝 http:// 域名。
- TLS 协议版本:微信客户端与主流浏览器均要求 TLS 1.2 及以上,TLS 1.0/1.1 在 2020 年后已被废弃,握手直接失败。
- 证书可信链:证书必须由受信任 CA 签发,且服务端必须下发完整证书链(服务器证书 + 中间 CA 证书)。自签名证书、缺中间证书、域名不匹配都会导致 request:fail。
另外两个高频坑:第一,服务器域名必须在微信公众平台「开发管理 → 开发设置 → 服务器域名」中配置,只能是域名、不能是 IP、不能带端口号(固定走 443);第二,证书有效期已经不是“一年”——CA/Browser Forum 规定自 2020-09-01 起,公开信任的 TLS 证书单张有效期上限为 398 天,Let’s Encrypt 等免费 CA 更是只有 90 天,必须做自动续期,否则到期当天小程序全线报错。
最后别忘了云主机安全组:ECS/轻量服务器的 443/TCP 入方向未放行时,客户端表现为连接超时(curl 报 Connection timed out),而不是证书错误,排查方向完全不同。
二、证书类型选型:DV / OV / EV 与域名覆盖范围
证书按审核深度分三档,按域名覆盖分三种,两个维度要分开选。
| 类型 | 审核内容 | 签发时长 | 有效期上限 | 浏览器表现 | 典型场景 |
|---|---|---|---|---|---|
| DV 域名型 | 仅验证域名控制权(DNS TXT / 文件 / HTTP) | 5 分钟 – 2 小时 | 398 天 | 地址栏锁图标 | 小程序后端、API、个人站 |
| OV 企业型 | DV + 企业工商信息核验 | 1-5 工作日 | 398 天 | 锁图标,可点开查看组织名 | 企业官网、SaaS 后台 |
| EV 增强型 | OV + 严格法律实体与电话核验 | 3-7 工作日 | 398 天 | 锁图标(Chrome 77 / Firefox / Safari 自 2019 年起已移除地址栏绿色公司名) | 金融、支付、电商 |
纠正一个过时说法:原文称 EV 证书“浏览器地址栏直接显示公司名称”,这在 2019 年之前成立;现在 Chrome、Safari、Firefox 均已取消 EV 视觉标识,只保留锁图标。EV 的剩余价值在于保险赔付额度与合规审计,不再有视觉溢价,中小项目没必要为此多付钱。
| 覆盖类型 | 示例 | 注意 |
|---|---|---|
| 单域名 | api.example.com | example.com 与 api.example.com 视为两个域名 |
| 多域名(SAN) | example.com + www.example.com + api.example.com | 默认 3-5 个,可付费扩到 100 个 |
| 通配符 | *.example.com | 只匹配一级子域;不匹配 example.com 本身,也不匹配 a.b.example.com |
选型结论:小程序后端接口域名 99% 用 DV 单域名或 DV 通配符即可,微信只校验证书是否受信任、域名是否匹配、是否在有效期内,不看你买的是 OV 还是 EV。若同域下子域很多(如 a.example.com、b.example.com、c.example.com),一张通配符证书比多域名证书更省钱,但要额外给裸域 example.com 补一张单域名证书。
三、申请前准备:域名、验证方式与 CSR 生成
提交申请前,先把四样东西备齐:
- 域名:已实名、已完成 ICP 备案(国内服务器必须),解析记录可控。
- DNS 管理权限:DV 证书最常用 DNS TXT 验证,需要在域名解析里添加一条 TXT 记录。
- 服务器信息:操作系统版本 + Web 服务软件版本(Nginx 1.24、Apache 2.4、IIS 10、Tomcat 9),决定最终下发哪种格式的证书包。
- 私钥与 CSR:CSR(Certificate Signing Request)包含公钥与主体信息,私钥必须自己保管,绝不外传。
在服务器上生成私钥与 CSR(RSA 2048 位,兼容性最好):
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
openssl genrsa -out example.com.key 2048
chmod 600 example.com.key
openssl req -new -key example.com.key -out example.com.csr
-subj "/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Tech/CN=example.com"
如果需要多域名(SAN),必须在 CSR 中显式写入,不能只写 CN:
openssl req -new -key example.com.key -out example.com.csr
-subj "/C=CN/O=Example Tech/CN=example.com"
-addext "subjectAltName=DNS:example.com,DNS:www.example.com,DNS:api.example.com"
openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name"
国内 CA 或部分商业 CA 更偏好 ECC 密钥(握手更快、证书更小),生成方式:
openssl ecparam -genkey -name prime256v1 -out example.com.key
提交后按 CA 要求添加 TXT 记录,用 dig 自行验证是否生效(DNS 有缓存,建议查权威 NS):
dig +short TXT _dnsauth.example.com @8.8.8.8
验证通过后 CA 通常几分钟内签发 DV 证书。下载的证书包一般包含 example.com.crt(服务器证书)、ca_bundle.crt(中间证书)、example.com.key,三者缺一不可,后面配置必须用「服务器证书 + 中间证书」合并后的 fullchain。
四、完整实操:用 acme.sh 申请 Let’s Encrypt 免费证书(90 天自动续期)
如果预算为零或需要快速上线,Let’s Encrypt 是最优解,有效期 90 天,靠 cron 自动续期,成本为零且被微信小程序完全认可。以下命令可直接执行(CentOS/Ubuntu 通用):
# 1. 安装 acme.sh(自动写入 crontab)
curl https://get.acme.sh | sh -s email=admin@example.com
source ~/.bashrc
# 2. 设置默认 CA(可选,也可用 ZeroSSL)
acme.sh --set-default-ca --server letsencrypt
# 3. 用 webroot 方式签发(Nginx 站点根目录需可写)
acme.sh --issue -d example.com -d www.example.com
--webroot /var/www/html --keylength ec-256
# 4. 安装证书并配置续期后自动 reload
acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/fullchain.cer
--reloadcmd "nginx -t && systemctl reload nginx"
如果 80 端口被占用或无法临时开放,改用 DNS 方式(以阿里云为例,需先 export 阿里云 AK/SK):
export Ali_Key="LTAI5t****" Ali_Secret="****"
acme.sh --issue -d example.com -d "*.example.com" --dns dns_ali --keylength ec-256
安装完成后确认续期任务存在:
crontab -l | grep acme
# 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null
acme.sh --list
商业证书(OV/EV)流程不同:把第三节生成的 CSR 提交给 CA → 完成组织核验 → 下载证书包 → 合并 fullchain(见第六节)。注意商业证书同样受 398 天上限约束,且到期不会自动续,必须在日历上提前 30 天提醒。
关键提醒:acme.sh 的 –install-cert 会创建软链接或复制文件,之后 Nginx 只读 /etc/nginx/ssl 下的文件,续期后自动 reload,无需人工干预。千万不要把证书路径直接指向 ~/.acme.sh 目录,否则 acme.sh 升级后路径变化会导致 Nginx 启动失败。
五、配置示例:Nginx / Apache 完整 HTTPS 与 301 跳转
Nginx 最小可用且符合小程序要求的配置(含 HTTP→HTTPS 301、TLS 1.2/1.3、OCSP Stapling、HSTS):
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 /etc/nginx/ssl/fullchain.cer;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
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;
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;
ssl_trusted_certificate /etc/nginx/ssl/fullchain.cer;
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 https;
proxy_set_header X-Real-IP $remote_addr;
}
}
nginx -t && systemctl reload nginx
Apache 2.4(httpd)对应配置:
<VirtualHost *:80>
ServerName example.com
Redirect permanent / https://example.com/
</VirtualHost>
<VirtualHost *:443>
ServerName example.com
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/fullchain.crt
SSLCertificateKeyFile /etc/httpd/ssl/example.com.key
# Apache 2.4.8+ 用 SSLCertificateFile 指向 fullchain 即可,无需 ChainFile
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite HIGH:!aNULL:!MD5:!3DES
Header always set Strict-Transport-Security "max-age=31536000"
</VirtualHost>
三个易错点:一是 ssl_certificate 必须指向 fullchain(服务器证书 + 中间证书),指向单张服务器证书会触发 curl: (60) 与小程序 request:fail;二是 HSTS 一旦下发,浏览器在 max-age 内强制走 HTTPS,调试期建议先设 max-age=300,验证通过后再调到 31536000;三是反向代理场景要传 X-Forwarded-Proto,否则后端生成的跳转链接仍会是 http。
六、证书链合并与格式转换:IIS / Tomcat / Java 环境
商业 CA 下发的证书包通常是分开的,必须手工合并成 fullchain,否则链不完整:
cd /etc/nginx/ssl
cat example.com.crt ca_bundle.crt > fullchain.crt
openssl verify -CAfile ca_bundle.crt fullchain.crt
# fullchain.crt: OK
验证链是否完整:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>&1 | grep -E "s:|i:"
输出里应该能看到至少两级证书(服务器证书 + 中间 CA),只有一级说明链断了。
Tomcat / Java 需要 PKCS#12 格式(.pfx),转换命令:
openssl pkcs12 -export -out example.com.pfx
-inkey example.com.key
-in fullchain.crt
-certfile ca_bundle.crt
-passout pass:YourPassword
# 检查 pfx 里是否包含完整链
keytool -list -v -keystore example.com.pfx -storetype PKCS12 -storepass YourPassword | grep -E "Alias|Owner|Issuer"
Tomcat 9 的 server.xml 配置:
<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
<SSLHostConfig>
<Certificate certificateKeystoreFile="/opt/tomcat/conf/example.com.pfx"
certificateKeystorePassword="YourPassword"
certificateKeystoreType="PKCS12"
type="RSA" />
</SSLHostConfig>
</Connector>
IIS 则通过「服务器证书 → 导入 .pfx」完成,导入时必须勾选「允许导出证书」,否则后续无法迁移。Java 8 早期版本对 ECC 证书支持不完整,若使用 ec-256 密钥出现握手失败,建议改回 RSA 2048 或升级到 JDK 11+。另外 Tomcat 若报 java.security.cert.CertificateException: No name matching example.com found,通常是 pfx 里只有服务器证书没有中间证书,重新用 -certfile 合并即可。
七、常见错误排查:真实报错与定位命令
| 报错信息 | 根因 | 修复 |
|---|---|---|
| curl: (60) SSL certificate problem: unable to get local issuer certificate | 未下发中间证书,链不完整 | ssl_certificate 指向 fullchain |
| 小程序 request:fail ssl handshake failed | TLS 版本过低 / 加密套件无交集 / 缺中间证书 | 启用 TLSv1.2+,用 openssl s_client 复测 |
| NET::ERR_CERT_COMMON_NAME_INVALID | 证书域名与访问域名不匹配(证书是 example.com,访问 api.example.com) | 重新签发含 SAN 的证书 |
| NET::ERR_CERT_DATE_INVALID | 证书过期,或客户端系统时间错误 | 续期;校准服务器 NTP |
| SSL_ERROR_NO_CYPHER_OVERLAP | 服务端只保留 TLS1.3 套件而客户端仅支持 1.2,或反之 | 同时启用 TLSv1.2 与 TLSv1.3 |
| curl: (7) Failed to connect to example.com port 443: Connection timed out | 安全组 / 防火墙未放行 443 | 放行 443/TCP 入方向 |
| verify error:num=20:unable to get local issuer certificate | openssl 本地缺根证书,或服务端链不全 | 用 -CAfile 指定根证书复测 |
三段式定位法:
# 1. 端口通不通
nc -zv example.com 443
# 2. 证书本身对不对(看 subject / 有效期 / 颁发者)
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 3. 链完整不完整(看 verify return code 是否为 0)
openssl s_client -connect example.com:443 -servername example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>&1 | grep "Verify return code"
输出 Verify return code: 0 (ok) 才算链完整。若为 21(unable to verify the first certificate),说明服务端没发中间证书;若为 10(certificate has expired),说明过期。
八、效果验证:从命令行到小程序真机
配置改完不要只看浏览器,按下面五步逐层验证。
1. 协议与套件
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 期望:handshake failure(TLS 1.1 已被禁用)
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null
# 期望:Verify return code: 0 (ok)
2. HTTP 跳转
curl -I http://example.com
# 期望:HTTP/1.1 301 Moved Permanently
# Location: https://example.com/
curl -I https://example.com
# 期望:HTTP/2 200
3. 证书有效期
echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -enddate
4. 第三方评级:把域名丢进 SSL Labs(ssllabs.com/ssltest),目标是 A 或 A+。若只有 B,多半是未开 HSTS 或仍支持 TLS 1.0/1.1。
5. 小程序端:开发阶段可在微信开发者工具「详情 → 本地设置」勾选「不校验合法域名」,但这只能掩盖问题,不能替代真实校验。真机验证前必须:在微信公众平台配置 request 合法域名(只能是 https、不能带端口、不能是 IP);用手机 4G 网络(非公司内网)打开小程序,走一遍核心接口;在小程序后台「开发管理 → 运维中心 → 监控告警」查看是否有 request:fail 上报。
另外建议加一条续期监控:
echo | openssl s_client -connect example.com:443 2>/dev/null
| openssl x509 -noout -checkend 2592000 && echo "30天内不会过期" || echo "请立即续期"
把这条命令挂到 Zabbix / Prometheus 的 textfile collector 里,就能在到期前 30 天收到告警,避免重演「证书过期导致小程序全线不可用」的事故。
常见问题
Let’s Encrypt 免费证书能用于微信小程序吗?
可以。微信只校验证书是否由受信任 CA 签发、域名是否匹配、是否在有效期内,不区分免费与付费。Let’s Encrypt 已被所有主流根证书库信任,唯一约束是 90 天有效期,必须配置 cron 自动续期并在续期后 reload 服务。
证书有效期到底是 398 天还是 90 天?
两者都对,是不同维度。CA/Browser Forum 规定公开信任的 TLS 证书单张最长 398 天,这是商业 CA(DV/OV/EV)的上限;Let’s Encrypt 主动把自家证书设为 90 天以缩短吊销窗口。无论哪种,都必须做续期自动化。
通配符证书能覆盖 example.com 和 a.b.example.com 吗?
都不能。*.example.com 只匹配一级子域(www.example.com、api.example.com),不匹配裸域 example.com,也不匹配二级子域 a.b.example.com。裸域需另配一张单域名证书,或用 SAN 把 example.com 加进去。
证书装好了,小程序仍报 request:fail,怎么查?
按顺序排查:① 微信公众平台是否已配置该域名(不能带端口、不能是 IP);② openssl s_client 看 Verify return code 是否为 0;③ 是否只支持 TLS 1.3 而部分安卓机只支持 1.2;④ 安全组 443 是否放行;⑤ 域名是否备案(国内服务器)。
一台服务器可以同时配置多张证书吗?
可以。Nginx 按 server_name 匹配不同的 ssl_certificate,同一 IP 多域名互不影响;也可以在同一 server 块中同时配置 RSA 与 ECC 双证书(ssl_certificate 写两次),由客户端协商选择。
配置 HSTS 有什么风险?
HSTS 下发后,浏览器在 max-age 内强制该域名走 HTTPS,无法回退到 HTTP。调试期建议先设 max-age=300,确认全站 HTTPS 正常(含子域、第三方回调)后再调到 31536000,并谨慎使用 includeSubDomains。