UniApp H5开发实战：跨域代理配置全解析（manifest.json与vue.config.js双方案）

1. UniApp H5开发中的跨域问题解析

第一次用UniApp开发H5页面时，我兴冲冲地写好了接口请求代码，结果浏览器控制台突然跳出一行刺眼的红色报错："Access-Control-Allow-Origin"。这个场景相信很多开发者都遇到过，特别是在前后端分离的开发模式下，跨域问题就像一道必须跨过的门槛。

跨域问题本质上是一个安全机制。浏览器出于安全考虑，会阻止不同源（协议、域名、端口任一不同）的请求响应。举个例子，如果你的H5页面运行在http://localhost:8080，而接口服务部署在http://api.example.com，这就构成了跨域。

在UniApp的H5开发中，这个问题尤为突出。因为开发阶段我们通常用本地服务器调试，而接口可能部署在测试环境或生产环境。这时候就需要代理配置来绕过浏览器的同源策略限制。代理的工作原理很简单：让同域的服务器帮你转发请求到目标服务器，这样浏览器就不会拦截了。

2. manifest.json配置方案详解

2.1 配置步骤

manifest.json是UniApp项目的核心配置文件，它提供了H5开发服务器的代理配置选项。我推荐先在HBuilderX中打开manifest.json文件，切换到"源码视图"模式，这样可以直接编辑JSON内容。

找到或添加h5配置项，在其中加入devServer配置。这里有个小技巧：如果你不确定配置位置，可以直接在JSON顶层添加"h5"字段。完整的配置示例如下：

json复制"h5": {
  "devServer": {
    "disableHostCheck": true,
    "proxy": {
      "/api": {
        "target": "http://your-api-domain.com",
        "changeOrigin": true,
        "secure": false,
        "ws": false,
        "pathRewrite": {
          "^/api": ""
        }
      }
    }
  }
}

2.2 参数解析

每个配置参数都有其特定作用：

• disableHostCheck：关闭主机检查，避免开发时出现Invalid Host header错误
• proxy：定义代理规则，可以配置多个不同路径的代理
• target：目标服务器地址，填写你的后端API地址
• changeOrigin：修改请求头中的origin为目标地址，这对某些服务端校验很重要
• secure：如果是https接口需要验证证书可以设为true
• pathRewrite：路径重写规则，可以去掉接口前缀

我在实际项目中发现，当接口返回404时，很可能是pathRewrite配置有问题。这时候可以先用简单的配置测试，确认代理生效后再调整重写规则。

3. vue.config.js配置方案详解

3.1 创建与配置

虽然manifest.json方案很方便，但在某些场景下，我们可能更习惯使用vue.config.js的方式。这个文件需要手动创建在项目根目录（与src同级），UniApp会自动识别它。

创建vue.config.js后，加入以下配置：

javascript复制module.exports = {
  devServer: {
    disableHostCheck: true,
    proxy: {
      '/api': {
        target: 'http://your-api-domain.com',
        changeOrigin: true,
        secure: false,
        ws: false,
        pathRewrite: {
          '^/api': ''
        }
      }
    }
  }
}

3.2 与manifest.json的差异

两种配置方式看起来很相似，但有几个关键区别：

1. 优先级：manifest.json的配置会覆盖vue.config.js
2. 灵活性：vue.config.js支持更多webpack配置选项
3. 适用场景：如果是纯UniApp项目，推荐使用manifest.json；如果需要复杂webpack配置，可以选择vue.config.js

我遇到过一个典型场景：项目需要同时配置代理和自定义webpack loader。这时候就必须使用vue.config.js，因为manifest.json不支持loader配置。

4. 两种方案的对比与选择

4.1 性能对比

在实际项目中，我分别测试了两种配置方式的性能差异。结果发现，在代理转发效率上几乎没有区别，因为底层都是基于webpack-dev-server实现的。主要的区别在于：

• 启动时间：manifest.json方式略快，因为少解析一个配置文件
• 内存占用：两者基本相当
• 热更新：vue.config.js方式对热更新更友好

4.2 适用场景建议

根据我的经验，给出以下选择建议：

1. 简单项目：直接使用manifest.json配置，减少文件数量
2. 复杂项目：使用vue.config.js，便于扩展其他webpack配置
3. 团队协作：如果团队熟悉Vue生态，选择vue.config.js更易维护
4. 多环境配置：vue.config.js更容易实现环境变量区分

有个常见的误区是同时使用两种配置，这可能导致代理规则混乱。我建议始终只选择一种方式，并在团队内统一规范。

5. 请求封装的最佳实践

5.1 基础封装方案

配置好代理后，我们需要一个健壮的请求封装。这是我的常用方案：

javascript复制// request.js
const BaseHost = process.env.NODE_ENV === 'development' ? '/api' : 'http://prod-api.com'

export default function request(options) {
  return new Promise((resolve, reject) => {
    uni.request({
      url: BaseHost + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'Content-Type': 'application/json',
        'X-Token': uni.getStorageSync('token'),
        ...options.headers
      },
      success: (res) => {
        if (res.statusCode === 200) {
          resolve(res.data)
        } else {
          reject(res)
        }
      },
      fail: (err) => {
        reject(err)
      }
    })
  })
}

5.2 高级技巧

在实际项目中，我还加入了以下增强功能：

1. 请求拦截：统一添加认证token
2. 响应拦截：统一处理错误码
3. 重试机制：对特定错误自动重试
4. 缓存策略：对GET请求合理缓存
5. 取消请求：页面卸载时取消pending请求

这些优化使请求层更加健壮，特别是在弱网环境下表现更好。一个典型的错误处理增强版如下：

javascript复制function withRetry(fn, retries = 3) {
  return async function(...args) {
    let lastError
    for (let i = 0; i < retries; i++) {
      try {
        return await fn(...args)
      } catch (error) {
        lastError = error
        if (error.statusCode === 502) {
          await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
          continue
        }
        throw error
      }
    }
    throw lastError
  }
}

6. 常见问题排查指南

6.1 配置不生效

这是最常见的问题，我总结了一套排查流程：

1. 检查配置文件位置是否正确
2. 确认修改后重新运行了项目
3. 查看控制台网络请求，确认代理路径匹配
4. 尝试最简单的配置排除其他干扰
5. 重启IDE和开发服务器

6.2 接口404问题

当代理配置正确但接口返回404时：

1. 检查目标地址是否可达
2. 确认pathRewrite规则是否正确
3. 测试直接访问目标接口
4. 检查后端路由是否存在

6.3 跨域依然存在

如果配置后还是出现跨域错误：

1. 确认changeOrigin设置为true
2. 检查响应头是否包含Access-Control-Allow-Origin
3. 如果是复杂请求，需要处理OPTIONS预检请求

7. 项目实战经验分享

在最近的一个电商项目中，我遇到了一个典型的代理配置挑战。项目需要同时对接三个不同的后端服务：用户服务、商品服务和订单服务。每个服务的API前缀和地址都不同。

最终的解决方案是在vue.config.js中配置多个代理规则：

javascript复制module.exports = {
  devServer: {
    proxy: {
      '/user-api': {
        target: 'http://user-service.com',
        pathRewrite: { '^/user-api': '' }
      },
      '/product-api': {
        target: 'http://product-service.com',
        pathRewrite: { '^/product-api': '' }
      },
      '/order-api': {
        target: 'http://order-service.com',
        pathRewrite: { '^/order-api': '' }
      }
    }
  }
}

对应的请求封装也需要适配多前缀：

javascript复制const SERVICE_PREFIX = {
  user: '/user-api',
  product: '/product-api',
  order: '/order-api'
}

function getApiUrl(service, path) {
  return process.env.NODE_ENV === 'development' 
    ? `${SERVICE_PREFIX[service]}${path}`
    : `${SERVICE_HOST[service]}${path}`
}

这个方案完美解决了多服务对接的问题，而且保持了开发和生产环境的一致性。上线后运行稳定，证明了代理配置方案的可靠性。