小程序域名校验文件部署教程｜校验失败原因与正确姿势 – MPForge
直接回答：小程序域名校验文件报 404 或校验不通过，问题基本逃不出四类：路径不对、HTTPS 证书异常、回源改写吞了文件、域名没备案。这篇小程序域名校验文件部署教程写给正在配 request 合法域名的开发与运维：按「放文件、验公网、点校验、真机测、留切换窗口」的顺序走，并且记住一条——开发工具能过不代表真机能过。MPForge（DEVDIY 旗下）处理域名问题，第一步永远是拿浏览器直接访问那个文件。
一、先搞懂校验文件为什么会被拦
结论先记住：平台校验的是「这个域名确实归你管」，文件读不到，所有权就证明不了。
校验失败时按四类对号入座：
- 路径不对：文件没放在站点根目录下要求的精确路径，或者放错了环境的机器。
- HTTPS 或证书问题：证书过期、证书链不全、只配了 http——校验要求公网 HTTPS 可正常访问。
- 回源与改写：CDN 回源 Host 改写、Nginx 重定向规则把校验文件请求转发去了首页。
- 域名本身不合规：填了未备案域名或 IP 直连，这条路在源头就走不通。
特别提醒：开发者工具里勾了「不校验合法域名」就能跑，很多人误以为域名配好了，到真机上 request 全部报错——真机验证永远是验收标准。
二、部署前的材料清单
结论先记住：四样材料里，最容易缺的是「根目录部署权限」——没有它，再懂原理也放不了文件。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 校验文件原文 | 按提示下载原始文件，不改名不转存 | 多环境拷错文件，内容对不上 |
| 根目录部署权限 | 能直接写站点根目录，或走发布流程当天生效 | 权限要走审批，文件迟迟上不去 |
| 证书状态 | 证书在有效期，证书链完整，HTTPS 可访问 | 只看了域名解析，没验证书 |
| CDN/Nginx 配置 | 校验文件路径不做重定向，回源 Host 正确 | 全站 301 规则把文件请求也吞了 |
request 合法域名的整体配置逻辑（每个小类各自的口径）见 服务器域名配置说明，web-view 业务域名的差异见 业务域名配置注意。
三、五步部署：从放文件到真机验证
结论先记住：顺序是「放文件、验公网、点校验、真机测、留窗口」，每步的验收点都很明确。
- 按提示部署文件：把下载的校验文件原样放到指定路径，文件名、内容一个字符都不改。
- 公网 HTTPS 自测：浏览器直接打开该文件的完整 URL，能原样返回内容且证书无告警，才算过。
- 后台点校验：回到小程序后台提交校验；失败时先按第一节的四类原因逐个排查，别急着重传文件。
- 真机预览验证：关掉「不校验合法域名」，真机上把 request、上传、下载各请求跑一遍。
- 变更留切换窗口：以后更换域名时，新旧域名并行一段时间再下线旧的，避免线上请求瞬间断掉。
验收口径：真机不勾任何跳过选项，所有网络请求正常返回；校验文件的公网 URL 存进运维文档，随时可复查。
四、高频翻车点与对应处理
结论先记住：域名翻车多发生在「配置改了但没人重验」，把重验变成流程的一部分。
| 场景 | 处理口径 | 常见错误 |
|---|---|---|
| CDN 回源 Host 变更 | 变更后重新点一次校验，并复查文件 URL | 改完配置没重验，数天后突然失效 |
| 全站重定向规则 | 校验文件路径加豁免，直接返回原文件 | 文件被 301 到首页，校验必挂 |
| 多环境并行 | 测试、生产域名隔离，文件各放各的 | 测试文件拷到生产，内容对不上 |
| 联调环境 | 临时隧道只用于调试，不进生产配置 | 隧道域名写进合法域名清单 |
其中「校验文件被重定向」最隐蔽：浏览器访问时跳回首页看起来「网站正常」，但校验器拿到的是 HTML 而不是文件内容，排查时要用命令行看原始响应。
五、避坑清单
这四条都能帮你省掉一次深夜排查：
- 别用 IP 直连：request 合法域名必须是备案过的 HTTPS 域名，IP 与 http 都进不了白名单。
- 子域用到就配：每个实际请求到的子域名都要配置并单独校验，没有「配主域全包」这回事。
- 云存储按实际目标配：请求打向哪个域名就配哪个，对象存储的下载域名也要单独过校验。
- 变更后必重验：回源、证书、重定向三类变更之后，把校验文件 URL 重新访问一遍再收工。
六、常见问题 FAQ
每个子域名都要单独校验吗？
是。用到的子域名都要逐个配置并部署校验文件，主域配好不代表子域自动生效。
云存储和 CDN 的域名怎么算？
按实际请求目标配置：小程序请求打到哪个域名，哪个域名就要在合法域名清单里并完成校验，包括对象存储的下载域名。
开发时用内网穿透行不行？
临时隧道只用于本机调试，不能也不该配进生产；生产环境用固定备案域名，两者彻底分开。
域名校验和小程序 GEO 地理位置配置有关系吗？
没有关系。GEO 指地理位置配置：门店地址、经纬度、服务类目，用于「附近」检索展示，不是地域 SEO；域名校验属于网络请求合规，两套配置互不影响。
校验通过后还能改服务器配置吗？
能，但涉及回源 Host、重定向规则、证书的变更，改完必须重新访问校验文件 URL 确认仍可原样返回，必要时重跑一次校验。
