Vue3 + axios 前后端联调实战：封装、跨域与报错处理

在 Vue3 项目开发中前后端联调是核心环节之一而 axios 作为最主流的 HTTP 客户端库承担着前端与后端数据交互的重任。很多新手在使用 axios 时会遇到三个高频痛点每个请求都重复写基础配置如 baseURL、请求头代码冗余本地开发时浏览器跨域报错无法访问后端接口接口报错、网络异常、登录失效时没有统一的处理逻辑用户体验差。一、环境准备首先确保你的项目是Vue3 Vite版本Vue3 CLI 项目仅跨域配置略有差异核心逻辑通用。1.1 安装 axios打开项目终端执行安装命令三选一即可npminstallaxios# 或 yarn add axios# 或 pnpm add axios二、核心axios 全局封装重点封装的核心目标统一配置、统一拦截、统一处理避免重复代码提升维护性后续所有接口都复用该封装实例。2.1 创建封装文件在项目src目录下新建utils文件夹再创建request.js文件固定路径src/utils/request.js专门用于封装 axios。2.2 完整封装代码可直接复制使用代码带详细注释关键步骤标注新手可快速理解// 1. 引入 axios核心依赖importaxiosfromaxios// 可选引入 Element Plus 消息提示项目常用无侵权可替换为其他UI库import{ElMessage}fromelement-plus// 2. 创建 axios 实例核心步骤constserviceaxios.create({// 基础路径后续请求会自动拼接在前面用环境变量配置灵活切换环境baseURL:import.meta.env.VITE_API_URL,// 请求超时时间10秒避免请求一直挂起timeout:10000,// 默认请求头适配 JSON 格式接口无需手动添加headers:{Content-Type:application/json;charsetUTF-8}})// 3. 请求拦截器发送请求前统一处理比如携带Tokenservice.interceptors.request.use((config){// 场景1自动携带 Token登录后存储在 localStorage按需修改存储方式consttokenlocalStorage.getItem(token)if(token){// 格式需和后端一致一般是 Bearer 空格 Tokenconfig.headers.AuthorizationBearer${token}}// 场景2可在这里添加请求加载动画比如 Element Plus 的 ElLoading// ElLoading.service({ text: 加载中... })returnconfig},(error){// 请求发送失败处理比如网络中断、请求参数错误console.error(请求拦截错误,error)returnPromise.reject(error)})// 4. 响应拦截器接口返回数据后统一处理报错、数据过滤service.interceptors.response.use((response){// 直接返回后端数据简化取值无需每次都写 response.data// 可根据后端返回格式调整比如后端统一返回 { code: 200, data: {}, msg: }可在这里判断 code// if (response.data.code ! 200) { ElMessage.error(response.data.msg); return Promise.reject() }returnresponse.data},(error){// 统一报错处理根据 HTTP 状态码判断异常类型重点const{response}errorif(response){// 有响应接口返回错误HTTP状态码非200switch(response.status){// 401未授权/登录失效最常见场景case401:ElMessage.error(登录已失效请重新登录)// 清空本地存储Token、用户信息等localStorage.clear()// 路由跳转至登录页需先引入路由实例路径按需修改// import router from ../router// router.push(/login)break// 403无权限比如普通用户访问管理员接口case403:ElMessage.error(没有权限访问该接口)break// 404接口不存在路径写错、后端接口未部署case404:ElMessage.error(请求接口不存在请检查接口路径)break// 500服务器错误后端代码报错、服务器宕机case500:ElMessage.error(服务器异常请稍后重试)break// 其他错误比如 400 参数错误default:ElMessage.error(response.data?.msg||请求失败请稍后再试)}}else{// 无响应网络异常、服务器未启动、跨域配置错误ElMessage.error(网络异常请检查网络连接或服务器状态)}// 抛出错误便于页面中额外处理可选returnPromise.reject(error)})// 5. 导出 axios 实例供其他文件引入使用exportdefaultservice2.3 封装核心说明必看baseURL使用 Vite 环境变量配置区分开发/生产环境无需手动修改代码请求拦截器自动携带 Token无需每个请求手动添加还可添加加载动画响应拦截器统一处理 HTTP 状态码报错无需每个接口单独写 try/catch错误提示集成 Element Plus 消息提示若未使用 Element Plus可替换为原生 alert。三、接口统一管理推荐不建议在页面中直接写接口地址和请求逻辑单独管理接口便于后续维护比如接口路径修改只需改一处。3.1 创建接口文件在src目录下新建api文件夹按业务模块划分接口文件比如用户相关、商品相关这里以用户接口为例创建user.js路径src/api/user.js。3.2 接口代码示例可直接复制// 引入封装好的 axios 实例路径按需调整importrequestfrom../utils/request// 1. 登录接口POST 请求参数为 JSON 格式exportfunctionlogin(data){returnrequest({url:/user/login,// 接口路径会拼接 baseURLmethod:post,// 请求方式data// 请求参数POST 用 dataGET 用 params})}// 2. 获取用户信息GET 请求参数为 URL 拼接exportfunctiongetUserInfo(params){returnrequest({url:/user/info,method:get,params// 比如 { id: 123 }会自动拼接为 /user/info?id123})}// 3. 上传文件接口POST FormData 格式特殊场景exportfunctionuploadFile(formData){returnrequest({url:/file/upload,method:post,// 上传文件需手动设置 Content-Type覆盖默认的 JSON 格式headers:{Content-Type:multipart/form-data},data:formData// FormData 实例比如 new FormData()})}四、页面中使用接口实战演示在 Vue3 组件Setup 语法中直接引入接口函数调用简洁高效结合 async/await 处理异步请求。template div classlogin-page button clickhandleLogin classlogin-btn登录/button /div /template script setup // 1. 引入需要的接口函数路径按需调整 import { login, getUserInfo } from ../api/user // 可选引入 Element Plus 消息提示优化用户体验 import { ElMessage } from element-plus // 2. 登录按钮点击事件异步函数 const handleLogin async () { try { // 调用登录接口传递参数和后端接口参数一致 const res await login({ username: admin, password: 123456 }) console.log(登录成功, res) // 登录成功后存储 Token 到 localStorage localStorage.setItem(token, res.token) // 调用获取用户信息接口登录后才能访问需携带 Token const userInfo await getUserInfo() console.log(用户信息, userInfo) // 登录成功提示 ElMessage.success(登录成功) } catch (error) { // 拦截器已统一报错这里可处理额外逻辑比如关闭加载动画 console.log(请求失败, error) } } /script style scoped .login-btn { padding: 8px 16px; cursor: pointer; } /style五、解决前端跨域问题高频痛点5.1 什么是跨域浏览器同源策略限制协议、域名、端口任意一个不同就会触发跨域导致接口请求失败控制台报错Access to XMLHttpRequest at … from origin … has been blocked by CORS policy。示例前端http://localhost:3000访问后端http://localhost:8080端口不同触发跨域。5.2 Vite 项目配置跨域开发环境重点开发环境下通过 Vite 代理解决跨域修改项目根目录的vite.config.js文件添加 proxy 配置import{defineConfig}fromviteimportvuefromvitejs/plugin-vue// https://vitejs.dev/config/exportdefaultdefineConfig({plugins:[vue()],// Vite 基础插件Vue3 必选// 跨域代理配置核心server:{port:3000,// 前端启动端口可自行修改proxy:{// 匹配以 /api 开头的所有请求和环境变量 VITE_API_URL 对应/api:{target:http://localhost:8080,// 后端真实接口地址替换为你的后端地址changeOrigin:true,// 允许跨域关键配置rewrite:(path)path.replace(/^\/api/,)// 路径重写去掉 /api 前缀按需调整}}}})5.3 环境变量配置推荐灵活切换环境在项目根目录新建 2 个环境变量文件区分开发/生产环境无需手动修改代码。新建.env.development开发环境本地开发用# 开发环境接口基础路径和 vite.config.js 中的 proxy 匹配 VITE_API_URL /api新建.env.production生产环境上线部署用# 生产环境真实接口地址替换为你的线上接口地址 VITE_API_URL http://api.xxx.com说明开发环境走代理/api 代理到后端地址生产环境直接访问真实接口无需修改封装代码。5.4 Vue CLI 项目跨域配置补充如果你的项目是 Vue3 CLI 搭建的不是 Vite修改项目根目录的vue.config.js文件module.exports{devServer:{proxy:{/api:{target:http://localhost:8080,// 后端真实接口地址changeOrigin:true,// 允许跨域pathRewrite:{^/api:}// 路径重写按需调整}}}}六、完整报错处理方案封装后的 axios 已经实现了统一报错覆盖所有常见异常场景无需在每个页面单独处理错误大幅减少代码冗余网络异常无响应服务器未启动、网络中断提示「网络异常请检查网络或服务器状态」登录失效401自动清空 Token提示「登录已失效请重新登录」并跳转到登录页无权限403提示「没有权限访问该接口」接口不存在404提示「请求接口不存在请检查接口路径」服务器错误500提示「服务器异常请稍后重试」其他业务报错直接显示后端返回的错误信息response.data.msg。七、注意事项避坑指南Token 存储示例用 localStorage若项目需要更安全的存储方式可替换为 pinia/vuex 状态管理刷新页面不丢失路由跳转401 跳转登录页时需先引入路由实例import router from ‘…/router’否则会报错跨域仅开发环境有效生产环境跨域需后端配置 CORS设置 Access-Control-Allow-Origin前端代理配置不生效Content-Type 注意上传文件需手动设置multipart/form-data普通 JSON 接口无需修改环境变量命名Vite 环境变量必须以VITE_开头否则无法读取比如 VITE_API_URL不能写成 API_URL代码复用所有接口都复用封装的 request 实例不要直接使用 axios 发起请求否则无法触发拦截器。八、总结本文完整实现了 Vue3 axios 前后端联调的核心实战内容覆盖新手必学的三个核心知识点axios 封装统一配置、拦截器、报错处理减少重复代码提升项目维护性接口管理模块化管理接口按业务划分后续修改接口路径更便捷跨域解决适配 Vite/Vue CLI 项目一键配置代理解决本地开发跨域痛点报错处理覆盖所有常见异常场景统一提示优化用户体验。