小程序二级域名的正确配置，核心在于完成ICP备案、HTTPS证书绑定、以及在小程序后台将二级域名加入request/uploadFile合法域名列表。 顺序不能错,否则会出现无法请求或域名不合法提示。
为什么要用二级域名：主域名与小程序的适配问题
很多开发者在接入小程序时，第一反应是直接复用官网主域名，但主域名往往承载着H5页面、用户中心、后台接口等业务，改Nginx配置或者换证书，都有牵一发动全身的风险，二级域名相当于给小程序开了一条专用车道，它和主域名共用同一个根域，却可以独立解析、独立配证书,出了故障也不影响主站。
行业共识认为，小程序对请求域名的要求非常苛刻：必须是HTTPS、必须备案、不能带端口，二级域名恰好能精准满足这套规则,同时把小程序流量和核心业务隔离。
小程序二级域名和小程序后台域名设置有什么关系
小程序后台的「服务器域名」配置页面，要求填写完整的域名，不能带路径，也不能带端口，如果你有一个 example.com，可以划出 api.example.com 专门给小程序用，配置时在小程序后台添加 https://api.example.com，小程序发起的网络请求就都会走这个二级域名，而不是直接打到主站上,便于日志分析和权限控制。
小程序二级域名怎么配置：从零到可用的完整流程
配置前先确认三样东西：域名已完成ICP备案、服务器可用、SSL证书已申请，缺一不可，如果域名没有备案，小程序会在请求阶段直接拦截，报错信息里会明确提示“域名未备案”。
第一步：给二级域名添加解析记录
登录你的DNS服务商控制台，简米云、酷番云或者Cloudflare都可以，找到域名解析列表，添加一条A记录或CNAME记录，想让 api.example.com 指向服务器IP，就选A记录，主机记录填 api，记录值填服务器公网IP，如果服务商提供负载均衡或CDN地址，选CNAME更合适，保存后，在本地终端执行 ping api.example.com,看到返回IP说明解析已经生效。
第二步：为二级域名绑定SSL证书
小程序要求所有请求域名必须是HTTPS，所以SSL证书是硬性条件，对小程序接口来说，DV证书就够用，不需要OV或EV，到证书管理后台申请一张绑定
api.example.com 的证书，然后部署到Nginx或Apache，以Nginx为例,在配置文件的server块里填入证书路径：
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/api.example.com.pem;
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
}注意证书必须和域名完全匹配，如果证书只绑定了 example.com，而没有绑定 api.example.com，小程序端会提示“SSL证书无效”,浏览器也会显示不安全。
第三步：配置小程序后台合法域名
登录微信公众平台，进入「开发」-「开发管理」-「开发设置」-「服务器域名」，在 request合法域名 里添加 https://api.example.com，如果小程序需要上传文件，同步在 uploadFile合法域名 里添加对应域名；下载文件则填到 downloadFile合法域名，保存后一般几分钟内生效,不需要重新提交审核。
小程序二级域名需要ssl证书吗：这个问题的答案很明确
需要，而且必须是由正规CA机构签发的有效证书，自签名证书在浏览器里可以强制信任，但小程序端会直接拒绝，因为它不在系统信任链里，部署完成后，建议在浏览器打开 https://api.example.com，确认地址栏出现锁形图标，然后点开证书详情,查看域名是否完全匹配。
配置完成后如何验证：常见报错与解决办法
配置完不等于能跑通，最常见的现象是域名已经填进后台，但小程序请求仍然失败,这时需要按顺序排查。
验证HTTPS是否真正可用
在服务器本地或本机终端执行 curl -I https://api.example.com，如果返回 HTTP/2 200 或 HTTP/1.1 200，说明HTTPS已经正常，如果出现 SSL certificate problem，说明证书链不完整，有些云服务商默认只部署了叶证书，缺少中间证书，会导致一部分安卓机型无法访问，可以用在线工具检测证书链,把中间证书补齐到服务器上。
小程序二级域名配置后出现“不在以下合法域名列表中”
这个报错信息很直接，意思是后台没有添加，或者添加后没生效，先回小程序后台核对域名是否完全一致，注意 http 和 https 不能混用，末尾也不能带 ，开发工具里勾选“不校验合法域名”只能解决本地调试，真机预览时依然会校验,所以不要依赖这个开关。
二级域名解析正确但无法访问的排查顺序
排查顺序可以这样：先看域名是否备案，再看服务器防火墙有没有放行443端口，最后看Nginx配置是否有语法错误，用 nginx -t 检查配置，用 systemctl status nginx 查看服务状态，如果服务器在中国大陆，还需要确认域名是否完成公安备案,微信小程序对没有公安备案的域名会限制访问。
| 报错信息 | 常见原因 | 解决办法 |
|---|---|---|
| 域名不在合法域名列表 | 后台未添加或URL不一致 | 到服务器域名配置页添加完整HTTPS域名 |
| SSL证书无效 | 证书域名不匹配或自签名 | 申请并部署与二级域名匹配的有效证书 |
| 无法连接服务器 | 443端口未放行或服务未启动 | 检查防火墙规则和Nginx运行状态 |
小程序二级域名的使用场景与细节：从开发到上线
用二级域名区分开发环境与生产环境
不少团队在联调阶段会用同一个域名来回切换环境，结果上线后才发现微信端缓存了旧的DNS解析，导致正式环境偶发请求到测试服务器，建议测试环境用 test-api.example.com，生产环境用 api.example.com，两个域名分别备案、分别配证书，虽然前期多花一点时间,但后续排错会轻松很多。
网页授权与业务域名的区别
如果小程序里嵌入了网页，还需要在「业务域名」里配置网页跳转的域名，业务域名和request合法域名可以相同，但必须在根目录放置一个校验文件，而且域名同样需要备案，业内专家指出，常见错误是只配置了request合法域名，忘记配置业务域名，导致微信内打开的网页提示“非官方页面”，这个小细节越早处理,越省心。
小程序二级域名价格和选择要不要花钱
二级域名本身没有单独费用，你只需要为已有的主域名增加一条解析记录，真正花钱的地方在SSL证书，免费证书如Let’s Encrypt可以满足小程序基本要求，但有效期只有90天，需要配置自动续期，付费证书适合对兼容性要求高的场景，价格从几十元到几百元不等，具体看品牌和通配符范围，多数情况下，小程序接口域名用免费证书就够用,但一定要做好续期监控。
多环境部署时如何维护证书
如果同一个二级域名需要部署在多台服务器上，比如负载均衡场景，可以在每台服务器上都部署相同证书，或者把证书统一放在网关层，注意私钥不要通过聊天工具或明文邮件传输，证书到期前一个月内要续期，续期后重新部署并重启Web服务,避免服务一直跑着旧证书。
小程序二级域名的价值就是隔离和可控，接口单独走一个二级域名后，主站改版和证书更新都不牵连，按备案、解析、证书、后台合法域名的顺序做,基本一次过。
小程序二级域名配置常见问题 Q&A
小程序可以不使用二级域名，直接使用主域名吗？
可以使用主域名，但前提是主域名已经备案且部署了有效HTTPS证书，不过主域名往往用于官网或H5活动页，修改配置可能影响其他业务，二级域名可以独立管理，互不干扰，更安全,建议单独配置。
小程序二级域名和主域名的备案有关系吗？
有关系，二级域名不需要单独备案，只要主域名已经备案，且二级域名解析到同一备案主体的国内服务器即可，如果服务器在中国大陆，备案主体必须一致，如果使用香港或海外服务器，则不需要公安备案,但可能面临延迟问题。
小程序请求接口时提示“无法连接服务器”怎么排查？
先确认 https://api.example.com 在浏览器能否打开，不能打开就回到解析和证书步骤，能打开但小程序连不上，检查合法域名列表是否已保存，以及是否使用了正确的域名,开发工具里的域名配置需要点击刷新或重新编译才能生效。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/%e5%b0%8f%e7%a8%8b%e5%ba%8f%e4%ba%8c%e7%ba%a7%e5%9f%9f%e5%90%8d%e5%a6%82%e4%bd%95%e6%ad%a3%e7%a1%ae%e9%85%8d%e7%bd%ae%e4%b8%8e%e4%bd%bf%e7%94%a8%ef%bc%9f%ef%bc%8c%e5%b0%8f%e7%a8%8b%e5%ba%8f%e4%ba%8c/
