tencent cloud

腾讯云超级应用服务

动态与公告
【2025年1月2日】关于腾讯云小程序平台更名为腾讯云超级应用服务的公告
控制台更新动态
Android SDK 更新动态
iOS SDK 更新动态
Flutter 更新动态
IDE 更新动态
基础库更新动态
产品简介
产品概述
产品优势
应用场景
购买指南
计费概述
按量计费(后付费)
续费指引
停服说明
快速入门
套餐管理
概述
控制台账号管理
存储配置
加速配置
品牌化配置
平台功能
控制台登录
用户和权限体系
小程序管理
小游戏管理
应用管理
商业化
平台管理
用户管理
团队管理
运营管理
安全中心
代码接入指引
Demo 及 SDK 获取
Android
iOS
Flutter
App 服务端接入指南
GUID 生成规则
小程序开发指南
小程序介绍与开发环境
小程序代码组成
指南
框架
组件
API
服务端
JS SDK
基础库
IDE 使用指南
小游戏开发指南
指南
API
服务端
实践教程
小程序登录实践教程
小程序订阅消息实践教程
支付相关实践教程
广告接入实践教程
小游戏订阅消息实践教程
相关协议
数据处理和安全协议

网络

PDF
聚焦模式
字号
最后更新时间: 2026-02-11 11:48:38
说明:
在小程序中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。

服务器域名配置

每个小程序需要事先设置一个通讯域名,小程序只可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(wx.request)、上传文件(wx.uploadFile)、下载文件(wx.downloadFile)和 WebSocket通信(wx.connectSocket)、UDP通信(wx.createUDPSocket)、TCP通信(wx.createTCPSocket)。
网络接口只允许与同个局域网内的非本机 IP 以及配置过的服务器域名通信。

配置流程

服务器域名请在小程序后台 > 小程序管理 > 开发管理 > 域名设置 中进行配置,配置时需要注意:
域名支持 HTTPSwx.requestwx.uploadFilewx.downloadFile)协议、 WSSwx.connectSocket)协议及 TCP 协议和 UDP 协议;
域名不能使用 IP 地址或 localhost;
不可以配置端口,如 http://miniApp.com,但请求的 URL 中可以包含端口,例如 http://miniApp.com:8080。
对于 WSS 域名,无需配置端口,默认允许请求该域名下所有端口。
不支持配置父域名,使用子域名。

网络请求

超时时间

默认超时时间和最大超时时间都是60s。
超时时间可以在 app.json 中配置。
也可以在接口调用时指定超时时间,如 wx.request({ timeout: 5000 }),单位为ms。接口调用的timeout配置优先级高于app.json中的配置。

使用限制

网络请求的 referer header 不可设置。其格式固定为 https://appservice.qq.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为0表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。
wx.requestwx.uploadFilewx.downloadFile的最大并发限制是 10 个。
wx.connectSocket 的最大并发限制是 5 个;
小程序进入后台运行后,如果 5s 内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用。

返回值编码

建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。
小程序会自动对 BOM 头进行过滤(只过滤一个 BOM 头)。

回调函数

只要成功接收到服务器返回,无论statusCode是多少,都会进入success回调。请开发者根据业务逻辑对返回值进行判断。

常见问题

HTTPS 证书

小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求。
对证书要求如下:
HTTPS 证书必须有效;
证书必须被系统信任,即根证书已被系统内置。
部署 SSL 证书的网站域名必须与证书颁发的域名一致。
证书必须在有效期内。
证书的信任链必须完整(需要服务器配置)。
iOS 不支持自签名证书。
iOS下证书必须满足苹果 App Transport Security (ATS) 的要求。
TLS 必须支持1.2及以上版本。部分旧Android机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持1.1及以下版本。
部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。
说明:
证书有效性可以使用 openssl s_client -connect example.com:443 命令验证,也可以使用其他 在线工具
除了网络请求 API 外,小程序中其他 HTTPS 请求如果出现异常,也请按上述流程进行检查。如 https 的图片无法加载、音视频无法播放等。

跳过域名校验

在开发者工具中,可以临时开启开发环境不校验请求域名、TLS版本及 HTTPS 证书 选项,跳过服务器域名的校验。此时,在开发者工具中及手机开启调试模式时,不会进行服务器域名的校验。
在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。
说明:
如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确。
如遇到“服务器内部错误”,请尝试以下办法自查 ①更换浏览器 ②刷新网页 ③排查文件是否放在正确的服务器根目录下。 排查办法:按照以下规则拼接网址,并且自行尝试访问是否成功:https://m.da9c.cn/文件名。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈