1. 为什么需要代理配置和跨域解决方案

如果你正在使用UniApp开发H5应用，一定会遇到这样一个头疼的问题：本地开发时，前端页面运行在localhost:8080，而后端API接口可能部署在其他域名下。这时候浏览器就会无情地抛出一个跨域错误，让你的请求无法正常发出。

跨域问题其实是浏览器的一种安全机制，专业术语叫"同源策略"。简单来说，就是浏览器不允许一个域下的脚本去请求另一个域下的资源，除非这两个域完全相同（协议、域名、端口都一致）。这就像是你去银行取钱，银行只认你本人带着身份证来办理业务，其他人代劳是不行的。

在实际开发中，我们最常用的解决方案就是配置代理服务器。它的工作原理就像是一个中间人：前端还是向自己的域名发送请求，代理服务器在背后悄悄地把请求转发到真正的API服务器，再把响应返回给前端。这样浏览器就不会发现你在"跨域"了。

2. manifest.json代理配置详解

2.1 基础配置步骤

让我们从最基础的配置开始。在UniApp项目中，manifest.json文件是整个应用的配置文件，我们可以在其中配置H5开发服务器的代理设置。

首先打开你的项目，找到manifest.json文件。在HBuilderX中，你可以直接双击打开它，然后切换到"源码视图"。找到"h5"节点，如果没有就手动添加一个：

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

这个配置的意思是：所有以/api开头的请求，都会被代理到http://your-api-domain.com这个目标地址。pathRewrite则用来重写路径，把/api前缀去掉。

2.2 配置参数详解

让我们仔细看看这些配置参数都是什么意思：

• target：这是最重要的参数，指定你要代理到的目标服务器地址。可以是IP也可以是域名。
• changeOrigin：这个参数很关键，设置为true时，会修改请求头中的host为目标地址的host。建议始终设置为true。
• secure：如果是https接口，需要设置为true；如果是http接口，可以设置为false。
• pathRewrite：路径重写规则，可以用正则表达式来修改请求路径。

我遇到过不少开发者反映代理不生效，90%的情况都是因为changeOrigin没设置或者设置错了。这个参数直接影响请求头中的host值，很多后端服务会根据host来做校验。

2.3 多环境代理配置

在实际项目中，我们通常会有多个环境：开发环境、测试环境、生产环境等。这时候可以这样配置：

"h5": {
  "devServer": {
    "proxy": {
      "/dev-api": {
        "target": "http://dev.your-api.com",
        "pathRewrite": {"^/dev-api": ""}
      },
      "/test-api": {
        "target": "http://test.your-api.com",
        "pathRewrite": {"^/test-api": ""}
      },
      "/prod-api": {
        "target": "http://prod.your-api.com",
        "pathRewrite": {"^/prod-api": ""}
      }
    }
  }
}

然后在代码中根据环境变量来决定使用哪个前缀：

const baseUrl = process.env.NODE_ENV === 'development' ? '/dev-api' : 
               process.env.NODE_ENV === 'test' ? '/test-api' : '/prod-api';

3. 常见问题与解决方案

3.1 代理配置不生效

这是最常见的问题，我总结了几种可能的原因和解决方案：

1. 没有重启开发服务器：修改manifest.json后，必须重启开发服务器才能生效。在HBuilderX中，点击"运行"->"终止运行"，然后重新运行项目。

2. 路径匹配问题：确保你请求的URL路径和proxy中配置的路径前缀完全匹配。比如配置的是"/api"，但请求的是"/v1/api"，这样是不会被代理的。

3. 浏览器缓存：有时候浏览器会缓存之前的请求，导致看起来代理没生效。可以尝试清除缓存或者使用无痕窗口。

4. 配置位置错误：确保proxy配置是在"h5"->"devServer"节点下，而不是其他位置。

3.2 接口返回404

如果代理后接口返回404，可以按照以下步骤排查：

1. 检查target地址是否正确，可以直接在浏览器中访问这个地址看看是否能正常响应。

2. 检查pathRewrite配置是否正确。有时候路径重写会把必要的路径部分也去掉了。

3. 如果后端接口有上下文路径（比如/api/v1），确保在pathRewrite中保留这部分。

3.3 跨域问题依然存在

有时候即使配置了代理，还是会遇到跨域问题，可能是因为：

1. 后端服务没有正确处理OPTIONS预检请求。跨域请求中，浏览器会先发送一个OPTIONS请求来检查是否允许跨域。

2. 后端返回的响应头中没有包含必要的CORS头信息（如Access-Control-Allow-Origin）。

这种情况下，除了前端代理配置外，还需要后端配合设置正确的响应头。

4. 高级配置技巧

4.1 WebSocket代理配置

如果你的应用使用了WebSocket，也可以配置代理：

"h5": {
  "devServer": {
    "proxy": {
      "/socket": {
        "target": "ws://your-websocket-server.com",
        "ws": true,
        "changeOrigin": true
      }
    }
  }
}

注意要设置"ws": true来启用WebSocket代理。

4.2 自定义请求头

有时候我们需要在代理请求中添加自定义请求头：

"h5": {
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://your-api.com",
        "headers": {
          "X-Custom-Header": "value",
          "Authorization": "Bearer token"
        }
      }
    }
  }
}

4.3 绕过代理的特定请求

如果你有一些请求不想走代理，可以配置bypass：

"h5": {
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://your-api.com",
        "bypass": function(req) {
          if (req.url.includes('/no-proxy')) {
            return req.url;
          }
        }
      }
    }
  }
}

5. 实际项目中的最佳实践

经过多个UniApp项目的实践，我总结出以下几点经验：

1. 统一API前缀管理：建议在项目中创建一个api.js文件，统一管理所有API的前缀和路径。这样当代理配置需要修改时，只需要改这一个地方。

2. 环境变量区分配置：使用process.env.NODE_ENV来区分开发、测试和生产环境，自动切换不同的代理配置。

3. 封装请求方法：对uni.request进行二次封装，统一处理请求前缀、错误处理等逻辑。

4. 文档记录：在团队协作中，一定要把代理配置的规则和使用方法记录下来，避免其他成员踩坑。

5. 定期检查配置：随着项目迭代，API路径可能会变化，要定期检查代理配置是否仍然适用。

记住，代理配置只是开发阶段的解决方案，生产环境中的跨域问题需要通过后端配置CORS或者Nginx反向代理来解决。