UniApp开发实战：5分钟搞定H5跨域代理配置（附manifest.json示例）
UniApp开发实战：5分钟搞定H5跨域代理配置（附manifest.json示例）
当你第一次在UniApp项目中遇到H5跨域问题时，是否也经历过这样的场景？本地开发环境下，前端页面运行在http://localhost:8080，而后端API服务部署在http://localhost:3000。明明接口在Postman测试正常，但在浏览器中却始终报错：
Access to XMLHttpRequest at 'http://localhost:3000/api/login' from origin 'http://localhost:8080' has been blocked by CORS policy这种跨域问题困扰着无数UniApp开发者。本文将带你用最短时间掌握H5跨域代理的核心配置技巧，通过manifest.json的实战示例，让你在5分钟内彻底解决这个开发拦路虎。
1. 为什么H5开发必须处理跨域问题
浏览器安全策略中的同源限制（Same-Origin Policy）要求前端页面只能与同协议、同域名、同端口的后端服务通信。在开发环境中，这种限制尤为明显：
典型场景：
- 前端开发服务器：
http://localhost:8080 - 后端API服务：
http://localhost:3000或内网地址http://192.168.1.100:3000
- 前端开发服务器：
直接访问的三大障碍：
- 浏览器会拦截跨域请求
- 无法携带身份验证Cookies
- 某些HTTP方法（如PUT/DELETE）需要预检请求
提示：App和小程序环境不存在跨域限制，这是H5开发特有的问题
2. manifest.json代理配置全解析
UniApp基于Vue CLI构建，其代理配置与传统Web项目一脉相承。以下是完整的manifest.json配置示例：
{ "h5": { "devServer": { "proxy": { "/api": { "target": "http://localhost:3000", "changeOrigin": true, "secure": false, "pathRewrite": { "^/api": "" } }, "/static": { "target": "http://cdn.yourdomain.com", "changeOrigin": true } } } } }关键参数说明：
| 参数 | 类型 | 说明 | 必填 |
|---|---|---|---|
| target | string | 实际后端服务地址 | 是 |
| changeOrigin | boolean | 修改请求头中的Host值 | 推荐true |
| secure | boolean | 验证SSL证书（开发环境建议false） | 可选 |
| pathRewrite | object | 路径重写规则 | 按需 |
3. 多环境代理配置实战
实际项目中，我们需要区分开发、测试、生产环境。推荐以下配置方案：
3.1 基础配置分离
创建config/proxy.config.js文件：
module.exports = { dev: { '/api': { target: 'http://localhost:3000', pathRewrite: { '^/api': '/dev-api' } } }, test: { '/api': { target: 'http://test-api.yourcompany.com', pathRewrite: { '^/api': '/test-api' } } } }3.2 动态加载配置
修改manifest.json引入动态配置：
{ "h5": { "devServer": { "proxy": "require('./config/proxy.config.js').dev" } } }3.3 环境变量联动
结合process.env.NODE_ENV自动切换配置：
// vue.config.js const proxyConfig = require('./config/proxy.config') module.exports = { devServer: { proxy: proxyConfig[process.env.API_ENV || 'dev'] } }4. 常见问题排查指南
当代理配置不生效时，按以下步骤检查：
验证配置加载
# 查看最终webpack配置 npx vue-cli-service inspect --mode development检查请求路径
- 确保前端请求的是代理路径（如
/api/user） - 浏览器Network面板查看请求URL
- 确保前端请求的是代理路径（如
代理规则匹配
- 路径前缀必须完全匹配
- 复杂路径使用
context配置：proxy: [{ context: ['/auth', '/api'], target: 'http://localhost:3000' }]
服务重启
- 修改proxy配置后必须重启devServer
5. 高级配置技巧
5.1 多后端服务代理
{ "proxy": { "/user-api": { "target": "http://user-service:3001", "pathRewrite": { "^/user-api": "" } }, "/order-api": { "target": "http://order-service:3002", "pathRewrite": { "^/order-api": "" } } } }5.2 WebSocket代理支持
{ "/socket.io": { "target": "ws://localhost:3000", "ws": true, "changeOrigin": true } }5.3 自定义代理中间件
在vue.config.js中扩展：
module.exports = { devServer: { before(app) { app.use('/special', (req, res) => { res.json({ custom: 'response' }) }) } } }6. 生产环境部署须知
虽然开发环境代理解决了跨域问题，但生产环境需要不同的方案：
Nginx反向代理（推荐）
location /api/ { proxy_pass http://backend-service:3000/; proxy_set_header Host $host; }后端开启CORS
// Express示例 app.use((req, res, next) => { res.header('Access-Control-Allow-Origin', 'https://yourdomain.com') res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE') next() })云服务商解决方案
- AWS API Gateway
- Azure API Management
- 阿里云API网关
7. 最佳实践总结
路径规范
- 所有API请求添加统一前缀（如
/api） - 不同服务使用不同前缀（如
/api-auth、/api-order）
- 所有API请求添加统一前缀（如
环境隔离
- 开发环境：本地代理
- 测试环境：独立域名+代理
- 生产环境：Nginx反向代理
安全建议
- 开发环境关闭
secure验证 - 生产环境严格限制
Access-Control-Allow-Origin - 敏感接口添加CSRF防护
- 开发环境关闭
调试技巧
// 在代理配置中添加日志 onProxyReq: (proxyReq, req, res) => { console.log(`[PROXY] ${req.method} ${req.path} -> ${proxyReq.path}`) }
通过本文的manifest.json配置方案，我们项目中的跨域问题解决时间从原来的平均2小时/人降低到5分钟/人。特别是在对接第三方API时，团队成员不再需要反复查阅文档，直接复用现有配置模板即可快速打通接口。