微信小程序 HTTPS 部署实战:SSL 泛域名证书申请、Nginx/Apache/IIS 配置与排错
微信小程序通过 wx.request、wx.uploadFile、wx.downloadFile 访问后端时,只允许 HTTPS,且证书必须由系统信任的 CA 签发,不能使用自签名证书;域名要完成 ICP 备案并加入小程序后台的 request 合法域名,不能使用 IP 或 localhost。很多“证书装了但小程序仍报错”的问题,根因不是证书没买,而是证书链不完整、泛域名不匹配、TLS 版本过低或页面混合内容。
泛域名证书的边界要先说清:*.example.com 只匹配一级子域名,如 api.example.com,不匹配 example.com,也不匹配 a.b.example.com。因此申请时通常同时提交根域和通配符:-d example.com -d '*.example.com'。微信校验的是证书 SAN 与请求域名是否一致,少一个域名就会报 NET::ERR_CERT_COMMON_NAME_INVALID 或 request:fail ssl handshake error。
另一个高频根因是证书链。Nginx 的 ssl_certificate 必须指向“叶子证书+中间证书”的 fullchain 文件,只配叶子证书时,浏览器可能正常,但 Android 微信和部分 iOS 版本会报 unable to verify the first certificate。公开信任 TLS 证书自 2020 年 9 月起最长有效期为 398 天,Let’s Encrypt 为 90 天,必须做自动续期。
上线前先做两条快速诊断:
curl -vI https://api.example.com
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null
输出中只有出现 Verify return code: 0 (ok),且证书链按“叶子证书→中间证书”顺序返回,才说明链完整。若返回 Verify return code: 21 (unable to verify the first certificate),直接检查 fullchain 配置。
申请泛域名证书:DNS-01 验证完整命令
泛域名证书不能走 HTTP-01,必须用 DNS-01:CA 要求你在 _acme-challenge.example.com 添加 TXT 记录。生产环境建议用 DNS API 自动完成,避免手工续期。以 acme.sh + 阿里云 DNS 为例,命令可直接执行:
curl https://get.acme.sh | sh -s email=ops@example.com
export Ali_Key='LTAI5txxxxxxxx'
export Ali_Secret='xxxxxxxxxxxxxxxx'
~/.acme.sh/acme.sh --issue --server letsencrypt --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256
签发过程中可用 dig 检查 TXT 是否生效,公共 DNS 有缓存时多等 1-5 分钟:
dig +short TXT _acme-challenge.example.com
dig @8.8.8.8 +short TXT _acme-challenge.example.com
dig +short CAA example.com
如果域名配置了 CAA 记录,必须允许 Let’s Encrypt 或你使用的 CA,否则会报 CAA record forbids issuance。签发成功后安装到 Nginx 并设置自动重载:
~/.acme.sh/acme.sh --install-cert -d example.com --ecc --key-file /etc/nginx/ssl/example.com.key --fullchain-file /etc/nginx/ssl/example.com.fullchain.pem --reloadcmd 'systemctl reload nginx'
用 certbot 也可以,Cloudflare DNS 插件示例:
certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d example.com -d '*.example.com'
注意三点:第一,--install-cert 会复制证书并注册续期任务,不要手工复制后就不管;第二,Let’s Encrypt 有效期 90 天,acme.sh 默认约 60 天续期,建议保留 --reloadcmd;第三,老客户端兼容性要求高时用 RSA 2048,即把 --keylength ec-256 换成 --keylength 2048。
Nginx 部署与 TLS 优化配置示例
下面配置同时覆盖 80 跳转、443 证书、TLS 1.2/1.3、OCSP Stapling 和反向代理。Nginx 1.25.1 及以上用 http2 on;,旧版本改为 listen 443 ssl http2;。
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/example.com.fullchain.pem;
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/example.com.fullchain.pem;
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;
proxy_set_header X-Real-IP $remote_addr;
}
}
执行 nginx -t && systemctl reload nginx。如果使用 CDN,证书要同时上传到 CDN,并把回源协议改成 HTTPS,否则回源仍是 HTTP,小程序侧看到的虽然是 HTTPS,但源站存在混合内容风险。验证命令:
openssl s_client -connect api.example.com:443 -servername api.example.com -alpn h2 -showcerts </dev/null | openssl x509 -noout -subject -issuer -dates
curl -I https://api.example.com
HSTS 的 includeSubDomains 要谨慎:一旦开启,所有子域名都必须能 HTTPS 访问,否则会被浏览器强制拦截。小程序接口域名建议单独使用一个子域,不要和未上 HTTPS 的旧业务混用。
Apache 与 IIS 部署要点
Apache 2.2.12 以后已支持 SNI,多站点 HTTPS 不再必须独立 IP;但旧版 Apache 或未开启 mod_ssl 时仍会受限。关键是指向 fullchain,而不是只写站点证书:
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/example.com.fullchain.pem
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
Header always set Strict-Transport-Security max-age=31536000
</VirtualHost>
执行 apachectl configtest 后重载。Apache 2.4.8 以后不再需要单独配置 SSLCertificateChainFile,把中间证书拼进 fullchain 即可;如果仍分开配置,链顺序必须是“站点证书→中间证书”,不能把根证书放进去。
IIS 方面要纠正一个旧说法:Windows Server 2003/2008 的 IIS 7.5 不支持 SNI,多站点 HTTPS 需要独立 IP 或通配符证书;IIS 8/Windows Server 2012 及以上支持 SNI,可以用 SslFlags 1 绑定多个域名。PowerShell 示例:
Import-PfxCertificate -FilePath C:/certs/example.com.pfx -CertStoreLocation Cert:LocalMachineMy
New-WebBinding -Name 'Api' -Protocol https -Port 443 -HostHeader api.example.com -SslFlags 1
$cert = Get-ChildItem Cert:LocalMachineMy | Where-Object {$_.Subject -like '*CN=*.example.com*'}
New-Item -Path 'IIS:SslBindings.0.0.0!443!api.example.com' -Value $cert
IIS 导入 PFX 时要包含私钥,并在站点绑定中勾选“需要服务器名称指示”。若绑定后仍返回默认站点证书,检查是否漏了 -SslFlags 1,以及 443 绑定是否被其他站点占用。
证书类型与部署方式对比
小程序只要求“受信任的 HTTPS”,并不强制 OV 或 EV。DV 证书签发快、成本低,适合 API 域名;OV/EV 需要组织验证,适合金融、品牌类业务,但 EV 早已不再显示绿色地址栏,不要为“绿色锁”多花钱。泛域名证书适合子域多、频繁增减的场景,但只覆盖一级子域。
| 证书类型 | 验证方式 | 覆盖范围 | 有效期 | 小程序适用 | 典型场景 |
|---|---|---|---|---|---|
| DV 单域名 | HTTP-01/DNS-01 | 1 个 FQDN | 最长 398 天 | 可用 | 单接口域名 |
| DV 泛域名 | 仅 DNS-01 | *.example.com 一级子域 | 最长 398 天 | 可用 | 多子域 API |
| OV/EV | 组织验证 | 单域名/多域名 | 最长 398 天 | 可用但非必需 | 金融、品牌 |
| Let’s Encrypt | HTTP-01/DNS-01 | 单域名/泛域名 | 90 天 | 可用 | 自动化免费 |
部署环境差异也要注意:Nginx 原生支持 SNI,多站点配置简单;Apache 2.2.12+ 支持 SNI,旧版才需要独立 IP;IIS 8/2012+ 支持 SNI,2008 R2 不支持;CDN 要在控制台上传证书和私钥,并开启回源 HTTPS。不要把“能配置几个 HTTPS 站点”当成证书类型问题,它本质是 SNI 和监听端口绑定问题。
| 环境 | 多站点 HTTPS | 关键配置 | 注意事项 |
|---|---|---|---|
| Nginx | SNI 原生支持 | ssl_certificate fullchain | 1.25.1+ 用 http2 on |
| Apache | 2.2.12+ 支持 SNI | SSLCertificateFile fullchain | 旧版需独立 IP |
| IIS | IIS 8/2012+ 支持 SNI | SslFlags 1 | 2008 R2 不支持 SNI |
| CDN | 控制台配置 | 上传证书+私钥 | 回源也要 HTTPS |
常见错误排查(含真实报错)
下面这些报错在小程序、浏览器和 curl 中很常见,按“报错→根因→修复”处理即可。
| 真实报错 | 根因 | 修复 |
|---|---|---|
| curl: (60) SSL certificate problem: unable to get local issuer certificate | 缺中间证书或链顺序错误 | ssl_certificate 改用 fullchain,按“叶子→中间”拼接 |
| request:fail ssl handshake error | TLS 版本/加密套件不兼容 | 启用 TLSv1.2 和 TLSv1.3,禁用 TLSv1.0/1.1 |
| NET::ERR_CERT_COMMON_NAME_INVALID | 证书 SAN 不含请求域名 | 泛域名只覆盖一级子域,重新签发并包含根域 |
| unable to verify the first certificate | 只部署了站点证书 | 补中间证书,检查 fullchain 文件内容 |
| sslv3 alert handshake failure / dh key too small | 旧协议或 DH 参数过短 | 禁用 SSLv3,使用 ECDHE,DH 至少 2048 位 |
| request:fail url not in domain list | 域名未加入小程序后台 | 在 request 合法域名中添加 HTTPS 域名并备案 |
定位时先绕过 CDN 直连源站:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 -showcerts </dev/null
curl -vI --resolve api.example.com:443:1.2.3.4 https://api.example.com
如果直连源站正常、走 CDN 异常,问题在 CDN 证书或回源配置;如果 openssl 返回的证书 subject 是默认站点证书,说明 SNI 未生效或 443 绑定串站。小程序侧还要注意:开发者工具勾选“不校验合法域名”时能跑,不代表真机能跑,真机调试必须使用已备案且证书有效的域名。
效果验证与上线检查清单
配置完成后不要只看浏览器锁标,按下面顺序验证:
openssl s_client -connect api.example.com:443 -servername api.example.com -verify_hostname api.example.com -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
openssl x509 -noout -subject -issuer -dates -ext subjectAltName < /etc/nginx/ssl/example.com.fullchain.pem
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}' https://api.example.com
nmap --script ssl-enum-ciphers -p 443 api.example.com
检查清单:证书 SAN 是否包含小程序请求的完整域名;有效期是否大于 30 天且自动续期任务正常;链是否完整;是否只启用 TLS 1.2/1.3;80 端口是否 301 到 HTTPS;HSTS 是否按需开启;页面是否还有 http:// 图片、JS、CSS 或接口;CDN 回源是否 HTTPS;小程序后台 request 合法域名是否已添加;真机是否关闭“不校验合法域名”后仍能请求。
最后用 SSL Labs 或 openssl s_client 看评级,A 以上即可;不必追求 A+ 而把旧客户端全部排除。微信小程序重点不是评级,而是证书链完整、域名匹配、TLS 1.2 可用和备案合法。上线后保留 30 天监控:证书到期前 15 天告警,续期后自动 reload,避免 90 天短周期证书过期导致接口全挂。
常见问题
不能。*.example.com 只匹配一级子域名,如 api.example.com,不匹配 example.com 和 a.b.example.com。申请时用 -d example.com -d ‘*.example.com’ 同时签发,或使用多域名证书补齐。
先用 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts 检查证书链和协议,确认已部署 fullchain、启用 TLS 1.2/1.3、域名与证书 SAN 一致;再检查小程序后台合法域名和 ICP 备案。
公开信任 TLS 证书自 2020 年 9 月起最长 398 天;Let’s Encrypt 为 90 天,acme.sh 默认约 60 天续期。建议开启自动续期并用 –reloadcmd 重载 Nginx/Apache,避免过期。
微信小程序要求 HTTPS,建议使用标准 443 端口;非标准端口在部分客户端、CDN 和防火墙策略下容易被拦截。若必须使用,需在合法域名中配置完整端口并确保证书 SAN 包含该域名。
这是页面仍调用 http:// 资源导致混合内容拦截,不是证书配置问题。用浏览器控制台筛选 Mixed Content,把图片、JS、CSS、接口地址改为 https:// 或 //,并设置 CSP upgrade-insecure-requests。
可以,同一张泛域名证书可部署在多台服务器,但私钥必须安全分发和保管;建议用 ACME 自动签发到各节点,或使用集中式证书管理,避免私钥泄露后全域名受影响,并定期轮换。