小程序开发

南京小程序服务器域名怎么配置?2026 合法域名、ICP 备案、HTTPS 证书与请求失败排查清单

2026年11月15日

专业技术文章

南京小程序服务器域名怎么配置?2026 合法域名、ICP 备案、HTTPS 证书与请求失败排查清单

发布时间:2026年11月15日
|作者:易企达网络|来源:南京易企达网络科技有限公司||
浏览:1,895
南京小程序服务器域名怎么配置:合法域名、ICP 备案、HTTPS 证书与请求失败排查清单
封面:域名、证书、请求报错是三段独立链路,配置只是其中一段。

「南京小程序服务器域名怎么配置」可以按三段收敛:先在小程序后台把域名按 API 用途填进对应分类,再确认域名本身满足协议、备案、端口、书写格式与证书要求,最后在真机上按报错关键词反查是哪一段没过。很多人把问题笼统归为「域名没配好」,实际常见故障里,证书链不完整、请求 URL 多写了端口、子域名没单独登记、开发者工具勾了「不校验合法域名」导致真机才暴露,各占一段,处理动作完全不同。下文按分类矩阵、前置条件、书写规则、证书与 TLS、报错反查、环境差异逐段列出可核验字段;域名数量、每月可修改次数、基础库版本要求会调整,落地时以微信开放文档「网络」章节和小程序后台当期提示为准。

先把判断放在前面:开发者工具里能跑通,不代表正式版能跑通。工具可以临时关闭请求域名、TLS 版本与 HTTPS 证书校验,手机开启调试模式时同样跳过校验,而正式版会逐项校验。因此域名类问题的复核必须在真机正式环境下完成,且要覆盖冷启动后首次请求、切后台再回前台、证书到期前后三类场景。把工具结果与真机结果分开记录,是定位这类问题成本最低的做法。

一、四类合法域名:按 API 用途分开登记

后台「服务器域名」不是一个输入框,而是按网络能力划分的几组列表。请求发往哪个域名,取决于代码里调用的是哪个接口;把域名填进错误分类,现象与「完全没配」几乎一样。下表把分类、接口、协议与常见错配列全,可直接当对照表使用。

小程序四类服务器域名:普通请求对应 request、长连接对应 socket、上传文件对应 uploadFile、下载文件对应 downloadFile
图 1:四类域名与四类网络接口一一对应,填错分类等同于没配。
分类 对应接口 协议 典型用途 常见错配
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、不用 IP 地址、端口完全一致、子域名单独配、官方接口禁用
图 2:六项前置条件分别卡在资质、协议、地址形式、端口与域名粒度上。
条件 官方要求 不满足时的表现 取证方式
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 资源异常,同样按这套证书流程排查。

五、报错反查:从关键词倒回配置

请求失败的日志里通常带着可定位的关键词。下表把常见现象、含义与定位顺序列出,按「关键词 → 配置台账 → 证书 → 环境」的顺序走,比反复改代码更快。

小程序请求失败五步排查:看报错关键词、核域名与端口、验证书链完整、查 TLS 版本、真机复核结果
图 3:五步按从配置到运行环境的顺序收敛,避免一上来改业务代码。
现象或关键词 指向的环节 定位顺序 处理动作
不在以下 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 域名的配置正确性

验证顺序建议固定为:工具默认状态看请求结构 → 真机调试模式看逻辑与日志 → 关闭所有豁免、用真机正式版走一遍核心接口。把三个环境的结论分开记录,出现「上次能跑这次不行」时,先确认是不是环境换了,而不是先怀疑服务端。

七、上线前自检清单

  1. 列出全部请求主机名(业务接口、上传、下载、长连接、静态资源、第三方服务),逐个标注所属分类与端口。
  2. 在小程序后台逐类核对配置,确认每个子域名单独登记、配置项不含路径与参数、协议为 https 或 wss。
  3. 核对请求 URL 与后台配置的端口完全一致:未配端口时 URL 不带端口,连默认 443 也不写。
  4. 确认所有域名已完成 ICP 备案,且未使用 IP 地址、localhost 或 api.weixin.qq.com。
  5. 用 openssl s_client 或等效工具验证证书链完整、域名匹配、在有效期内,并检查所有终止 TLS 的节点。
  6. 确认服务端 TLS 支持 1.2 及以上,并在旧 Android 机型上保留向下兼容,同时满足 iOS 的 ATS 要求。
  7. 关闭开发者工具与手机调试模式的域名豁免,用真机正式版走核心接口、图片加载、文件上传下载、长连接四类请求。
  8. 在请求封装层写清超时配置优先级、并发上限、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 版本;关闭工具与调试模式的校验豁免,在真机正式版分别走接口、图片、上传下载、长连接;最后把报错关键词与微信开放文档「网络」章节当期条款对齐。数量、次数、基础库版本会调整,按这条路径每次重新取证即可。

配图说明:本文部分配图使用人工智能生成合成技术制作。

《南京小程序服务器域名怎么配置?202…》是我们在南京做小程序开发时的实际实施记录。费用与交付范围以双方合同及平台当期规则为准。需要评估自己的项目,可以到联系页留下需求与预算范围。

相关文章

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

南京小程序图片上传与压缩怎么配置?2026 选图、压缩、上传链路与失败排查清单

小程序图片上传是否稳定,取决于四段链路:选图参数是否用对、压缩是否在正确时机执行、上传地址是否在合法域名内、返回地址是否...

2026年11月21日

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

南京小程序 web-view 怎么配置?2026 业务域名、双向通信、跳转限制与白屏排查清单

小程序 web-view 能否按预期工作,取决于四个前置条件:主体类型、业务域名与校验、通信是否遵守 postMessa...

2026年11月21日

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

南京小程序分享转发怎么配置?2026 转发灰色排查、带参归因与朋友圈限制清单

小程序分享转发的可用前置条件是页面级回调、未隐藏菜单、认证备案与版本兼容。转发给朋友与分享到朋友圈是两套独立能力,字段、...

2026年11月20日

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

南京小程序数据埋点怎么设置?2026 留存口径、事件模型与上报失败排查清单

小程序数据埋点能否支撑留存分析,结论取决于指标口径、事件模型与上报链路是否先定死。基础统计做大盘校准,自定义分析做单事件...

2026年11月20日

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

南京小程序本地存储怎么配置?2026 容量上限、隔离规则、同步异步与清理策略清单

小程序本地存储的结论先行:storage 独立于代码包,按用户维度隔离,单 key 上限 1MB、同一用户同一小程序总量...

2026年11月19日

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

南京小程序版本灰度与回滚怎么操作?2026 全量与分阶段发布、版本回退与异常反查清单

小程序版本发布与回退的结论先行:全量发布即时覆盖用户,分阶段发布在十五天内按自定义比例逐步覆盖并默认到期全量;撤销分阶段...

2026年11月19日