小程序服务器域名配置教程｜request 与 upload 合法域名一次配对 – MPForge

一、报错长什么样：为什么工具正常、真机全挂

根源只有一个：开发者工具默认可勾选「不校验合法域名」，真机没有这个豁免。真机报错通常是这两条：

• request 类：「url 不在以下 request 合法域名列表中」——接口域名没配或写错协议。
• upload/download 类：文件上传下载直接失败——很多人只配了 request，漏了另外三类。

所有走自有服务器的小程序都受这条规则约束：请求域名必须是 HTTPS 且已 ICP 备案，不能用 IP，不能用端口写死的方式绕过。域名与证书的前置准备，可配合 小程序域名验证文件配置 一起做。

二、配置步骤：四类合法域名一次配齐

配置顺序固定：先列清单，再后台配置，最后真机回归。按这五步走：

1. 列域名清单：把小程序用到的所有接口按用途归类：数据请求、WebSocket、文件上传、文件下载，逐条写出完整域名。
2. 区分环境：测试与正式用不同子域名（如 api-test、api），提审前确认代码里指向正式域名，避免环境域名混用。
3. 后台配置：在小程序后台「开发管理—开发设置—服务器域名」逐类填入，协议选 HTTPS，端口不写默认 443。
4. 配业务域名：用了 web-view 的项目，业务域名必须单独配置并下载校验文件放到服务器指定目录，参考 小程序 web-view 使用注意事项。
5. 真机验证：体验版真机关闭调试模式，把四类请求各触发一次，逐一确认无域名报错。

三、检查清单：报错对照与达标口径

域名问题集中在证书、环境、遗漏三类，出问题先按这张表排查。

证书链可以用浏览器或 openssl 检查：任意一级缺失，部分安卓机型就会握手失败，而桌面浏览器正常——这也是「看起来没问题」的高发点。

四、修改限制与回滚：别把次数用光

合法域名每月可修改的次数有限，改一次就要珍惜一次。三条口径：

• 写清单再动手：后台每月修改次数有上限（以当期平台规则为准），先把四类域名一次性配齐，别挤牙膏式试错。
• 变更留痕：每次修改双人复核并截图存档，写清改动人、时间、影响的服务，出问题能快速定位。
• 预案先行：域名迁移时新旧域名并行一段时间，旧域名先停写不停读，请求层做好重试，参考 小程序请求重试与超时处理。

上传下载相关的前端约束（大小、类型、并发）另见 小程序文件上传大小与类型限制，域名配好后仍传不上去时先查这两层。

五、避坑清单

这四条坑都在真实项目里花过整晚，配置完逐条对照。

• 别只测工具：工具里关掉「不校验合法域名」再跑一遍，能提前暴露大多数问题。
• 别用 IP 顶着：临时 IP 调试的代码忘了改回来，是最典型的提审翻车原因。
• 别忘证书链：更新证书后用多台安卓真机各访问一次，别只看桌面浏览器。
• 别混环境：测试与正式域名分离命名，发布前全局搜索测试域名做一遍确认。

六、常见问题 FAQ