微信小程序 SSL 证书申请、安装配置与问题排查实战指南(398 天有效期修订版)
问题背景与根因:微信小程序为什么必须用受信任 SSL 证书
微信小程序把网络请求限制在 HTTPS 合法域名内,根因不是“装上证书就行”,而是客户端会校验证书链、域名、有效期、TLS 版本和域名备案状态。小程序要求服务器域名使用 HTTPS,TLS 版本至少 1.2;证书必须由受信任 CA 签发,不能自签名;request、uploadFile、downloadFile、socket 等域名需在小程序后台配置为合法域名,且不能使用 IP、localhost 或非标准端口。常见失败根因包括:只部署了叶子证书未带中间证书、证书 SAN 不含请求域名、证书过期、服务器时间错误、TLS 1.0/1.1 未关闭、Nginx 未开启 SNI、域名未备案或未加入合法域名列表。排查先看客户端报错,再用命令验证服务端。例如:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts
重点看 Verify return code 是否为 0,Protocol 是否为 TLSv1.2 或 TLSv1.3,证书链是否包含中间 CA。若返回 unable to get local issuer certificate,优先补 fullchain。小程序开发者工具中“不校验合法域名”只适合本地调试,真机预览和发布必须使用已备案、已配置的 HTTPS 域名。另一个根因是证书最长有效期规则变化:公共信任 TLS 证书单张最长 398 天,Let’s Encrypt 为 90 天,过期不会自动提醒业务方,必须做续期监控。以上检查能把“小程序 SSL 证书安装配置”问题从盲目重装转为按链路定位。
证书选型与有效期修正:DV、OV、EV 与 398 天规则
小程序场景优先选 DV 域名型证书即可满足受信任要求,不必为“小程序”三个字购买 OV/EV。DV 只验证域名控制权,签发快;OV 验证企业身份,通常 1-5 个工作日;EV 验证更严格,但主流浏览器已不再展示绿色公司名,小程序也不会因为 EV 放宽校验。按覆盖范围分:单域名证书只保护一个精确域名,如 api.example.com;多域名证书用 SAN 覆盖多个域名;通配符证书保护 *.example.com 的一级子域,不覆盖 example.com 本身,也不覆盖 a.b.example.com。购买前用 `openssl x509 -in cert.pem -noout -subject -issuer -dates -ext subjectAltName` 检查 SAN 和有效期。有效期必须修正:公共信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,原文“默认一年”已不符合现行规则;续期要自动化。Let’s Encrypt 可用 certbot 申请和续期,商业证书按 398 天周期续签。小程序后台配置的域名必须与证书 SAN 完全匹配,`www.example.com` 和 `api.example.com` 不能混用。若使用 CDN/WAF,证书要部署在边缘节点,回源也要校验。证书链文件通常叫 fullchain.pem,包含叶子证书和中间证书,私钥单独保存。选型时还要确认 CA 是否被微信客户端信任,避免使用内部 CA 或自签名证书。最后提醒:证书不是越贵越适合小程序,DV + 完整链 + TLS 1.2/1.3 + 自动续期才是关键。
完整实操:生成 CSR、申请证书、DNS 验证与下载证书
完整实操按“生成 CSR → 提交 CA → DNS 验证 → 下载证书 → 部署 → 自动续期”执行。先生成私钥和 CSR:
mkdir -p /etc/nginx/ssl
cd /etc/nginx/ssl
openssl req -new -newkey rsa:2048 -nodes -keyout api.example.com.key -out api.example.com.csr -subj '/C=CN/ST=Beijing/L=Beijing/O=Example/CN=api.example.com'
chmod 600 api.example.com.key
openssl req -in api.example.com.csr -noout -subject -text | grep -A2 'Subject Alternative Name'
商业 CA 下单时填 api.example.com,选择 DNS TXT 验证,按 CA 给出的主机记录添加 TXT。验证命令:
dig +short TXT _dnsauth.api.example.com
nslookup -type=TXT _dnsauth.api.example.com 8.8.8.8
返回值与 CA 控制台一致后再点验证。下载证书时通常得到 api.example.com.pem、fullchain.pem、private.key;Nginx 用 fullchain.pem 和 private.key,Apache 注意 SSLCertificateChainFile。Let’s Encrypt 可用:
certbot certonly --webroot -w /var/www/html -d api.example.com --agree-tos -m ops@example.com --non-interactive
certbot renew --dry-run
证书目录在 /etc/letsencrypt/live/api.example.com/,fullchain.pem 已含链。检查有效期:
openssl x509 -in /etc/nginx/ssl/api.example.com.fullchain.pem -noout -subject -issuer -dates
若使用通配符,DNS 验证记录为 _acme-challenge.example.com,且通配符申请通常必须 DNS-01。部署前核对私钥与证书是否匹配:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in private.key | openssl md5
两个 MD5 必须一致。最后设置续期任务并监控到期时间,避免 90 天或 398 天到期导致小程序请求失败。
Nginx 配置示例:443、TLS 1.2/1.3、证书链与反向代理
Nginx 是微信小程序后端最常见入口。配置要点:443 监听、证书用 fullchain、私钥权限 600、只开 TLSv1.2/TLSv1.3、HTTP 301 跳转 HTTPS、反向代理保留 Host 和 X-Forwarded-Proto。示例:
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.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
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-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
旧版 Nginx 用 `listen 443 ssl http2;`,1.25.1 后建议 `http2 on;`。`ssl_certificate` 必须指向 fullchain,若只写叶子证书,微信端可能报证书链不完整。修改后执行 `nginx -t` 和 `systemctl reload nginx`。若后端是 Spring Boot/Tomcat,确保 proxy_pass 后应用生成链接时识别 HTTPS,否则可加 `proxy_set_header X-Forwarded-Port 443;`。HSTS 首次上线建议先用较小 max-age,确认全站 HTTPS 后再加长。证书文件名不要带空格,权限 `chown root:root`、`chmod 600`。若使用 CDN,源站也要配置证书或使用回源协议 HTTPS,否则边缘到源站仍可能明文。最后用 `curl -I https://api.example.com/health` 看 200 和 TLS 握手,不要只看浏览器能打开。
Apache、Tomcat 与 IIS 配置示例
Apache 2.4 配置:启用 ssl 模块后,在 VirtualHost 中写 `SSLEngine on`、`SSLCertificateFile` 指向 fullchain、`SSLCertificateKeyFile` 指向私钥。Apache 2.4.8 之前还需 `SSLCertificateChainFile` 指向中间链。示例:
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/api.example.com.fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/api.example.com.key
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite HIGH:!aNULL:!MD5
Header always set Strict-Transport-Security 'max-age=31536000'
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/
RequestHeader set X-Forwarded-Proto 'https'
</VirtualHost>
执行 `apachectl configtest` 和 `systemctl reload httpd` 或 `apache2`。Tomcat 可把 PEM 转 PKCS12 再转 JKS:
openssl pkcs12 -export -out api.example.com.pfx -inkey api.example.com.key -in api.example.com.fullchain.pem -passout pass:ChangeMe
keytool -importkeystore -srckeystore api.example.com.pfx -srcstoretype PKCS12 -destkeystore api.example.com.jks -deststoretype JKS -deststorepass ChangeMe -srcstorepass ChangeMe
server.xml 中 Connector 示例:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" scheme="https" secure="true" keystoreFile="/etc/tomcat/api.example.com.jks" keystorePass="ChangeMe" SSLProtocol="TLSv1.2+TLSv1.3" />
IIS 则导入 PFX 到“服务器证书”,在站点绑定 443 并勾选 SNI,确保中间证书已包含在 PFX。无论哪种服务器,部署后都要用 `openssl s_client` 验证链和协议版本。若前面还有 SLB/CDN,证书要同时部署在负载均衡和源站,避免只修一层。
证书类型与部署方式对比表格
选型与部署方式对比如下。证书类型维度:DV 只验证域名,几分钟到数小时签发,适合小程序 API、个人站点;OV 验证企业,1-5 工作日,适合企业门户;EV 验证最严,但浏览器不再展示绿色公司名,小程序不因 EV 放宽校验。覆盖维度:单域名只保护一个 FQDN;多域名用 SAN 覆盖多个域名;通配符保护一级子域。有效期维度:公共信任证书最长 398 天,Let’s Encrypt 90 天且可自动续期。部署方式维度:Nginx 用 fullchain + key,Apache 用 fullchain + key + 可选 chain,Tomcat 用 JKS/PKCS12,IIS 用 PFX 并绑定 SNI。表格:
| 项目 | DV | OV | EV | 小程序建议 |
|---|---|---|---|---|
| 验证内容 | 域名控制权 | 企业身份+域名 | 严格企业身份 | DV 即可 |
| 签发时间 | 几分钟至数小时 | 1-5 工作日 | 更长 | 优先快发 |
| 最长有效期 | 398 天 | 398 天 | 398 天 | 需续期监控 |
| 浏览器展示 | 锁标志 | 锁标志 | 主流浏览器不展示公司名 | 无额外加分 |
| 适用场景 | API、博客、测试转生产 | 企业门户 | 金融/强合规 | API 用 DV |
另表:
| 覆盖类型 | 示例 | 不覆盖 | 注意 |
|---|---|---|---|
| 单域名 | api.example.com | www.example.com | 最常用 |
| 多域名 SAN | api.example.com、m.example.com | 未列出的域名 | 看 SAN 列表 |
| 通配符 | *.example.com | example.com、a.b.example.com | 通常 DNS-01 |
结论:小程序后端优先 DV 单域名或多域名,证书链完整、TLS1.2+、自动续期比证书等级更重要。
常见错误排查:真实报错与逐条修复
排查按“客户端报错 → 服务端握手 → 证书链 → 域名/备案 → 应用配置”顺序。1)`curl: (60) SSL certificate problem: unable to get local issuer certificate`:服务端未发送中间证书,Nginx 把 `ssl_certificate` 改成 fullchain.pem,Apache 补 `SSLCertificateChainFile`,Tomcat 重新导入含链的 PFX。2)`nginx: [emerg] cannot load certificate … PEM_read_bio_X509_AUX() failed`:路径错误、文件不是 PEM、把私钥和证书拼错,或证书含 CRLF 异常;用 `openssl x509 -in fullchain.pem -noout -text` 验证。3)微信开发者工具 `request:fail ssl hand shake error`:常见于只开 TLS1.0/1.1、证书链不完整、SNI 未生效;用 `openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2` 验证。4)`net::ERR_CERT_COMMON_NAME_INVALID`:证书 SAN 不含请求域名,如证书是 `www.example.com` 却请求 `api.example.com`,需重签或换域名。5)`curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL`:检查 443 安全组、防火墙、Nginx 是否监听、后端是否崩溃。6)微信后台提示“合法域名校验出错”:域名未备案、未加入 request 合法域名、使用了 IP/端口或证书不受信任。7)证书过期报 `certificate has expired`:用 `openssl x509 -noout -dates` 查到期,配置 certbot renew 和到期告警。8)`SSL_ERROR_BAD_CERT_DOMAIN`:与域名不匹配同类,检查 SNI 和多域名虚拟主机。每条修复后都用 `curl -vI https://api.example.com` 和 `openssl s_client` 复测,不要只重启服务。
效果验证与上线检查清单
效果验证分四层:证书层、协议层、HTTP 层、小程序端。证书层:
openssl x509 -in /etc/nginx/ssl/api.example.com.fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /etc/nginx/ssl/api.example.com.fullchain.pem
协议层:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2
输出中 `Verify return code: 0 (ok)` 表示链受信任,`Protocol : TLSv1.2` 或 TLSv1.3 表示协议达标;若出现 `verify error:num=21:unable to verify the first certificate`,说明链不完整。HTTP 层:
curl -I https://api.example.com/health
curl -vI https://api.example.com/health
看 200/301、证书主题、TLS 版本。小程序端:在微信开发者工具清缓存,真机预览,检查 request 合法域名、域名备案、TLS1.2、证书 SAN。上线检查清单:1. 证书未过期且剩余大于 30 天;2. fullchain 含中间证书;3. 私钥权限 600;4. 只开 TLS1.2/1.3;5. HTTP 301 到 HTTPS;6. 域名与 SAN 完全匹配;7. 小程序后台已配置 request/uploadFile/downloadFile 合法域名;8. 续期任务 `certbot renew –dry-run` 成功;9. 监控 443 和证书到期;10. CDN/源站证书一致。最后用 SSL Labs 或 `testssl.sh` 做外部扫描,确认无弱协议和链问题。
常见问题
微信小程序必须购买 OV 或 EV 证书吗?
不必须。小程序校验证书是否受信任、域名是否匹配、TLS 是否 1.2+,受信任 CA 签发的 DV 证书即可。OV/EV 不会绕过合法域名和备案要求。
Let’s Encrypt 90 天证书能用于小程序吗?
可以,但必须部署 fullchain 并自动续期。90 天有效期短,建议 `certbot renew –dry-run` 加到期告警,避免过期导致 request:fail。
证书最长有效期到底是 398 天还是 90 天?
公共信任 TLS 证书单张最长 398 天;Let’s Encrypt 默认 90 天。原文“一年有效期”已过时,续期周期按 CA 实际签发执行。
通配符证书能覆盖小程序所有子域名吗?
只覆盖一级子域,如 *.example.com 覆盖 api.example.com,不覆盖 example.com 和 a.b.example.com。小程序域名必须出现在 SAN 中。
如何判断证书链是否完整?
用 `openssl s_client -connect 域名:443 -servername 域名 -showcerts`,看到 `Verify return code: 0 (ok)` 且证书链含中间 CA 即完整;Nginx 的 ssl_certificate 应指向 fullchain.pem。
HTTP 已跳转 HTTPS,小程序仍报错怎么办?
检查 request 合法域名是否配置、域名是否备案、是否使用 IP/端口、TLS 是否低于 1.2、证书 SAN 是否匹配、CDN 回源是否 HTTPS。用真机而非仅开发者工具复测。