UniApp H5开发实战：proxy代理配置详解与跨域问题一站式解决

1. 为什么H5开发总会遇到跨域问题？

第一次用UniApp开发H5页面时，我对着浏览器控制台鲜红的跨域报错一脸懵。明明在小程序端运行正常的接口请求，到了H5就突然罢工。后来才发现这是浏览器特有的安全机制在作祟——就像小区门禁系统，不允许你拿着A栋的门禁卡刷开B栋的大门。

跨域的本质是浏览器对JavaScript的安全限制，当协议（http/https）、域名或端口任一不同时就会触发。比如你的前端页面在http://localhost:8080，而接口在https://api.example.com，这就构成了典型的跨域场景。有趣的是，这种限制只存在于浏览器环境，这也是为什么同样的代码在App和小程序端能正常运行。

在实际项目中，我遇到过最棘手的两种情况：一是调试时本地开发服务器访问测试环境接口，二是生产环境前端部署在CDN而接口在独立域名。有次紧急上线时，后端同学突然说服务器暂时无法配置CORS，当时急得我差点把咖啡洒在键盘上——幸好proxy代理救场。

2. manifest.json配置代理的完整指南

2.1 基础配置三步走

打开项目根目录的manifest.json文件，切换到"源码视图"，找到或添加h5节点。这是我常用的配置模板：

"h5": {
  "devServer": {
    "https": false,
    "port": 8080,
    "disableHostCheck": true,
    "proxy": {
      "/api": {
        "target": "https://your-api-domain.com",
        "changeOrigin": true,
        "secure": false,
        "pathRewrite": {
          "^/api": "/v1"
        }
      }
    }
  }
}

几个关键参数值得注意：

• disableHostCheck：关闭主机检查，解决Invalid Host header报错
• changeOrigin：修改请求头中的Origin为目标地址，这个不开启可能导致某些服务器拒绝请求
• pathRewrite：我习惯用它将通用前缀/api映射到具体的接口版本/v1

2.2 多环境智能配置技巧

实际开发中我们需要区分测试/生产环境。我的方案是通过环境变量动态配置：

"proxy": {
  "/api": {
    "target": process.env.API_BASE || "https://default-api.com",
    "pathRewrite": {
      "^/api": process.env.API_PREFIX || ""
    }
  }
}