企业官网建设流程全解析

前言

如果你正在用 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 跨域的常见解决方案

解决跨域主要有以下几种思路：

四、避坑指南：常见问题与排查

❌ 问题1：配置了代理但完全不生效

排查步骤：

1. 检查配置位置：确认proxy是否在"h5" → "devServer"层级下

2. 检查请求路径：前端请求是否以/api开头（相对路径）

3. 重启开发服务：修改配置文件后必须重启H5 开发服务

4. 检查配置冲突：是否同时存在manifest.json和vue.config.js的代理配置

5. 尝试重启编辑器：尤其是 HBuilderX，有时需要重启才能生效

❌ 问题2：请求发出去但返回 404

原因：pathRewrite配置有误。

• 检查目标接口是否真的需要去掉/api前缀

• 确认pathRewrite的正则表达式是否写成了字符串形式

❌ 问题3：请求被后端拒绝（403 等）

原因：changeOrigin未设为true。

• 确认changeOrigin: true已配置

• 如果后端是 HTTPS，确认secure: false已配置

❌ 问题4：Invalid Host header 报错

原因：disableHostCheck未配置或为false。

• 将disableHostCheck设为true

五、总结

配置好代理之后，你的 Uni-App H5 开发体验将会顺畅很多。记住：跨域不是框架的 Bug，而是 Web 开发的通用问题，而 devServer 代理正是我们解决它的有力工具。