
「南京小程序服务器域名怎么配置」可以按三段收敛:先在小程序后台把域名按 API 用途填进对应分类,再确认域名本身满足协议、备案、端口、书写格式与证书要求,最后在真机上按报错关键词反查是哪一段没过。很多人把问题笼统归为「域名没配好」,实际常见故障里,证书链不完整、请求 URL 多写了端口、子域名没单独登记、开发者工具勾了「不校验合法域名」导致真机才暴露,各占一段,处理动作完全不同。下文按分类矩阵、前置条件、书写规则、证书与 TLS、报错反查、环境差异逐段列出可核验字段;域名数量、每月可修改次数、基础库版本要求会调整,落地时以微信开放文档「网络」章节和小程序后台当期提示为准。
先把判断放在前面:开发者工具里能跑通,不代表正式版能跑通。工具可以临时关闭请求域名、TLS 版本与 HTTPS 证书校验,手机开启调试模式时同样跳过校验,而正式版会逐项校验。因此域名类问题的复核必须在真机正式环境下完成,且要覆盖冷启动后首次请求、切后台再回前台、证书到期前后三类场景。把工具结果与真机结果分开记录,是定位这类问题成本最低的做法。
一、四类合法域名:按 API 用途分开登记
后台「服务器域名」不是一个输入框,而是按网络能力划分的几组列表。请求发往哪个域名,取决于代码里调用的是哪个接口;把域名填进错误分类,现象与「完全没配」几乎一样。下表把分类、接口、协议与常见错配列全,可直接当对照表使用。

| 分类 | 对应接口 | 协议 | 典型用途 | 常见错配 |
|---|---|---|---|---|
| request 合法域名 | wx.request | https | 业务接口、登录换凭证、列表数据 | 把图片 CDN 也填这里就以为万事大吉 |
| socket 合法域名 | wx.connectSocket | wss | 即时消息、实时状态推送 | 按 https 规则去配端口 |
| uploadFile 合法域名 | wx.uploadFile | https | 头像、凭证、表单附件上传 | 上传地址与业务接口域名不同却只配了一个 |
| downloadFile 合法域名 | wx.downloadFile、image 等资源加载 | https | 图片、文件、音视频资源 | 静态资源外移后忘了登记资源域名 |
| 业务域名 | web-view 组件 | https | 内嵌网页、活动 H5 | 与 request 合法域名混为一谈,忽略校验文件 |
| UDP / TCP | wx.createUDPSocket、wx.createTCPSocket | 按平台要求 | 局域网设备通信 | 直接拿公网域名思路套用 |
分类之外还有两条常被略过的约束:使用微信云托管时,通过私有协议调用可无需配置通讯域名;而 api.weixin.qq.com 出于安全考虑不能配置为服务器域名,相关接口也不能在小程序前端直接调用,应由开发者服务器发起并把结果转给小程序。把这两条写进接口设计文档,能避免后期为了「绕过域名校验」去做不该做的架构。
二、配置前置条件:六项不过,填了也保存不上
后台填写域名时报错,多半不是操作问题,而是域名本身不满足条件。下表把官方公开的硬性条件、不满足时的表现和取证方式列在一起,配置前逐项打勾,比反复点保存更有效。

| 条件 | 官方要求 | 不满足时的表现 | 取证方式 |
|---|---|---|---|
| ICP 备案 | 配置的域名须完成备案 | 后台保存被拒或提示域名不合规 | 备案查询加域名注册信息 |
| 协议 | 仅 https(request、uploadFile、downloadFile)与 wss(connectSocket) | 请求被拦截或后台不允许保存 | 配置项前缀与代码里 url 前缀 |
| 地址形式 | 不能用 IP 地址或 localhost,局域网 IP 属例外 | 测试地址能跑、提交后失败 | 全局搜索硬编码地址 |
| 父域名与子域名 | 不支持配置父域名覆盖全部子域名,各子域名单独登记 | 主域可访问、api 子域报错 | 列出全部请求主机名逐个比对 |
| 路径与参数 | 配置项只到域名与可选端口,不带路径、参数 | 后台格式校验失败 | 复制粘贴内容逐字符检查 |
| 官方接口域名 | api.weixin.qq.com 不能配置为服务器域名 | 前端调用被拒 | 接口发起方归属核对 |
还有一项运营层面的约束:后台对服务器域名的修改次数设有上限,且历年调整过。调试域名与生产域名来回切换会消耗次数,因此上线前把业务接口、上传、下载、长连接、静态资源、第三方服务涉及的主机名一次性列全,再统一登记。具体数值以平台当期公示为准,不要沿用旧文章里的固定数字。
三、书写规则:端口是最容易出错的一格
端口规则的细节比「能不能带端口」更多:https 分类里配置端口后,请求 URL 必须与配置完全一致;未配置端口时,请求 URL 也不能带端口,连默认 443 都不行。wss 分类则无需配置端口,默认允许该域名下所有端口。下表把允许与禁止的写法分开列,改配置时照着对。
| 场景 | 后台配置项 | 请求 URL 允许写法 | 会失败的写法 | 规则来源 |
|---|---|---|---|---|
| https 未配端口 | https://api.example.com | https://api.example.com/path | https://api.example.com:443/path | 未配置端口时 URL 不得含端口 |
| https 配了端口 | https://api.example.com:8080 | https://api.example.com:8080/path | https://api.example.com/path、:9091 | 配置后只能请求该端口 |
| wss 长连接 | wss://ws.example.com | 该域名下各端口的 wss 连接 | 写成 https 前缀 | wss 无需配置端口 |
| 带路径配置 | https://api.example.com/v1 | 无 | 任何保存尝试 | 配置项只到域名与端口 |
| 父域名通配 | https://example.com | 仅该主机 | https://api.example.com | 子域名需单独配置 |
| 局域网地址 | 按平台当期要求 | 同局域网非本机 IP | 本机 IP、localhost | 基础库版本相关例外 |
这里的 example.com 只作占位示例。实际项目里建议把所有请求主机名、端口、用途、所属分类写成一张内部台账,由后台配置、前端代码、服务端网关三方共同确认。域名变更时先改台账再动后台,能避免「前端换了新域名、后台还留旧域名」这类低频但代价高的故障。
四、证书与 TLS:真机上才暴露的那一层
小程序发起网络请求时会校验服务器 HTTPS 证书,校验失败请求无法发起。官方公开的证书要求包含:证书有效、根证书被系统内置信任、部署域名与证书颁发域名一致、证书在有效期内、信任链完整、iOS 不支持自签名证书且须满足苹果 ATS 要求、TLS 支持 1.2 及以上,同时部分旧 Android 机型 TLS 1.2 支持不全,服务器需保留向下兼容能力。下表把校验项、常见疏漏与检查手段对应起来。
| 校验项 | 要求 | 常见疏漏 | 检查手段 |
|---|---|---|---|
| 证书有效性 | 在有效期内且未被吊销 | 续期后只更新了部分节点 | 证书查看工具、openssl s_client |
| 信任链 | 服务器需部署完整证书链 | 只部署站点证书、漏中间证书 | openssl s_client -connect 域名:443 -showcerts |
| 域名匹配 | 部署域名与证书颁发域名一致 | 换了子域名但沿用旧证书 | 证书使用者可选名称核对 |
| 根证书信任 | 根证书已被系统内置 | 使用不被部分系统信任的 CA | 多机型真机复测 |
| TLS 版本 | 支持 1.2 及以上,兼顾旧机型兼容 | 只开了高版本或只留旧版本 | 服务端配置核对加在线检测 |
| 自签名证书 | iOS 不支持自签名证书 | 测试环境自签证书带到生产 | 证书签发方核对 |
| 终止 TLS 的节点 | 负载均衡、CDN、网关都要覆盖同一套证书 | 只更新源站、边缘节点仍是旧证书 | 按访问链路逐节点验证 |
证书问题的典型特征是「浏览器正常、小程序失败」:浏览器对证书链的处理更宽容,小程序与不同系统版本的要求更严格。换证书后如果请求失败,除了检查证书本身,还要确认所有终止 TLS 的节点都更新到位;图片加载失败、音视频无法播放等 HTTPS 资源异常,同样按这套证书流程排查。
五、报错反查:从关键词倒回配置
请求失败的日志里通常带着可定位的关键词。下表把常见现象、含义与定位顺序列出,按「关键词 → 配置台账 → 证书 → 环境」的顺序走,比反复改代码更快。

| 现象或关键词 | 指向的环节 | 定位顺序 | 处理动作 |
|---|---|---|---|
| 不在以下 request 合法域名列表中 / url not in domain list | 域名未登记或分类填错 | 请求主机名 → 所属分类 → 后台配置 | 补登记子域名、改到正确分类、重新编译 |
| ssl hand shake error / SSL handshake failed | 证书链或 TLS 版本 | 证书链完整性 → TLS 版本 → 机型 | 补全中间证书、调整 TLS 配置 |
| request:fail 且无更多上下文 | 网络、超时或被系统拦截 | 真机网络 → 超时配置 → 后台 5 秒切换 | 复现路径留日志、缩短请求、处理重试 |
| fail interrupted | 小程序进入后台后 5 秒内请求未结束 | 切后台时机 → 请求发起点 | 前置请求、回前台重发、避免后台长请求 |
| net::ERR_CONNECTION_REFUSED 类 | 服务端端口或安全组 | 端口 → 网关 → 安全组 | 放行 443,核对配置端口与请求端口一致 |
| 工具正常、真机失败 | 工具跳过了域名与证书校验 | 工具勾选项 → 手机调试模式 → 正式包 | 关闭豁免后用真机正式环境复测 |
| statusCode 非 200 却进 success | 回调语义理解偏差 | 业务判断分支 → 服务端返回 | 在 success 内按 statusCode 与业务码分流 |
| 图片空白但接口正常 | 资源域名或证书 | downloadFile 分类 → 资源域名证书 | 登记资源域名并按证书流程复核 |
官方文档里还有几条容易影响判断的运行约束:请求超时默认值与最大值均为 60 秒,可在 app.json 或单次调用的 timeout 配置,单次调用优先级更高;referer 头不可设置,格式由平台固定;wx.request、wx.uploadFile、wx.downloadFile 存在并发上限,wx.connectSocket 另有上限;服务端返回值建议使用 UTF-8,小程序只过滤一个 BOM 头;只要成功收到服务器返回,无论 statusCode 是多少都会进入 success 回调,业务错误必须在回调内自行判断。把这些写进请求封装层的注释,能减少大量误判。
六、环境差异:工具、调试模式、正式版分别校验什么
同一份代码在三个环境里校验强度不同,这是域名类问题「时好时坏」的主要来源。下表把每个环境的用途和边界列清,用于安排验证顺序。
| 环境 | 是否校验域名与证书 | 适合做什么 | 不能用来证明什么 |
|---|---|---|---|
| 微信开发者工具默认 | 校验 | 看请求 url、参数与返回结构 | 真机 TLS 兼容性与证书信任链 |
| 工具勾选「不校验合法域名、TLS 版本及 HTTPS 证书」 | 跳过 | 本地联调未备案的临时地址 | 配置是否完整、正式版能否请求 |
| 手机开启调试模式 | 跳过 | 真机看日志与渲染表现 | 域名白名单与证书校验结果 |
| 真机正式版 | 完整校验 | 上线前最终验收 | 不适用 |
| 微信云托管私有协议调用 | 按平台规则,可无需配置通讯域名 | 云托管场景的接口联通 | 普通 https 域名的配置正确性 |
验证顺序建议固定为:工具默认状态看请求结构 → 真机调试模式看逻辑与日志 → 关闭所有豁免、用真机正式版走一遍核心接口。把三个环境的结论分开记录,出现「上次能跑这次不行」时,先确认是不是环境换了,而不是先怀疑服务端。
七、上线前自检清单
- 列出全部请求主机名(业务接口、上传、下载、长连接、静态资源、第三方服务),逐个标注所属分类与端口。
- 在小程序后台逐类核对配置,确认每个子域名单独登记、配置项不含路径与参数、协议为 https 或 wss。
- 核对请求 URL 与后台配置的端口完全一致:未配端口时 URL 不带端口,连默认 443 也不写。
- 确认所有域名已完成 ICP 备案,且未使用 IP 地址、localhost 或 api.weixin.qq.com。
- 用 openssl s_client 或等效工具验证证书链完整、域名匹配、在有效期内,并检查所有终止 TLS 的节点。
- 确认服务端 TLS 支持 1.2 及以上,并在旧 Android 机型上保留向下兼容,同时满足 iOS 的 ATS 要求。
- 关闭开发者工具与手机调试模式的域名豁免,用真机正式版走核心接口、图片加载、文件上传下载、长连接四类请求。
- 在请求封装层写清超时配置优先级、并发上限、success 内按 statusCode 分流、切后台后请求中断的处理,并保留可按主机名检索的日志。
八、常见问题
问:小程序服务器域名怎么配置的?
在小程序后台「开发管理 – 开发设置 – 服务器域名」里,按 request、socket、uploadFile、downloadFile 分类分别填写,配置项只写协议加域名与可选端口,不带路径和参数;修改通常需要管理员验证。保存后重新编译并在真机正式版复测,工具与调试模式的豁免结果不算验收。
问:小程序服务器域名配置要求有哪些?
域名须完成 ICP 备案,协议限定 https(请求、上传、下载)与 wss(长连接),不能用 IP 地址或 localhost,不支持用父域名覆盖子域名,配置项不带路径与参数,api.weixin.qq.com 不可配置。域名数量与每月修改次数设有上限,以平台当期公示为准。
问:小程序 request 合法域名怎么填?
只填 wx.request 实际请求的主机名,例如业务接口域名;图片、下载文件、上传文件的域名要分别填进另外三类。若后台配置未带端口,请求 URL 也不能带端口,包括默认 443。子域名要单独登记,不能只填主域。
问:小程序 https 证书问题怎么排查?
按证书有效、根证书被系统信任、部署域名与证书一致、在有效期内、信任链完整、iOS 符合 ATS 且不用自签名、TLS 支持 1.2 及以上逐项核。用 openssl s_client -showcerts 看链是否完整,并确认负载均衡与 CDN 等终止 TLS 的节点都已更新。
问:小程序证书链不完整怎么办?
在服务器上补全中间证书,把站点证书与中间证书按 CA 提供的顺序合并部署,再用检测工具复核。浏览器可能容忍不完整链,小程序与部分系统版本不会;换证书后要按访问链路逐节点验证,而不是只查源站。
问:小程序业务域名配置异常怎么办?
业务域名服务于 web-view,与 request 合法域名不是同一组配置。按后台提示下载校验文件放到域名根目录,确认可通过 https 直接访问该文件,再回后台保存;静态资源被 Nginx 等规则拦截是常见原因。配完用真机打开内嵌页面复核。
问:小程序域名备案要求是什么?
配置到后台的服务器域名须完成 ICP 备案,这是保存与正式版请求的硬性条件。备案主体、域名解析与证书域名建议一并列进台账核对;备案信息变更或换了新子域名时,先确认备案状态再改后台配置。
问:小程序 tls 版本要求太高怎么办?
官方要求 TLS 支持 1.2 及以上,同时部分旧 Android 机型对 1.2 支持不全,因此服务器宜保留向下兼容,而不是把版本一刀切到最高。做法是在服务端配置中同时满足高版本要求与旧机型兼容,再用多机型真机复测,不要靠关闭工具校验绕过。
九、可复用的核验路径
这套判断不依赖任何二手结论:把全部请求主机名与分类列成台账,逐条对照小程序后台配置;用证书检测工具确认链完整、域名匹配与 TLS 版本;关闭工具与调试模式的校验豁免,在真机正式版分别走接口、图片、上传下载、长连接;最后把报错关键词与微信开放文档「网络」章节当期条款对齐。数量、次数、基础库版本会调整,按这条路径每次重新取证即可。
配图说明:本文部分配图使用人工智能生成合成技术制作。





