uniapp网络请求封装库安装配置与使用教程

在UniApp开发中，直接使用原生 uni.request 往往会导致代码冗余、错误处理分散以及难以统一管理Token等公共参数。引入成熟的网络请求封装库，如 luch-request，可以将请求逻辑标准化，实现全局拦截、自动重试和类型提示支持。这种做法不仅让业务代码更清爽，还能在接口变更时只需修改一处配置即可全局生效。

UniApp项目中网络请求封装的整体架构示意

网络请求封装的核心在于“拦截器”机制，它允许你在请求发送前和响应返回后插入自定义逻辑，比如添加认证Header或解析通用错误码。开始前，请确保你已创建一个基础的UniApp项目，并安装了Node.js环境以便使用npm或yarn管理依赖。

1. 安装依赖库

打开项目根目录下的终端窗口，执行安装命令。这里以社区广泛使用的 luch-request 为例，它专为UniApp设计，支持Promise和拦截器。

npm install luch-request

如果你使用的是yarn，则运行 yarn add luch-request。安装完成后，检查 package.json 文件，确认依赖列表中已出现该库及其版本号，这表示安装成功。

2. 创建请求实例文件

在项目根目录或 utils 文件夹下新建一个JS文件，例如 request.js。首先引入库并创建实例。这一步决定了后续所有请求的基础配置，如 baseURL 和超时时间。

在utils目录下创建request.js并设置baseURL

import Request from 'luch-request'

const http = new Request()

// 设置默认配置
http.setConfig((config) => {
  config.baseURL = 'https://api.example.com' // 你的接口域名
  config.timeout = 10000 // 超时时间，单位毫秒
  return config
})

export default http

注意 baseURL 应替换为你实际的后端接口地址。保存文件后，这个 http 对象就具备了发送请求的基本能力，且所有通过它发出的请求都会自动拼接上基础域名。

3. 配置请求拦截器

拦截器是封装库的灵魂。在 request.js 中继续编写代码，添加请求拦截器用于在发送前处理数据，最常见的是添加 Token。

编写请求拦截器自动注入Authorization Header

// 请求拦截器
http.interceptors.request.use((config) => {
  // 从本地存储获取token
  const token = uni.getStorageSync('token')
  if (token) {
    config.header['Authorization'] = 'Bearer ' + token
  }
  // 必须返回config，否则请求不会发送
  return config
}, (error) => {
  return Promise.reject(error)
})

这段代码会在每次请求发出前检查本地是否有 Token，如果有则自动写入 Header。观察控制台或网络面板，你会发现后续请求头中多出了 Authorization 字段，无需在每个页面手动添加。

4. 配置响应拦截器

响应拦截器用于统一处理后端返回的数据结构，比如判断状态码是否为200，或者处理特定的业务错误码。

// 响应拦截器
http.interceptors.response.use((response) => {
  // 根据后端约定，假设 code 为 200 表示成功
  if (response.data.code === 200) {
    return response.data.data
  } else {
    // 统一处理业务错误，如弹出提示
    uni.showToast({
      title: response.data.msg || '请求失败',
      icon: 'none'
    })
    return Promise.reject(response.data)
  }
}, (error) => {
  // 处理网络错误或HTTP错误
  uni.showToast({
    title: '网络连接异常',
    icon: 'none'
  })
  return Promise.reject(error)
})

通过这一步，业务层接收到的直接是有效数据部分，不再需要层层解包 res.data.data，同时也统一了错误提示的交互体验。

4. 配置响应拦截器

5. 在页面中发起请求

配置完成后，在具体的 .vue 页面中引入刚才创建的 http 实例，并使用它发起GET或POST请求。

import http from '@/utils/request.js'

export default {
  onLoad() {
    this.fetchData()
  },
  methods: {
    async fetchData() {
      try {
        // 发起GET请求
        const res = await http.get('/user/info')
        console.log('用户信息:', res)
        
        // 发起POST请求
        // const postRes = await http.post('/login', { username: 'admin', password: '123456' })
      } catch (error) {
        console.error('请求出错:', error)
      }
    }
  }
}

运行项目并在浏览器或真机调试器中查看控制台，如果配置正确，你应该能看到打印出的用户数据对象，且网络面板中的请求URL已自动补全了 baseURL。

6. 验证与维护

最后，尝试修改 baseURL 或移除本地 Token，观察拦截器是否按预期工作。例如，清除 Token 后再次请求，应看到请求头中不再包含 Authorization 字段；若后端返回错误码，页面应自动弹出统一的 Toast 提示。

控制台验证数据输出与网络请求详情

这种封装方式使得网络层与业务层彻底解耦。未来若需切换接口域名或调整鉴权方式，只需修改 request.js 中的配置，无需遍历所有页面文件。保留好这个工具文件，它将成为你UniApp项目中稳定的基础设施。