uniapp网络请求拦截怎么设置及配置方法

在 uni-app 开发中，为原生网络请求设置拦截主要有两种途径：一是使用官方提供的原生拦截器接口 uni.addInterceptor 针对 uni.request 进行全局钩子挂载；二是编写独立的工具函数，使用 Promise 对 uni.request 进行统一封装并在函数体内流转请求与响应。两者的核心目标都是在请求发出前自动拼装服务器根路径、附加身份凭证（如 Token），并在服务器响应后统一处理登录失效、状态码错误与网络异常。

方法一：基于 uni.addInterceptor 原生拦截器配置

uni-app 官方运行时提供了 uni.addInterceptor(apiName, options) 方法，其原理是通过劫持全局的指定 API（如 request 或 uploadFile）来执行前置与后置拦截。这种方式最大的特点是对已有代码无侵入性，无论业务组件中写的是直接调用的 uni.request 还是第三方库，只要底层触及该 API，拦截均会生效。

1. 编写拦截器模块

在项目源码目录下新建拦截配置文件，例如 utils/interceptor.js。在该文件中配置 invoke、success、fail 三个钩子函数：

// utils/interceptor.js
const BASE_URL = 'https://api.example.com';

export function setupRequestInterceptor() {
  uni.addInterceptor('request', {
    // 1. 发起请求前触发：在此处处理 URL、设置 Header 与 Token
    invoke(args) {
      // 拼接基础地址：非完整 http 链接时自动加上 BASE_URL
      if (!/^https?:\/\//i.test(args.url)) {
        const cleanBase = BASE_URL.replace(/\/+$/, '');
        const cleanPath = args.url.replace(/^\/+/, '');
        args.url = `${cleanBase}/${cleanPath}`;
      }

      // 设置默认超时时间
      args.timeout = args.timeout || 15000;

      // 读取本地缓存中的 Token 并附带在请求头中
      const token = uni.getStorageSync('ACCESS_TOKEN');
      args.header = {
        'Content-Type': 'application/json',
        ...args.header,
      };

      if (token) {
        args.header['Authorization'] = `Bearer ${token}`;
      }
    },

    // 2. 接口调用成功回调截获
    success(response) {
      // HTTP 状态码为 200，但业务状态码可能是约定错误
      const statusCode = response.statusCode;
      if (statusCode === 200) {
        const resData = response.data;
        // 假设服务端业务状态码 401 代表凭证失效
        if (resData && resData.code === 401) {
          uni.removeStorageSync('ACCESS_TOKEN');
          uni.showToast({ title: '登录已过期，请重新登录', icon: 'none' });
          uni.reLaunch({ url: '/pages/login/login' });
        }
      } else if (statusCode === 401) {
        // HTTP 原生 401 拦截
        uni.removeStorageSync('ACCESS_TOKEN');
        uni.showToast({ title: '无权访问，请先登录', icon: 'none' });
        uni.reLaunch({ url: '/pages/login/login' });
      } else {
        uni.showToast({
          title: response.data?.message || `网络异常 (${statusCode})`,
          icon: 'none'
        });
      }
    },

    // 3. 网络故障或请求被终止
    fail(err) {
      uni.showToast({
        title: '网络连接失败，请检查网络设置',
        icon: 'none'
      });
    }
  });
}

2. 在 main.js 中执行注册

拦截器必须在所有页面与网络请求执行前完成初始化。最合适的执行节点是应用入口文件 main.js（或 Vue 3 项目的 main.ts）：

// main.js (Vue 2 示例)
import Vue from 'vue';
import App from './App';
import { setupRequestInterceptor } from './utils/interceptor';

// 执行拦截器注册
setupRequestInterceptor();

Vue.config.productionTip = false;
App.mpType = 'app';
const app = new Vue({ ...App });
app.$mount();

若为 Vue 3 项目：

// main.ts (Vue 3 示例)
import { createSSRApp } from 'vue';
import App from './App.vue';
import { setupRequestInterceptor } from './utils/interceptor';

export function createApp() {
  const app = createSSRApp(App);
  setupRequestInterceptor();
  return { app };
}

方法二：基于 Promise 的自主封装拦截配置（更精准的控制流）

许多团队在实践中发现，uni.addInterceptor 存在一个局限：它的 success 钩子虽然能监测到服务端返回，但无法直接篡改返回给业务页面的 Promise 状态。即使服务端业务状态码为错误，业务页面的 await uni.request() 依然会被当成成功执行，导致每个业务函数还得自行做一层判断。

为了获得类似 Web 端 Axios 的控制力度（即直接返回纯业务数据，出错直接抛出异常进入 catch），更通用的方案是封装一个统一的 request.js 实例。

封装核心文件 request.js

// utils/request.js
const BASE_URL = 'https://api.example.com';

function request(options = {}) {
  return new Promise((resolve, reject) => {
    // 1. 请求前拦截配置
    let url = options.url || '';
    if (!/^https?:\/\//i.test(url)) {
      url = BASE_URL.replace(/\/+$/, '') + '/' + url.replace(/^\/+/, '');
    }

    const token = uni.getStorageSync('ACCESS_TOKEN');
    const header = {
      'Content-Type': 'application/json',
      ...options.header
    };
    if (token) {
      header['Authorization'] = `Bearer ${token}`;
    }

    // 2. 发起原生网络调用
    uni.request({
      url,
      method: (options.method || 'GET').toUpperCase(),
      data: options.data || {},
      header: header,
      timeout: options.timeout || 15000,
      success: (res) => {
        const { statusCode, data } = res;
        
        // 3. 响应拦截：HTTP 层面判断
        if (statusCode >= 200 && statusCode < 300) {
          // 业务数据解包判断
          if (data && data.code === 0) {
            // 业务成功：直接剥离外壳，返回核心 data
            resolve(data.data);
          } else if (data && data.code === 401) {
            // 登录态失效
            uni.removeStorageSync('ACCESS_TOKEN');
            uni.showToast({ title: '登录失效，请重新登录', icon: 'none' });
            uni.reLaunch({ url: '/pages/login/login' });
            reject(data);
          } else {
            // 其他业务报错提示
            uni.showToast({ title: data.msg || '业务请求失败', icon: 'none' });
            reject(data);
          }
        } else {
          // 4xx, 5xx 状态码统一报错
          uni.showToast({ title: `服务器响应异常: ${statusCode}`, icon: 'none' });
          reject(res);
        }
      },
      fail: (err) => {
        // 断网或超时拦截
        uni.showToast({ title: '网络连接超时，请重试', icon: 'none' });
        reject(err);
      }
    });
  });
}

// 便捷方法封装
request.get = (url, data, header) => request({ url, method: 'GET', data, header });
request.post = (url, data, header) => request({ url, method: 'POST', data, header });

export default request;

在业务页面中使用封装后的请求

// pages/index/index.vue
import request from '@/utils/request';

async function fetchUserProfile() {
  try {
    // 已经过拦截器处理，直接拿到真实数据载荷
    const userInfo = await request.get('/user/profile');
    console.log('获取用户信息成功', userInfo);
  } catch (error) {
    // 业务错误或网络错误均在此集中捕获
    console.warn('请求已中断或失败', error);
  }
}

常见认知辨析与容易混淆的说法

观点一：“设置了拦截器，小程序和 H5 端就能统一解决跨域问题。”
辨析：这种说法在小程序端看似成立，但在 H5 端是错误的。小程序平台不存在浏览器的同源策略，由微信或支付宝客户端沙箱直接发起网络请求；而 H5 端受浏览器安全策略限制，即使你在请求拦截器中添加了任何 Header，只要后端未配置 CORS 响应头，浏览器控制台依然会拦截请求。在 H5 本地开发调试时，仍须在 manifest.json 中配置 h5.devServer.proxy 进行正向代理。

观点二：“uni.addInterceptor 的 success 钩子返回 false 就能取消向后传递。”
辨析：在 invoke 阶段返回 false 确实能够阻止该请求的发出；但在 success 和 fail 钩子中，返回 false 只是忽略当前后置处理，并不能阻止外部调用方的 Promise 结算。调用方依然会收到原始响应。若需强行更改调用链的结果，应当使用上述方法二的 Promise 自主封装体系。

多环境与多端运行的注意要点

• 动态环境配置：在实际开发中，BASE_URL 应当区分开发环境与生产环境。可以通过 process.env.NODE_ENV 进行分支判断：开发环境指向内网联调地址，生产环境指向线上真实服务器。
• 白名单放行机制：部分请求（如登录、注册、短信验证码获取）并不需要携带 Token，拦截器内应维护一个白名单数组，避免不必要地读取本地缓存，并在未登录时避免无谓的报错触发。
• 重复提示防抖：当一个页面同时并发发起 3 个请求且 Token 均失效时，后置拦截器可能会连续弹出 3 次“登录已过期”并触发 3 次页面重定向。建议在拦截模块内设置一个标志位（如 isRefreshing 或 isRedirecting），在触发一次跳转后锁定，防止界面连续闪烁。

配置验证与结果自查清单

完成上述配置后，可以通过以下几个具体测试用例来验证请求拦截是否生效：

1. 路径与参数验证：在页面中调用形如 /api/test 的相对路径，打开控制台 Network 面板，确认最终发送的网络请求是否自动补全为了完整的域名地址。
2. Token 自动化验证：在本地缓存中存入模拟 Token（uni.setStorageSync('ACCESS_TOKEN', 'test_token')），发起任意请求，查看 Request Headers 中是否存在 Authorization: Bearer test_token。
3. 状态码与过期处理：故意调用一个返回 401 状态的接口，验证控制台或界面是否执行了本地 Token 清除，并成功自动重定向到登录页面。