uni-app H5 跨域代理配置前言如果你正在用 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 已配置

❌ 问题4：Invalid 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 代理正是我们解决它的有力工具。