微信小程序与 iOS ATS 的 HTTPS 合规实践:通配符 SSL 证书申请、部署、排错全指南
一、问题背景:小程序与 iOS ATS 到底在卡什么
微信小程序里所有 wx.request 请求走的域名必须同时满足四个硬性条件:已完成 ICP 备案;域名不能带端口、不能带路径;可通过 HTTPS 正常访问;服务端 TLS 版本 ≥ 1.2。此外还要在「开发管理 → 开发设置 → 服务器域名」里把它配置为 request 合法域名,否则真机一律报“不在以下 request 合法域名列表中”。
iOS 端更严格,ATS(App Transport Security)默认要求:TLS 1.2 及以上、必须使用支持前向保密的密码套件(ECDHE 系列)、签名算法 SHA-256 及以上、RSA 密钥 ≥ 2048 位或 ECC ≥ 256 位、证书链完整且域名严格匹配。任何一条不满足,系统层直接断开连接,客户端只能看到一句笼统的“网络异常”,排查成本极高。
线上“证书明明买了却还是连不上”的案例,根因基本落在下表五类,而不是证书本身:
| 故障类型 | 典型表现 | 真实根因 |
|---|---|---|
| 证书链不完整 | Chrome 正常,小程序 / iOS 握手失败 | 只部署了叶子证书,缺少中间 CA |
| 协议版本过低 | request:fail ssl hand shake error | 服务端仍开启 TLS 1.0 / 1.1 或 SSLv3 |
| 域名不匹配 | ERR_CERT_COMMON_NAME_INVALID | 通配符只覆盖一级:*.example.com 不匹配 a.b.example.com |
| 缺少 SNI | 多站点服务器返回错证书 | 用 IP 直连或老客户端未发 SNI |
| 有效期异常 | certificate has expired or is not yet valid | 证书过期,或服务器时间漂移 |
这正是通配符证书(Wildcard)的价值所在:一张 *.example.com 可同时覆盖 api、img、m、pay、cdn 等所有一级子域,小程序、H5、App、CDN 回源共用一张,续期与部署成本最低。但必须记住两个边界:它不覆盖主域 example.com(需额外加一条 SAN),也不覆盖二级子域 a.b.example.com。
二、完整实操:从生成 CSR 到证书落地
第一步,生成私钥与 CSR。CN 写 *.example.com,同时把主域放进 SAN,避免主域再单独买一张证书:
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
openssl genrsa -out example.com.key 2048
openssl req -new -key example.com.key -out example.com.csr
-subj '/C=CN/ST=Beijing/L=Beijing/O=Example Tech Ltd/CN=*.example.com'
-addext 'subjectAltName=DNS:*.example.com,DNS:example.com'
openssl req -in example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
chmod 600 example.com.key
输出中必须出现 DNS:*.example.com, DNS:example.com,否则签出来的证书会漏域名。
第二步,选择验证方式。按 CA/B Forum 规则,通配符证书只能通过 DNS-01 验证,不能用 HTTP-01。用 acme.sh 配合云 DNS API 可全自动完成:
curl https://get.acme.sh | sh -s email=ops@example.com
export Ali_Key='LTAI********'; export Ali_Secret='********'
~/.acme.sh/acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256
~/.acme.sh/acme.sh --install-cert -d example.com
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd 'nginx -t && nginx -s reload'
若走商业 CA:把 CSR 提交后,DV 走 DNS TXT 或管理员邮箱验证,OV/EV 还需提交营业执照与组织信息,签发周期从 10 分钟到 3 个工作日不等。下载时务必选「Nginx / fullchain」格式,内容顺序是叶子证书 → 中间证书,切勿只下载域名证书。
第三步,校验链顺序与完整性:
openssl crl2pkcs7 -nocrl -certfile example.com.fullchain.pem | openssl pkcs7 -print_certs -noout
正常应输出两张:第一张 subject 为 *.example.com,第二张为中间 CA(如 DigiCert TLS RSA SHA256 2020 CA1、R3、Sectigo RSA DV Server CA)。顺序颠倒会让部分 Android WebView 与 Java 客户端报 unable to find valid certification path。
第四步,替换文件后执行 nginx -t 再 nginx -s reload,不要 restart,避免连接中断。此时用 curl -I https://api.example.com 应返回 200 且无证书告警。
三、服务端配置示例:TLS 1.2/1.3 + HTTP/2 + 防劫持
下面是可直接使用的 Nginx 站点配置,覆盖协议版本、密码套件、OCSP Stapling、HSTS 与 HTTP/2 五项关键点:
server {
listen 443 ssl http2;
server_name *.example.com 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-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305: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/chain.pem;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
}
server {
listen 80;
server_name *.example.com example.com;
return 301 https://$host$request_uri;
}
Apache 2.4 对应写法:SSLProtocol -all +TLSv1.2 +TLSv1.3、SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256、SSLUseStapling on、Protocols h2 http/1.1。注意 ssl_prefer_server_ciphers 在新版 Nginx 中建议设为 off,把套件选择权交给客户端,反而能获得更好的兼容性。
“防劫持”不是证书自带的属性,而是三件事的组合:其一,全站 301 跳转 + HSTS,让浏览器强制走 HTTPS,杜绝首次 HTTP 明文跳转被中间人替换;其二,配置 CAA 记录,限制只有指定 CA 能为该域名签发证书,防止误签发:
example.com. IN CAA 0 issue "letsencrypt.org"
example.com. IN CAA 0 issuewild ";"
其三,开启 CT(Certificate Transparency)日志监控,一旦出现陌生证书立即告警。三者叠加后,DNS 劫持与证书冒用都会在数小时内被发现。
四、证书选型对比:单域名、通配符、OV 与免费证书
选型前先明确两条当前规则:自 2020 年 9 月起,所有公有 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天;Let’s Encrypt 免费证书有效期固定 90 天,且必须自动化续期。CA/B Forum 已通过新规,2026 年 3 月起上限进一步降至 200 天,2027 年降至 100 天,长期看自动化是唯一可行路径。
| 类型 | 覆盖范围 | 验证方式 | 有效期 | 参考价位 | 适用场景 |
|---|---|---|---|---|---|
| DV 单域名 | 1 个具体域名 | DNS / 文件 | 398 天 | 数百元/年 | 单一 API 域名、测试环境 |
| DV 通配符 | *.example.com + 主域 | 仅 DNS-01 | 398 天 | 千元级/年 | 小程序 + H5 + App 多子域共用 |
| OV 单域名 | 1 个域名 | 组织材料核验 | 398 天 | 千元级/年 | 需要展示企业实名的对外系统 |
| OV 通配符 | *.example.com | 组织核验 + DNS | 398 天 | 数千元/年 | 金融、政企多子域统一管理 |
| 多域名 SAN | 3~100 个不同域名 | 逐个验证 | 398 天 | 按域名数加价 | 域名后缀不同的混合场景 |
| Let’s Encrypt 通配符 | *.example.com | DNS-01 | 90 天 | 免费 | 有自动化运维能力的团队 |
对绝大多数小程序项目,DV 通配符是最优解:成本低于多张单域名证书之和,子域扩展零成本,且 DV 与 OV 在浏览器和小程序端的加密强度、信任链完全一致,差异仅在于身份背书。需要注意的坑是:老版本 Android(7 以下)与部分 IoT 设备对 Let’s Encrypt 的 ISRG Root X1 信任链存在兼容问题,若小程序需要覆盖极旧机型,商业 CA 更稳妥。
五、常见错误排查:真实报错对照表
下面这张表来自实际工单,覆盖了 90% 以上的 HTTPS 接入失败场景,建议直接收藏:
| 报错原文 | 出现端 | 根因 | 处理 |
|---|---|---|---|
| curl: (60) SSL certificate problem: unable to get local issuer certificate | 服务端 / 命令行 | 缺中间证书 | 部署 fullchain 而非单证书 |
| request:fail ssl hand shake error | 微信小程序 | TLS 版本低或套件不兼容 | 开启 TLS 1.2/1.3,关闭 SSLv3 |
| net::ERR_CERT_COMMON_NAME_INVALID | 浏览器 / webview | 域名不在 SAN 中 | 核对通配符层级,补 SAN |
| NSURLErrorDomain Code=-1200 | iOS | ATS 不合规 | nscurl 逐项诊断 |
| x509: certificate has expired or is not yet valid | Go / Java 客户端 | 证书过期或服务器时间错误 | 校准 NTP,检查 notAfter |
| SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch | Nginx 启动 | 证书与私钥不配对 | 比对 modulus |
| nginx: [emerg] PEM_read_bio_X509_AUX() failed | Nginx 启动 | 路径错或文件格式错 | 确认文件以 —–BEGIN CERTIFICATE—– 开头 |
定位三把斧,按顺序执行即可锁定问题层:
# 1. 看服务端实际协商出的协议与套件
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher|Verify'
# 2. 比对证书与私钥是否配对(两个 md5 必须一致)
openssl x509 -noout -modulus -in example.com.fullchain.pem | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
# 3. iOS ATS 逐项诊断(在 macOS 上执行)
nscurl --ats-diagnostics https://api.example.com
还有一类不在证书层:微信后台保存域名失败。原因通常是域名未备案、填了端口(如 api.example.com:8443)、填了路径(如 /v1)或直接填 IP。这三类都属于配置格式错误,与证书无关。
六、效果验证:上线前必须跑完的六项检查
配置完成后不要只看浏览器绿锁,按下面六项逐条验收:
# ① 证书主体、签发者与有效期
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# ② 强制 TLS 1.1 必须失败(验证低版本已关闭)
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null
# ③ HTTP/2 是否生效
curl -sI https://api.example.com | head -1
# ④ 完整链路与证书链张数
openssl s_client -connect api.example.com:443 -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
检查 ② 若返回 handshake failure 或 no protocols available,说明 TLS 1.0/1.1 已正确禁用;检查 ④ 正常输出为 2(叶子 + 中间),若为 1 说明链不完整。
第五项,用 SSL Labs 跑分,目标 A 及以上,重点看「Certificate Paths」「Protocols」「Key Exchange」三栏是否全绿。第六项,在微信开发者工具「详情 → 域名信息」里查看当前请求域名的 TLS 版本与证书信息,再用 iOS 真机(非模拟器)走一遍完整业务链路——模拟器不校验 ATS,只有真机才暴露问题。
建议同时配置到期监控,用最简脚本即可:
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -enddate
# 输出 notAfter=Mar 15 12:00:00 2026 GMT,接入 Zabbix / Prometheus 做 30 天预警
七、自动化续期与防劫持监控
398 天看似很长,但证书过期仍是线上事故的头号原因。Let’s Encrypt 90 天周期下,人工续期完全不可行,必须走自动化。certbot 用户可直接验证续期链路是否通畅:
certbot renew --dry-run
systemctl list-timers | grep certbot
acme.sh 用户安装时会自动写入 crontab,确认一下:crontab -l | grep acme.sh,正常应看到 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null。通配符续期依赖 DNS API 凭据,务必确认 API Key 未过期、权限最小化(只授予 DNS 解析权限),否则续期会在第 60 天静默失败。
防劫持层面,除前文的 HSTS 与 CAA 外,还应订阅 CT 日志。可用 crt.sh 的公开接口做低成本巡检:
curl -s 'https://crt.sh/?q=%25.example.com&output=json' | jq -r '.[].name_value' | sort -u
把结果与自有域名清单比对,出现未登记的子域或陌生签发者立即排查。再配合 DNS 侧开启 DNSSEC、解析商开启双因子与操作审计,基本可封堵“DNS 被改指向 + 伪造证书”这条经典劫持链路。
最后提醒一个易被忽略的点:多台服务器、CDN、负载均衡上的证书必须统一管理。常见事故是主站已换新证书,CDN 回源节点仍是旧证书,导致部分地域用户间歇性握手失败。建议把证书文件纳入配置管理,通过 Ansible 或 CI 统一分发,并在每台节点上跑一次 openssl x509 -noout -enddate 做一致性校验。
常见问题
通配符证书能覆盖 a.b.example.com 这样的二级子域吗?
不能。通配符只匹配一级:*.example.com 覆盖 api.example.com、m.example.com,但不覆盖 a.b.example.com,也不覆盖主域 example.com。若业务存在多级子域,需为每一级单独申请通配符,或改用多域名 SAN 证书逐条列出。
小程序必须用付费证书吗?Let’s Encrypt 可以吗?
可以。微信小程序与 iOS ATS 校验的是协议版本、证书链完整性与域名匹配,并不区分免费或付费。只要 TLS ≥ 1.2、链完整、未过期即可正常通讯。但免费证书 90 天到期,必须确保自动化续期可靠;若需覆盖 Android 7 以下老机型,商业 CA 的兼容性更稳。
证书最长有效期到底是 398 天还是 1 年?
自 2020 年 9 月起,公有 CA 签发的证书最长有效期被限制为 398 天,所谓“1 年期证书”实际已是 398 天。Let’s Encrypt 固定 90 天。按 CA/B Forum 新规,2026 年 3 月起上限降至 200 天,2027 年降至 100 天,长期必须依赖自动化续期。
小程序报 request:fail ssl hand shake error 怎么快速定位?
先在服务器上执行 openssl s_client -connect 域名:443 -servername 域名 -tls1_2,若握手失败说明服务端未开启 TLS 1.2 或套件不兼容;若能成功,则检查证书链是否完整(-showcerts 应输出 2 张)、证书是否过期、域名是否在 SAN 中。三步基本可定位到具体层。
已经全站 HTTPS 了,还会被劫持吗?
会。HTTPS 只保护传输段,若 DNS 被篡改指向攻击者服务器,而攻击者又持有一张合法证书(误签发或社工签发),用户端仍会显示“安全”。因此必须叠加 HSTS(阻断首次 HTTP 降级)、CAA 记录(限制可签发 CA)、CT 日志监控(发现陌生证书)三道防线。
一张通配符证书能同时给小程序、公众号 H5、App 和 CDN 用吗?
可以,前提是这些入口使用同一主域下的一级子域。证书绑定的是域名而非应用类型。但要注意 CDN 与源站需部署同一张证书,且回源协议也要开启 HTTPS,否则会出现“边缘 HTTPS、回源 HTTP”的混合内容问题,部分客户端仍会告警。