uni-app H5 跨域代理配置

前言如果你正在用 Uni-App 开发 H5 应用并且在本地调试时调用后端接口那么你大概率已经和“跨域”这个老朋友打过照面了。浏览器控制台那个刺眼的红色报错 ——Access-Control-Allow-Origin—— 相信让不少刚接触 H5 开发的开发者头疼不已。明明在小程序端和 App 端运行得好好的接口请求一到 H5 端就突然“罢工”了。这其实是运行环境的差异所致而非 Uni-App 框架本身的 Bug。本文将深入讲解 Uni-App H5 跨域问题的本质并围绕一段典型的代理配置代码手把手教你如何彻底解决这个问题。跨域是浏览器出于安全考虑而实施的同源策略。它规定只有当网页的协议http/https、域名、端口号三者完全一致时脚本才能正常访问另一个资源的接口。举个例子你的本地开发服务器跑在http://localhost:8080而后端 API 部署在http://api.example.com:3000这就构成了跨域。浏览器会阻止这种请求以防范恶意网站窃取用户数据。一、两种配置方式对比方式一manifest.json 配置推荐优点Uni-App 官方推荐的方式最“原生”配置简单无需额外创建文件缺点必须切换到源码视图操作灵活性不如 JavaScript 文件h5 : { devServer : { disableHostCheck : true, proxy : { /api : { target : http://www.demo.com, changeOrigin : true, secure : false, ws: false, pathRewrite : { ^/api : } } } } }方式二vue.config.js 配置在项目根目录创建vue.config.js文件module.exports { devServer: { disableHostCheck: true, proxy: { /api: { target: http://www.demo.com, changeOrigin: true, secure: false, ws: false, pathRewrite: { ^/api: } } } } }优点语法更灵活支持 JavaScript 逻辑与 Vue 项目配置方式一致缺点manifest.json的优先级高于vue.config.js两者同时存在且配置冲突时以manifest.json为准可能造成配置混乱二、请求代码示例配置好代理后前端代码中直接使用相对路径即可uni.request({ url: /api/mobile/user/userinfo, // 以 /api 开头触发代理 method: GET, data: {}, header: { X-Token: uni.getStorageSync(token) }, success: (res) { console.log(res) }, fail: (err) { console.log(err) } })封装建议可以通过条件编译区分 H5 和其他端的环境// #ifdef H5 const BaseHost /api // H5 端走代理 // #endif // #ifndef H5 const BaseHost http://www.demo.com // 其他端直接请求真实地址 // #endif三、补充3.1 跨域的常见解决方案解决跨域主要有以下几种思路方案适用场景优缺点CORS生产环境后端配置响应头最标准的方式JSONP仅限 GET 请求古老技巧局限性大已不推荐Nginx 反向代理生产部署服务端转发稳定可靠devServer 代理本地开发最方便、最主流、官方推荐四、避坑指南常见问题与排查❌ 问题1配置了代理但完全不生效排查步骤检查配置位置确认proxy是否在h5 → devServer层级下检查请求路径前端请求是否以/api开头相对路径重启开发服务修改配置文件后必须重启H5 开发服务检查配置冲突是否同时存在manifest.json和vue.config.js的代理配置尝试重启编辑器尤其是 HBuilderX有时需要重启才能生效❌ 问题2请求发出去但返回 404原因pathRewrite配置有误。检查目标接口是否真的需要去掉/api前缀确认pathRewrite的正则表达式是否写成了字符串形式❌ 问题3请求被后端拒绝403 等原因changeOrigin未设为true。确认changeOrigin: true已配置如果后端是 HTTPS确认secure: false已配置❌ 问题4Invalid Host header 报错原因disableHostCheck未配置或为false。将disableHostCheck设为true五、总结关键点说明跨域本质浏览器的同源策略限制仅存在于 H5 环境代理原理本地开发服务器代为请求浏览器感知不到跨域配置位置manifest.json源码视图 →h5.devServer.proxy核心参数target目标地址、changeOrigin必开、pathRewrite路径重写请求路径必须使用相对路径如/api/xxx匹配代理前缀配置后操作必须重启H5 开发服务生产环境代理仅开发环境有效生产需用 CORS 或 Nginx配置好代理之后你的 Uni-App H5 开发体验将会顺畅很多。记住跨域不是框架的 Bug而是 Web 开发的通用问题而 devServer 代理正是我们解决它的有力工具。