UniApp H5开发实战：巧用devServer proxy配置，一站式解决uni.request跨域难题

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

第一次用uni.request请求后端接口时，看到控制台报错"Access-Control-Allow-Origin"的时候，我整个人都是懵的。明明Postman能正常调用的接口，为什么在H5页面就报错？后来才明白这是浏览器的同源策略在作祟。

现代前端开发基本都是前后端分离架构，前端跑在localhost:3000，后端API在api.yourdomain.com。浏览器出于安全考虑，默认禁止这种跨域请求。而在UniApp打包成App或小程序时，其实没有这个限制，问题就出在H5环境——它本质上就是个网页。

我见过不少新手开发者的"野路子"解决方案：有的让后端直接关闭CORS校验（安全隐患极大），有的改用JSONP（现在很多API已不支持），还有的甚至要求用户手动关闭浏览器安全设置（简直离谱）。其实在开发阶段，最简单的方案就是配置devServer的proxy。

2. 三分钟搞定proxy基础配置

打开你的manifest.json文件，找到（或新建）h5节点。这里有个坑要注意：一定要切换到"源码视图"才能修改，可视化编辑器是看不到完整配置项的。配置模板长这样：

json复制"h5": {
  "devServer": {
    "proxy": {
      "/api": {
        "target": "https://your-real-api.com",
        "changeOrigin": true,
        "secure": false
      }
    }
  }
}

我来拆解下这几个关键参数：

• /api：你的请求路径前缀，相当于一个标记
• target：实际的后端接口地址
• changeOrigin：改变请求头中的host值（对付某些后端校验必备）
• secure：关闭HTTPS证书验证（本地开发时常用）

配置完后，当你在代码里调用：

javascript复制uni.request({
  url: '/api/user/list'
})

实际发出的请求会自动变成https://your-real-api.com/api/user/list，完美绕过浏览器同源限制。不过这里有个常见坑点：修改manifest.json后必须重新运行项目才会生效，HBuilderX的热更新对配置文件无效。

3. 高级玩法：pathRewrite的妙用

很多老项目API设计不规范，路径里根本没有统一前缀。比如你可能遇到这种情况：

• 获取用户信息：/user/info
• 获取商品列表：/product/list

这时候就需要pathRewrite出场了。改造后的配置示例：

json复制"proxy": {
  "/proxy_api": {
    "target": "https://your-real-api.com",
    "pathRewrite": {
      "^/proxy_api": ""
    }
  }
}

这样配置后：

• 请求/proxy_api/user/info
• 实际变成https://your-real-api.com/user/info

pathRewrite的本质是正则替换，我常用这些骚操作：

1. 给所有接口加版本号："^/api/v1" : "/api"
2. 多环境切换："^/dev" : "/prod"
3. 接口路径重组："^/user/(.*)" : "/api/v2/user/$1"

4. 多环境配置与实战技巧

真实项目往往需要区分开发/测试/生产环境。我推荐这种目录结构：

code复制├── config
│   ├── dev.js
│   ├── test.js
│   └── prod.js
└── manifest.json

然后在manifest.json中动态引入配置：

javascript复制const config = require('./config/' + process.env.NODE_ENV)

"proxy": {
  "/api": {
    "target": config.apiBaseUrl
  }
}

开发中还会遇到这些典型问题：

1. Cookie携带问题：需要设置"cookieDomainRewrite": "localhost"
2. WebSocket代理：要单独配置ws: true
3. 自定义头信息：通过headers字段注入
4. HTTPS证书问题：配"secure: false"临时跳过验证

实测过程中我发现HBuilderX有个小坑：修改proxy配置后，有时需要完全退出重启才能生效。建议每次修改后：

1. 停止当前运行的项目
2. 清理HBuilderX缓存
3. 重新运行

5. 原理剖析：proxy是如何工作的

很多人以为proxy是uniapp的黑魔法，其实底层用的是webpack-dev-server的能力。当你在本地启动开发服务器时：

1. 浏览器发送请求到http://localhost:8080/api/data
2. 开发服务器拦截到/api开头的请求
3. 根据配置转发到真实API地址
4. 将响应结果返回给浏览器

整个过程浏览器始终只和本地服务器通信，根本不知道有跨域这回事。这也是为什么proxy方案仅适用于开发环境，生产环境要么需要后端配CORS，要么通过Nginx反向代理。

6. 常见报错与解决方案

问题1：配置了proxy但请求还是报跨域错误

• 检查是否重启了开发服务器
• 确认请求路径是否匹配proxy规则
• 试试在浏览器直接访问代理后的完整URL

问题2：POST请求变成OPTIONS

• 这是浏览器预检请求
• 确保后端正确处理了OPTIONS方法
• 检查请求头是否包含非常规字段

问题3：接口返回404但Postman能通

• 大概率是pathRewrite没生效
• 在控制台查看实际发出的请求URL
• 检查target地址末尾是否有误加的斜杠

问题4：HTTPS证书验证失败

• 临时方案：设置"secure: false"
• 长期方案：把证书放到devServer的https配置里

7. 生产环境部署方案

再次强调：devServer.proxy只是开发工具！线上环境需要这些方案：

方案A：Nginx反向代理

nginx复制location /api/ {
  proxy_pass https://your-api-server.com/;
  proxy_set_header Host $host;
}

方案B：后端开启CORS

java复制// Spring Boot示例
@Bean
public WebMvcConfigurer corsConfigurer() {
  return new WebMvcConfigurer() {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
      registry.addMapping("/api/**")
        .allowedOrigins("*");
    }
  };
}

方案C：云服务商API网关

• 阿里云API网关的"跨域插件"
• AWS API Gateway的CORS配置
• 腾讯云API网关的"基础跨域"功能

最近在做一个电商项目时，就遇到了第三方支付接口的跨域问题。由于对方服务器无法修改CORS配置，最终我们采用了Nginx中转方案，在测试环境用proxy，生产环境用Nginx，完美实现了开发和生产配置的无缝切换。