小程序全局loading必须在uni.request的complete回调中统一hide，因timeout/fail/abort均不触发success但都进complete；支持按接口控制需参数化loading开关，默认true，文案可定制，且需防页面切换导致的上下文错位。
小程序端的全局 Loading 必须走 uni.request 封装层 + complete 回调统一收口，否则必卡死——因为 fail、timeout、abort 都不会触发 success，但都会进 complete。
uni.request 的 complete 回调为什么是唯一可靠出口
小程序平台（微信/支付宝/字节）下，uni.showLoading 一旦调用，就必须配对 uni.hideLoading，否则 loading 框会永远挂住。而 success 和 fail 两个回调不覆盖全部完成路径：
- 网络超时（
timeout设置后触发）→ 不进success，也不进fail，只进complete - 用户手动取消请求（如 navigateBack 中断）→ 触发
fail，但部分基础库版本下fail可能不执行 - SSL 证书错误、域名未配置、跨域拦截 → 微信小程序直接静默失败，仅
complete可捕获
所以封装时必须把 uni.hideLoading() 放在 complete 里，且只在此处调用一次。
如何支持按接口控制 loading 开关（非全量强制）
不是所有请求都该弹 loading：轮询心跳、静默上传头像、埋点上报、下拉刷新的“无感加载”都不应干扰用户。硬编码 uni.showLoading 会导致体验断裂。
推荐在请求函数参数中加 loading 字段，默认 true，业务层可显式传 false 关闭：
export function request(params) {
const showLoading = params.loading !== false
if (showLoading) {
uni.showLoading({ title: params.loadingText || '加载中' })
}
return new Promise((resolve, reject) => {
uni.request({
url: params.url,
method: params.method || 'GET',
data: params.data,
timeout: params.timeout || 8000,
complete() {
if (showLoading) uni.hideLoading()
}
})
})
}
-
params.loadingText允许不同接口显示不同文案（如“提交中…”“删除中…”） - 避免用全局变量（如
isLoading）判断状态——并发请求下会被覆盖 - 不要在
finally块里 hide，那是 Promise 层逻辑，和 uni API 生命周期无关
小程序端特别注意的三个坑
H5 和 App 端的问题在小程序上会放大，尤其以下三点极易被忽略：
-
uni.showLoading在某些低版本微信基础库（如 2.25.0 以下）中，若页面有cover-view或自定义导航栏，可能被遮挡——检查是否设置了过高的z-index或position: fixed元素 - 使用
uni.navigateTo跳转新页前若刚触发请求，而新页面也立即发请求，旧页的complete仍会执行uni.hideLoading，但此时 loading 已属新页上下文 → 导致新页 loading 闪一下就消失。解决办法：在complete中加简单防抖，比如记录当前页面getCurrentPages().pop().route，匹配再 hide - 如果项目用了 uView 或 uni-ui 的
u-loading组件做自定义 loading，务必确保组件v-if绑定的是 Vuex / Pinia 中的单一状态，且请求完成时清空该状态——不能靠组件内部计时器自动关闭，否则和真实请求生命周期脱钩
最易被绕开的复杂点是：loading 状态必须与「当前活跃页面」强绑定，而不是与「请求发起时刻」绑定。页面切换、tabBar 切换、navigateBack 都可能让 loading 上下文错位，complete 里的 hide 动作得先确认自己还是“合法主人”。
