跳到主要内容
HTTPS安装配置

小程序 SSL 证书申请、安装与配置全流程(微信/百度/抖音/支付宝通用)

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

微信、百度智能、抖音(字节)、支付宝四家小程序平台都强制网络请求走 HTTPS,并且对证书有一组硬性约束:必须由受信任的公有 CA 签发、证书链完整、域名与证书 SAN 匹配、TLS 协议版本不低于 1.2、禁止使用 IP 地址与自签名证书。iOS 端受 ATS(App Transport Security)约束,还要求密钥交换具备前向保密能力(ECDHE),RSA 1024 位、SHA-1 签名、3DES 套件一律被拒。

线上事故里最常见的一类是“证书过期”与“证书链不完整”。这里必须先纠正原文的两个过时事实:其一,Symantec 证书品牌已于 2017 年被 DigiCert 收购,2018 年之后新签证书由 DigiCert 根签发,市面上所谓“Symantec 一年证书”多为渠道话术,实际签发主体与有效期都变了;其二,自 2020 年 9 月 1 日起,CA/Browser Forum 规定公有 CA 签发的 TLS 证书最长有效期不得超过 398 天,所谓“一年证书”在技术上已不存在,Let’s Encrypt 更是只有 90 天。按已通过的缩短路线图,后续还会压到 200 天、100 天直至 47 天,所以自动化续期不是可选项,而是必选项。

典型报错:微信开发者工具控制台 request:fail ssl hand shake error;真机 errno: 600001;浏览器 net::ERR_CERT_AUTHORITY_INVALID、net::ERR_CERT_COMMON_NAME_INVALID;服务端 curl 报 SSL certificate problem: unable to get local issuer certificate。这几类分别指向“链不完整/根不受信”“域名不匹配”“缺中间证书”,排查路径完全不同,下文逐一给出可执行命令。

证书类型与选型对比

小程序后端一般只暴露一个 API 域名(如 api.example.com),选 DV 单域名即可;如果有 api、img、upload 多个二级域名,用通配符或多域名 SAN 更划算。需要提醒:通配符证书 *.example.com 只覆盖一级子域,不覆盖 a.b.example.com,也不能跨域。

类型 覆盖范围 验证方式 有效期 市场参考价(元/年) 适用场景
Let’s Encrypt DV 单域名 1 个精确域名 HTTP 文件 / DNS-01 90 天 0 有自动化运维能力的后端
商业 DV 单域名 1 个精确域名 文件 / DNS 最长 398 天 0 – 300 小程序 API 主域名
DV 通配符 *.example.com 一级子域 DNS TXT 为主 最长 398 天 400 – 1500 多子域、测试环境
OV 单域名 1 个域名 文件/DNS + 企业实名 最长 398 天 800 – 2500 金融、支付类合规要求
多域名 SAN 3 – 5 个不同域名 逐个验证 最长 398 天 1000 – 3000 跨主域的多个服务

选型时只看三点:域名数量、是否需要企业实名、能否接受 90 天续期频率。加密算法上,RSA 2048 兼容性最好;ECDSA P-256 握手更快、包体更小,iOS 12+ 与 Android 7+ 均支持,但如果还有 Android 6 以下存量用户,建议双证书(RSA + ECDSA)并行,由 Nginx 的 ssl_certificate 多行配置自动协商。

步骤一:生成私钥与 CSR

CSR 由服务端自己生成,私钥绝不出服务器。以下命令可直接执行(把域名、公司信息替换掉):

# RSA 2048,兼容性最好
openssl req -new -newkey rsa:2048 -sha256 -nodes 
  -keyout api.example.com.key 
  -out api.example.com.csr 
  -subj "/C=CN/ST=Guangdong/L=Shenzhen/O=Example Tech/OU=Ops/CN=api.example.com"

# ECDSA P-256,握手性能更好
openssl ecparam -genkey -name prime256v1 -out api.example.com.key
openssl req -new -key api.example.com.key -sha256 -out api.example.com.csr 
  -subj "/C=CN/ST=Guangdong/L=Shenzhen/O=Example Tech/CN=api.example.com"

chmod 600 api.example.com.key

几个容易踩的点:-nodes 表示私钥不加密,漏了它 Nginx reload 时会卡在交互式输密码导致启动失败;CN 只写一个域名,多域名必须靠 SAN,OpenSSL 1.1.1+ 可加 -addext "subjectAltName=DNS:api.example.com,DNS:www.example.com";CN 里写 IP 或写中文都会导致后续校验失败。

提交前先自检,确认私钥与 CSR 匹配、SAN 正确:

openssl rsa -in api.example.com.key -check -noout
openssl req -in api.example.com.csr -noout -text | grep -E "Subject:|DNS:|Public-Key"
# 对比两个模数是否一致(RSA)
openssl req -in api.example.com.csr -noout -modulus | openssl md5
openssl rsa -in api.example.com.key -noout -modulus | openssl md5

步骤二:域名验证(文件验证与 DNS 验证)

CA 必须确认你拥有该域名,主流两种方式。文件验证要保证 .well-known/pki-validation/ 目录可被公网直接访问,且不能返回 301/302 跳转、不能返回 HTML 页面:

mkdir -p /var/www/html/.well-known/pki-validation
# 把 CA 给的 fileauth.txt 上传到该目录
curl -s -o /dev/null -w "%{http_code}n" http://api.example.com/.well-known/pki-validation/fileauth.txt
curl -s http://api.example.com/.well-known/pki-validation/fileauth.txt

如果站点强制跳 HTTPS 或 Nginx 里有 location ~ /. 的 deny 规则,校验会返回 403/301,需显式放行:

location ^~ /.well-known/pki-validation/ {
    default_type text/plain;
    root /var/www/html;
    try_files $uri =404;
}

DNS 验证更省事,适合通配符证书。CA 会给一条 _dnsauth 的 TXT 记录,添加后用公共 DNS 确认已生效(注意 TTL,建议先设为 600 秒):

dig +short TXT _dnsauth.api.example.com
dig +short TXT _dnsauth.api.example.com @8.8.8.8
nslookup -type=TXT _dnsauth.api.example.com 223.5.5.5

常见失败原因:记录值被复制成带引号的两段字符串、域名前多了 www、该子域已有 CNAME 导致 TXT 冲突、CDN 厂商托管 DNS 未刷新。校验通过后 CA 一般 10 分钟到 2 小时内签发,DV 证书通常几分钟。

步骤三:Nginx / Apache 安装证书与 TLS 加固

拿到的通常是 api.example.com.crt + intermediate.crt(或 bundle)。必须把站点证书与中间证书按顺序拼成 fullchain.pem,顺序错了小程序一样握手失败:

cat api.example.com.crt intermediate.crt > fullchain.pem
# 校验拼接结果与顺序
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
server {
    listen 443 ssl;
    http2 on;                      # nginx >= 1.25.1;旧版写 listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/api.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: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;
    ssl_trusted_certificate /etc/nginx/ssl/chain.pem;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / { proxy_pass http://127.0.0.1:8080; }
}

server {
    listen 80;
    server_name api.example.com;
    location ^~ /.well-known/pki-validation/ { root /var/www/html; }
    location / { return 301 https://$host$request_uri; }
}

Apache 2.4 对应配置:SSLCertificateFile 指向 fullchain(2.4.8+ 支持证书链并入该文件),SSLCertificateKeyFile 指向私钥,SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1。改完执行 nginx -t && nginx -s reload 或 apachectl configtest && systemctl reload httpd。

步骤四:在小程序后台配置服务器域名

证书装好只是第一步,域名没进白名单,小程序仍然发不出请求。微信路径:mp.weixin.qq.com → 开发 → 开发管理 → 开发设置 → 服务器域名,需分别填 request 合法域名、socket 合法域名、uploadFile 合法域名、downloadFile 合法域名。硬性要求:域名已完成 ICP 备案、必须 HTTPS、不能带端口(固定 443)、不能是 IP 或 localhost、不能使用未备案的二级域。修改次数有限(当前约 5 次/月,以官方最新文档为准),改之前想清楚。

平台 配置入口 需配置项 特殊限制
微信 开发管理 → 开发设置 → 服务器域名 request / socket / uploadFile / downloadFile 需备案;不支持 IP 与端口;每月修改次数受限
百度智能 开发者后台 → 设置 → 开发设置 → 服务器域名 request / uploadFile / downloadFile 需备案;域名须与证书完全匹配
抖音 开发者平台 → 开发设置 → 服务器域名 request / uploadFile / downloadFile 需备案;不支持通配符填写,需写具体子域
支付宝 开放平台 → 开发设置 → 服务器域名白名单 httpRequest / uploadFile / downloadFile 需备案;白名单外请求直接拒绝

注意:白名单里填 https://api.example.com,而证书 CN/SAN 是 api.example.com,两者必须一致;若证书只签了 example.com,请求 api.example.com 会直接 ERR_CERT_COMMON_NAME_INVALID。

常见错误排查(含真实报错)

报错信息 根因 修复动作
request:fail ssl hand shake error 证书链不完整 / TLS 版本过低 / 套件不兼容 配置 fullchain.pem,开启 TLSv1.2+,检查 ssl_ciphers
errno: 600001 微信侧证书校验失败,多为根证书不受信 用 openssl s_client -CAfile 验证链,补齐中间证书
net::ERR_CERT_COMMON_NAME_INVALID 域名与证书 SAN 不匹配 重新签发含该域名的证书或改请求域名
net::ERR_CERT_AUTHORITY_INVALID 自签名证书或根 CA 不在系统信任列表 换公有 CA 证书
curl: (60) SSL certificate problem: unable to get local issuer certificate 服务端未下发中间证书 拼接 fullchain 并 reload
SSL_ERROR_NO_CYPHER_OVERLAP 客户端仅支持 TLS1.0/1.1,服务端已禁用 评估存量设备,必要时临时放开 TLSv1.1
x509: certificate signed by unknown authority Java/Go 服务端信任库未更新或链缺失 更新 ca-certificates,或把中间证书加入 truststore

定位三板斧,按顺序执行:

# 1) 看服务端到底下发了哪些证书(必须看到站点证书 + 中间证书)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -E "^ *[0-9]+ s:|i:"

# 2) 用系统信任库验证链是否完整
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"
# 期望:Verify return code: 0 (ok)

# 3) 模拟小程序客户端的 TLS 版本与套件
curl -vI https://api.example.com --tlsv1.2 --tls-max 1.2
nmap --script ssl-enum-ciphers -p 443 api.example.com

如果第 1 步只看到一张证书,就是典型的“漏装中间证书”,这是小程序报 ssl hand shake error 的第一大原因。

效果验证与到期监控

上线后做四项验证:证书链完整、有效期正确、协议版本达标、SAN 覆盖全部业务域名。SSL Labs 跑一次评级,小程序场景目标 A 及以上(A+ 需开 HSTS):https://www.ssllabs.com/ssltest/analyze.html?d=api.example.com。

# 有效期与 SAN 一次性核对
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null 
  | openssl x509 -noout -subject -dates -ext subjectAltName

# 检查是否残留 TLS1.0/1.1
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null 2>&1 | grep -i "alert|handshake failure"

398 天上限意味着必须有过期告警。一个 30 行的巡检脚本配 cron 每天跑即可,低于 15 天推企业微信/钉钉:

#!/usr/bin/env bash
DOMAIN="api.example.com"
end=$(echo | openssl s_client -connect ${DOMAIN}:443 -servername ${DOMAIN} 2>/dev/null 
      | openssl x509 -noout -enddate | cut -d= -f2)
left=$(( ( $(date -d "$end" +%s) - $(date +%s) ) / 86400 ))
echo "${DOMAIN} 证书剩余 ${left} 天(到期:${end})"
[ "$left" -lt 15 ] && echo "WARN: 证书即将过期,请立即续期"

用 Let’s Encrypt 的话,续期与重载必须绑定:certbot renew --deploy-hook "nginx -s reload",并 systemctl enable --now certbot.timer。换证书后无需重新提交小程序审核,只要域名不变,配置即刻生效。

常见问题

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

可以。只要证书链完整、域名匹配、TLS 1.2 以上,微信/百度/抖音/支付宝都正常识别。但要注意两点:一是 90 天有效期必须全自动续期,靠人工记日子几乎必然翻车;二是 DST Root CA X3 交叉签名到期后,Android 7.1 以下的老设备可能不再信任 ISRG Root X1,如果存量用户里有大量老旧安卓机,建议商业 DV 证书兜底。

通配符证书能覆盖多级子域吗?

不能。*.example.com 只匹配 api.example.com、img.example.com 这一级,不匹配 a.b.example.com。如果需要多级,要么单独签 *.b.example.com,要么使用多域名 SAN 证书逐个列出。另外通配符证书的验证基本只能走 DNS TXT,文件验证不适用于通配符。

浏览器访问正常,为什么小程序仍报 ssl hand shake error?

三个高概率原因:一是服务端只下发了站点证书、没带中间证书,桌面浏览器会自动补链(AIA Fetching),而小程序客户端不会;二是服务端仍启用 TLS 1.0/1.1 或用了 iOS 不接受的弱套件;三是同一 IP 上多张证书但未启用 SNI,或 CDN 回源时证书被替换。按上文 openssl s_client -showcerts 命令逐项核对即可定位。

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

公有 CA 签发的 TLS 证书当前上限为 398 天(2020 年 9 月 1 日起生效),Let’s Encrypt 为 90 天。按 CA/Browser Forum 已通过的路线图,后续会继续缩短到 200 天、100 天直至 47 天,所以“买一年省事”的思路已经彻底失效,自动化签发与续期(ACME)是唯一可持续方案。

小程序服务器域名必须是备案域名吗?

国内四家平台均要求域名已完成 ICP 备案,且必须是 HTTPS、不能带端口(固定 443)、不能填 IP 或 localhost。海外主体可走各平台的海外版通道,但域名与证书匹配规则不变。配置进白名单后,域名变更次数有限制,改之前先确认证书 SAN 已覆盖新域名。

更换证书后需要重新提交小程序审核吗?

不需要。证书属于服务端配置,只要请求域名不变,替换证书并 reload Nginx 后立即生效,不影响已发布的版本。但如果同时更换了域名,则必须更新各平台服务器域名白名单,白名单变更可能触发配置审核,建议在低峰期操作并保留旧证书 7 天以便回滚。

内容审核

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