跳到主要内容
HTTPS小程序证书

微信小程序 HTTPS 全流程实战:SSL 证书申请、宝塔/Nginx 部署配置与报错排查

微信小程序 HTTPS 全流程实战:SSL 证书申请、宝塔/Nginx 部署配置与报错排查 — 微信小程序 HTTPS 全流程实战:SSL 证书申请、宝塔/Nginx 部署配置与报错排查

一、问题背景:小程序为什么“必须 HTTPS”,报错的真实根因是什么

微信小程序的所有网络请求(wx.request、wx.uploadFile、wx.downloadFile、WebSocket)都被强制要求走 HTTPS,且域名必须已在「微信公众平台 → 开发管理 → 开发设置 → 服务器域名」中配置为 request 合法域名。平台侧的硬约束有四条:必须是已完成备案的域名、不支持 IP 与 localhost、必须使用 443 端口(HTTPS)、必须是受信任 CA 签发的证书,自签名证书一律拒绝。

实际排障中,绝大多数“证书装了但小程序仍报错”的情况并非证书本身有问题,而是以下五类根因:① 只部署了站点证书,漏掉中间证书,形成“证书链不完整”;② 证书已过期,或服务器系统时间漂移导致校验失败;③ 证书 SAN 与请求域名不一致(www 与裸域混用最常见);④ 服务端仍开启 TLS 1.0/1.1,或加密套件被客户端拒绝;⑤ CDN/WAF 回源走 HTTP,或 443 端口被其他进程占用。

典型报错:小程序端 request:fail ssl handshake error,开发者工具 net::ERR_CERT_AUTHORITY_INVALID,命令行 curl: (60) SSL certificate problem: unable to get local issuer certificate。

关于有效期这个高频过时点:自 2020-09-01 起,公网信任 SSL/TLS 证书单张最长有效期为 398 天;Let’s Encrypt 免费证书有效期为 90 天,必须依赖自动续期。CA/Browser Forum 已通过分阶段缩短方案(2026-03 起降至 200 天),因此运维上应默认“证书一定会过期”,用自动化替代人工更换。

二、前置准备:域名解析、端口放行与证书类型选型

动手前先做四项检查,避免买错证书或白装一遍:

# 1. 解析是否正确
 dig +short example.com A
 dig +short www.example.com A

# 2. 80/443 是否放行(云安全组 + 本机防火墙都要看)
 firewall-cmd --list-ports        # CentOS
 ufw status                       # Ubuntu

# 3. 443 是否已被占用
 ss -lntp | grep ':443'

# 4. 当前线上证书信息(无输出即说明未部署)
 echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
   | openssl x509 -noout -subject -issuer -dates

证书类型直接决定验证方式、签发时长与成本:

证书类型 验证方式 签发时长 典型场景 注意点
DV 域名型 DNS / 文件 1-10 分钟 小程序、博客、测试环境 仅验证域名所有权,小程序够用
OV 企业型 企业资质 + DNS 1-3 工作日 政企对外站点 证书含企业信息,价格高
通配符 DV DNS-01(必须) 10 分钟内 多子域业务 只覆盖一级子域
多域名 SAN DNS / 文件 10 分钟内 多业务域共用一张 按域名个数计费,注意上限
IP 证书 特殊文件验证 1-3 工作日 IP 直连的内网/专有场景 小程序合法域名仍要求域名,不能填 IP

关键结论:小程序用 DV 证书即可满足兼容性要求;通配符 *.example.com 不覆盖 a.b.example.com;多域名证书扩容前先确认 SAN 余量;按域名个数付费的服务,通配符与多域名证书都要按实际域名数结算,下单前先数清域名。

三、实操:acme.sh 完成证书申请与 DNS/文件验证

以 Let’s Encrypt(90 天,自动续期)为例,DNS-01 与 HTTP-01 两种验证方式都能覆盖。先安装并切换默认 CA:

curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
acme.sh --set-default-ca --server letsencrypt

方式 A:DNS 自动验证(推荐,支持通配符,无需公网 80 端口):

export Ali_Key='LTAIxxxxxxxx'
export Ali_Secret='xxxxxxxx'
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256

方式 B:文件验证(站点已能通过 80 正常访问):

acme.sh --issue -d example.com -d www.example.com 
  -w /www/wwwroot/example.com --keylength ec-256

签发成功后把证书安装到固定路径,并绑定 reload 命令,让续期后自动生效:

acme.sh --install-cert -d example.com --ecc 
  --key-file       /www/server/panel/vhost/cert/example.com/privkey.pem 
  --fullchain-file /www/server/panel/vhost/cert/example.com/fullchain.pem 
  --reloadcmd      'nginx -t && nginx -s reload'

三个必须注意的点:① 一定要用 fullchain(站点证书 + 中间证书),只给站点证书会导致安卓端与小程序握手失败;② acme.sh 默认已写入 crontab,用 crontab -l | grep acme 确认;③ 手动续期用 acme.sh --renew -d example.com --force,上线前可加 --dry-run 演练,避免把测试证书打到生产。

四、宝塔面板部署 SSL 证书的完整步骤

宝塔是国内最常见的部署入口,路径为:网站 → 对应站点「设置」→「SSL」→「其他证书」。标准操作顺序如下:

  • 打开 fullchain.pem,内容必须是“站点证书在前、中间证书在后”的 PEM 块,整段粘贴到「证书(PEM 格式)」;
  • 把 privkey.pem 粘贴到「私钥(KEY 格式)」,点击保存;
  • 打开「强制 HTTPS」开关,宝塔会自动写入 301 跳转规则;
  • 进入「配置文件」确认已生成 listen 443 ssl http2; 与正确的 ssl_certificate 路径。

也可以直接用「Let’s Encrypt」一键申请,但要注意:文件验证要求域名已解析到本机、且 80 端口可从公网访问。若站点开启了 CDN 或全站 301 跳转 HTTPS,验证文件会被重定向,报错形如 Invalid response from http://example.com/.well-known/acme-challenge/xxx: 301,此时应在 Nginx 中为 /.well-known/acme-challenge/ 单独放行,或改用 DNS 验证。

宝塔提示「证书已到期」多数不是真的过期,而是粘贴顺序颠倒(中间证书在前)或混入了 BOM 头与 Windows 换行。可用 openssl x509 -in fullchain.pem -noout -dates 查真实有效期,用 openssl verify -CAfile chain.pem fullchain.pem 校验链。部署完成后务必在宝塔「安全」页与云厂商安全组同时放行 443,否则本机 curl 正常、公网访问不通。

五、Nginx 配置示例:TLS 1.2/1.3 + 完整证书链 + HSTS

server {
    listen 80;
    server_name example.com www.example.com;

    # 微信小程序域名校验文件必须能通过 80 直接访问,不能被 301 掉
    location ^~ /.well-known/acme-challenge/ { root /www/wwwroot/example.com; }
    location = /MP_verify_xxxxxxxx.txt { root /www/wwwroot/example.com; }

    location / { 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-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;
    resolver 223.5.5.5 119.29.29.29 valid=300s;

    add_header Strict-Transport-Security 'max-age=31536000' always;
    add_header X-Content-Type-Options nosniff always;

    root /www/wwwroot/example.com;
    index index.php index.html;
}

要点解析:ssl_certificate 必须指向 fullchain,ssl_trusted_certificate 只用于 OCSP Stapling 验证链,不参与握手;开启 Stapling 需要可用的 resolver,否则会拖慢首次握手;HSTS 首次上线建议先用 max-age=300 观察,确认全站资源均为 HTTPS 后再调到一年;小程序默认访问 443,不要配置非标准端口。修改后执行 nginx -t && nginx -s reload,测试失败时 Nginx 会保留旧配置,不会中断线上服务。

六、方案对比:验证方式、部署位置与证书类型怎么选

对比维度 DNS-01 验证 HTTP-01 文件验证
是否支持通配符 支持 不支持
是否依赖 80 端口 不需要 需要公网可访问
受 CDN/301 影响 无影响 容易被重定向打断
自动化程度 高(API 密钥) 中(webroot 目录)
适用场景 通配符、源站无公网 80、批量签发 单域名、临时验证
部署位置 优点 风险点
源站 Nginx / 宝塔 完全可控,排障路径短 需自行保障续期与重载
CDN / 负载均衡 卸载 TLS、集中管理多域 回源若走 HTTP,链路不闭环
容器 Ingress 随发布流水线自动化 Secret 更新后需触发重载

选型建议:单域名小程序站点用 DV + HTTP-01 即可;存在多级子域、或源站没有公网 80 时,直接上 DNS-01 + 通配符;面向政企的对外站点再考虑 OV。本质上,付费证书买的是有效期、赔付条款与人工支持,免费证书买的是“必须自动化”的运维纪律——两者在小程序兼容性上没有差别,前提都是完整证书链 + TLS 1.2 以上。预算有限时,把钱花在监控与自动化续期上,收益高于升级证书类型。

七、常见错误排查:5 个真实报错与修复命令

1. curl: (60) SSL certificate problem: unable to get local issuer certificate
原因:服务端只下发了站点证书,缺中间证书。修复:ssl_certificate 改用 fullchain;用 openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null | grep -c 'BEGIN CERTIFICATE' 验证,正常返回 2 或 3,返回 1 即缺链。

2. nginx: [emerg] PEM_read_bio_X509_AUX() failed (SSL: error:0909006C:PEM routines:get_name:no start line)
原因:证书与私钥写反、路径错误,或文件被 BOM 头污染。修复:head -1 fullchain.pem 应为 -----BEGIN CERTIFICATE-----;openssl rsa -in privkey.pem -check -noout 校验私钥;再比对 openssl x509 -noout -modulus -in fullchain.pem | md5sum 与私钥 modulus 是否一致。

3. 小程序 request:fail ssl handshake error
原因:TLS 版本过低、证书链不完整、SNI 未匹配或 CDN 回源异常。修复:确认 ssl_protocols 含 TLSv1.2;用 openssl s_client -tls1_2 -connect example.com:443 -servername example.com 测试握手;安卓旧机型还需避免仅含 ECDSA 的证书链。

4. net::ERR_CERT_DATE_INVALID
原因:证书过期,或服务器系统时间漂移。修复:timedatectl status、chronyc tracking,必要时 timedatectl set-ntp true;再用 openssl x509 -in fullchain.pem -noout -dates 核对 notBefore/notAfter。

5. SSL_ERROR_RX_RECORD_TOO_LONG,或面板显示“证书已到期”但文件正常
原因:443 端口被 HTTP 服务占用(例如只写了 listen 443; 却没加 ssl),或证书与私钥不匹配导致面板解析失败。修复:ss -lntp | grep 443 定位进程,检查该 server 块是否带 ssl 参数,修正后重载并复测。

八、效果验证:从命令行到真机的四层检查

# 1) 证书主体、有效期、颁发者、SAN
 echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
   | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 2) 证书链完整性(返回 2~3 为正常)
 echo | openssl s_client -connect example.com:443 -servername example.com -showcerts 2>/dev/null 
   | grep -c 'BEGIN CERTIFICATE'

# 3) 协议与加密套件枚举
 nmap --script ssl-enum-ciphers -p 443 example.com

# 4) 强制跳转与 HSTS 响应头
 curl -sI https://example.com | grep -Ei 'strict-transport|location|^http/'

四层验证清单:① 命令行层,上述四条全部通过;② 浏览器层,Chrome 地址栏无证书警告,SSL Labs 评级 A 及以上;③ 小程序层,在微信开发者工具中关闭「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」后,真机预览 wx.request 返回 200;④ 续期层,把 acme.sh --renew -d example.com --force --dry-run 加入月度巡检。

监控建议:用 openssl x509 -checkend 604800 -noout -in fullchain.pem 判断 7 天内是否过期,返回 1 即触发告警;同时监控 443 端口存活与 TLS 握手耗时,避免出现“证书没问题但服务挂了”的误判。对多域名站点,建议用脚本遍历全部域名逐个 openssl s_client 检测,防止某个子域漏续期拖垮整条业务线。

常见问题

免费证书(Let’s Encrypt)能用于微信小程序吗?

可以。小程序只要求证书由受信任 CA 签发、域名匹配、TLS 1.2 以上,对 DV/OV 类型没有限制。但 Let’s Encrypt 有效期只有 90 天,必须配置自动续期与 --reloadcmd 重载,否则 90 天后小程序会直接报 ssl handshake error。

SSL 证书最长有效期到底是多久?

目前公网信任证书单张最长有效期为 398 天(自 2020-09-01 起生效),Let’s Encrypt 为 90 天。CA/Browser Forum 已通过分阶段缩短方案,2026-03 起降至 200 天,后续还会继续缩短,因此不要再按“一年一换”的老经验做运维规划。

小程序必须使用已备案域名吗?可以填 IP 吗?

必须使用已完成 ICP 备案的域名,且不能填 IP 地址、localhost 或非标准端口。服务器域名需在微信公众平台「开发管理 → 服务器域名」中配置,每月可修改次数有限,上线前一次性规划好 request、uploadFile、downloadFile、socket 四类域名。

浏览器访问正常,但小程序仍报证书错误,怎么查?

按顺序排查四点:证书链是否完整(缺中间证书时桌面浏览器常能容错,安卓与小程序不容错)、是否只支持 TLS 1.0/1.1、是否 CDN 回源走 HTTP、证书 SAN 是否覆盖小程序实际请求的域名(含 www 前缀)。可用 openssl s_client -showcerts 与微信开发者工具的 Network 面板交叉验证。

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

*.example.com 只覆盖 a.example.com 这一级,不覆盖 a.b.example.com,也不覆盖裸域 example.com。实际部署时通常需要把裸域作为独立 SAN 一并签发,否则用户直接访问主域会报证书名称不匹配。

更换证书后还需要做哪些收尾动作?

执行 nginx -t && nginx -s reload 使配置生效;若前置了 CDN,需在控制台更新证书并刷新缓存;清理旧证书备份避免误加载;最后用真机与 openssl s_client 复测有效期与链完整性,并确认自动续期任务仍在 crontab 中。

内容审核

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