uniapp开发实战：5分钟搞定H5跨域代理配置（附完整代码）

Uniapp H5开发实战跨域问题一站式解决方案与高效请求封装跨域问题一直是前端开发中的常见痛点尤其在Uniapp开发H5应用时本地调试阶段频繁遇到接口请求被浏览器拦截的情况。本文将带你深入理解Uniapp中的跨域本质并提供三种不同场景下的解决方案最后还会分享一个经过实战检验的请求封装方案让你的开发效率提升200%。1. 理解Uniapp H5开发中的跨域本质跨域问题本质上是一个浏览器安全策略而非技术限制。当你的Uniapp项目在H5环境下运行时如果前端页面地址与后端接口地址的协议、域名或端口任一不同浏览器就会触发同源策略拦截请求。在本地开发环境中这种情况尤为常见你的Uniapp项目可能运行在http://localhost:8080而后端API可能部署在http://api.yourdomain.com或http://192.168.1.100:3000三种典型跨域场景对比场景类型本地开发环境测试环境生产环境出现概率100%50%0%解决方案devServer代理Nginx反向代理同域部署或CORS配置复杂度中等较高无提示生产环境通常不会出现跨域问题因为前后端通常会部署在同一域名下或通过CORS策略解决。2. 三管齐下Uniapp跨域解决方案全攻略2.1 方案一使用内置浏览器绕过跨域这是最简单的解决方案但仅限于开发阶段// manifest.json 配置 { h5: { devServer: { open: true, // 自动打开内置浏览器 port: 8080 } } }优点零配置开箱即用适合快速验证接口缺点仅限开发环境使用无法测试真实浏览器行为2.2 方案二devServer代理配置推荐这是最常用的开发阶段解决方案通过webpack-dev-server的proxy功能实现// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://your-api-domain.com, changeOrigin: true, pathRewrite: { ^/api: // 移除/api前缀 } } } } }关键参数解析参数类型说明targetstring代理目标地址changeOriginboolean是否修改请求头中的originpathRewriteobjectURL路径重写规则secureboolean是否验证SSL证书注意修改vue.config.js后需要重启开发服务器才能生效。2.3 方案三生产环境解决方案对于生产环境推荐以下两种方式Nginx反向代理配置示例server { listen 80; server_name yourdomain.com; location /api/ { proxy_pass http://api-server:3000/; proxy_set_header Host $host; } }后端启用CORS以Node.js为例// Express中间件 app.use((req, res, next) { res.header(Access-Control-Allow-Origin, *); res.header(Access-Control-Allow-Methods, GET,POST,PUT,DELETE); res.header(Access-Control-Allow-Headers, Content-Type,Authorization); next(); });3. 高阶实战Uniapp请求封装最佳实践一个健壮的请求封装应该包含以下功能统一错误处理请求/响应拦截Token自动管理超时处理请求取消完整封装方案// utils/request.js import store from /store import { getToken } from /utils/auth const BASE_URL process.env.VUE_APP_API_BASE_URL const TIMEOUT 15000 const http (method, url, data, config {}) { const header { Content-Type: application/json, ...config.headers } // 自动添加Token if (getToken() !config.skipAuth) { header[Authorization] Bearer ${getToken()} } return new Promise((resolve, reject) { uni.request({ url: ${BASE_URL}${url}, method, data, header, timeout: TIMEOUT, success: (res) { if (res.statusCode 200 res.statusCode 300) { resolve(res.data) } else { handleError(res, reject) } }, fail: (err) { handleNetworkError(err, reject) } }) }) } function handleError(response, reject) { const { statusCode, data } response let message 请求异常 switch (statusCode) { case 401: message 登录已过期 store.dispatch(user/logout) break case 403: message 没有权限 break case 500: message data.message || 服务器错误 break default: message 未知错误: ${statusCode} } uni.showToast({ title: message, icon: none }) reject({ code: statusCode, message, response }) } function handleNetworkError(error, reject) { let message 网络异常 if (error.errMsg.includes(timeout)) { message 请求超时 } uni.showToast({ title: message, icon: none }) reject({ code: -1, message, error }) } // 封装常用方法 export const get (url, params, config) http(GET, url, params, config) export const post (url, data, config) http(POST, url, data, config) export const put (url, data, config) http(PUT, url, data, config) export const del (url, data, config) http(DELETE, url, data, config) export default { get, post, put, delete: del }使用示例import { get, post } from /utils/request // 获取用户列表 const fetchUsers async () { try { const res await get(/users) console.log(用户数据:, res) } catch (error) { console.error(获取用户失败:, error) } } // 提交表单 const submitForm async (formData) { try { const res await post(/submit, formData) uni.showToast({ title: 提交成功 }) return res } catch (error) { console.error(提交失败:, error) throw error } }4. 性能优化与调试技巧4.1 代理配置优化对于大型项目可能需要代理多个API服务// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://api.main.com, ws: true, changeOrigin: true }, /auth: { target: http://auth.server.com, changeOrigin: true, pathRewrite: { ^/auth: } }, /uploads: { target: http://static.cdn.com, changeOrigin: false // 某些CDN不需要修改origin } } } }4.2 请求性能监控在请求封装中添加性能统计const http (method, url, data, config {}) { const startTime Date.now() return new Promise((resolve, reject) { uni.request({ // ...其他配置 complete: () { const duration Date.now() - startTime console.log([${method}] ${url} 耗时: ${duration}ms) // 可以上报到监控系统 if (duration 3000) { reportSlowRequest({ url, method, duration }) } } }) }) }4.3 常见问题排查指南问题1代理配置不生效检查vue.config.js位置是否正确项目根目录确认修改后重启了开发服务器检查代理规则是否匹配请求路径问题2生产环境跨域确保前后端域名一致检查Nginx/Apache配置是否正确确认后端已正确配置CORS问题3请求封装报错检查BASE_URL是否正确确认uni.request的返回结构处理正确验证错误处理逻辑是否覆盖所有场景在实际项目中我通常会创建一个api目录来组织所有接口请求结合本文的请求封装方案可以极大提升开发效率和代码可维护性。例如src/ api/ user.js # 用户相关接口 product.js # 产品相关接口 order.js # 订单相关接口 utils/ request.js # 请求封装