uni-app H5跨域代理配置与多端请求处理实践

1. 问题背景与排查思路

最近在开发一个基于uni-app的多端项目时，遇到了一个典型问题：H5环境下接口调用返回404错误，而同样的接口在APP和小程序环境下却能正常访问。这种情况在多端开发中其实很常见，主要原因是不同运行环境对网络请求的处理机制存在差异。

首先需要明确的是，uni-app虽然提供了跨平台开发能力，但各平台的实际运行环境差异很大：

• APP端：运行在原生容器中，可以直接访问任何网络地址
• 小程序端：受限于小程序的安全策略，需要配置合法域名
• H5端：运行在浏览器环境中，受同源策略限制

当遇到H5接口404问题时，建议按照以下步骤排查：

1. 确认接口本身是否可用：使用Postman等工具直接调用接口，排除后端服务问题
2. 检查跨域问题：浏览器控制台查看是否有CORS相关错误
3. 验证代理配置：确认manifest.json中的代理设置是否正确
4. 检查请求地址拼接：确保条件编译代码正确区分了不同环境

提示：H5环境下的404错误90%以上都是由于代理配置不正确或请求地址拼接错误导致的，建议优先检查这两点。

2. H5代理配置详解

2.1 代理配置原理

在开发环境下，H5页面运行在本地服务器（通常是localhost），而接口服务通常部署在其他域名下。浏览器出于安全考虑，会阻止这种跨域请求。解决这个问题的常用方法就是配置开发服务器代理。

uni-app的H5开发服务器基于webpack-dev-server，可以在manifest.json中配置代理规则。其工作原理是：

1. 浏览器发送请求到本地开发服务器（如：/aps/api/store.getPage）
2. 开发服务器根据代理规则，将请求转发到目标服务器（如：https://xxx.com/api/store.getPage）
3. 目标服务器返回响应，开发服务器再将响应返回给浏览器

这样，浏览器始终只与本地服务器通信，避免了跨域问题。

2.2 完整代理配置示例

在manifest.json的源码视图中，找到h5配置项，添加devServer和proxy配置：

json复制"h5": {
    "devServer": {
        "port": 80,
        "https": true,
        "disableHostCheck": true,
        "proxy": {
            "/aps": {
                "target": "https://xxx-xxx.com/",
                "changeOrigin": true,
                "secure": false,
                "pathRewrite": {
                    "^/aps": "/"
                }
            }
        }
    },
    "router": {
        "base": "/h5/",
        "mode": "hash"
    }
}

关键参数说明：

• port：开发服务器端口，默认8080，可自定义
• https：是否启用HTTPS，根据后端接口协议决定
• disableHostCheck：禁用主机检查，解决Invalid Host header问题
• proxy：代理规则配置
  • /aps：匹配请求路径的前缀
  • target：目标服务器地址
  • changeOrigin：修改请求头中的host为目标地址
  • secure：是否验证SSL证书
  • pathRewrite：路径重写规则

2.3 代理配置常见问题

1. 路径匹配问题：

   • 确保代理前缀（如/aps）与请求地址中的前缀一致
   • 路径区分大小写，建议统一使用小写

2. 修改配置不生效：

   • 每次修改manifest.json后，需要关闭当前H5运行窗口并重新运行
   • 检查HBuilderX控制台启动日志，确认代理配置已加载

3. HTTPS证书问题：

   • 如果接口服务使用自签名证书，需要设置secure: false
   • 正式环境建议使用合法证书

3. 多环境请求处理方案

3.1 条件编译实现

uni-app提供了条件编译能力，可以根据不同平台编写特定代码。对于接口请求，通常需要区分H5和非H5环境：

javascript复制let requestUrl = '';
// #ifdef H5
requestUrl = `/aps/api/store.${url}`;
// #endif

// #ifdef APP-PLUS || MP-WEIXIN
requestUrl = `${CONFIG.HOST2}/api/store.${url}`;
// #endif

uni.request({
    url: requestUrl,
    // 其他配置...
});

3.2 请求封装最佳实践

建议对uni.request进行统一封装，处理各平台的差异：

javascript复制// utils/request.js
const request = (options) => {
    // 处理不同环境的URL
    let url = options.url;
    
    // #ifdef H5
    if (!url.startsWith('/aps') && !url.startsWith('http')) {
        url = `/aps${url.startsWith('/') ? '' : '/'}${url}`;
    }
    // #endif
    
    // #ifndef H5
    if (!url.startsWith('http')) {
        url = `${CONFIG.BASE_URL}${url.startsWith('/') ? '' : '/'}${url}`;
    }
    // #endif
    
    return new Promise((resolve, reject) => {
        uni.request({
            ...options,
            url,
            success: (res) => {
                // 统一处理响应
                if (res.statusCode === 200) {
                    resolve(res.data);
                } else {
                    reject(res);
                }
            },
            fail: (err) => {
                reject(err);
            }
        });
    });
};

export default request;

3.3 路径设计技巧

1. 代理前缀选择：

   • 避免使用常见的路径如/api、/v1等作为代理前缀
   • 建议使用项目特定的前缀，如/aps、/myproject等
   • 确保前缀不会与实际接口路径冲突

2. 路径重写策略：

   • 简单场景：^/aps:/ 直接去掉前缀
   • 复杂场景：可以保留部分路径，如^/aps/api:/api

3. 多代理配置：
   如果需要代理多个服务，可以配置多个规则：

json复制"proxy": {
    "/api1": {
        "target": "https://service1.com",
        "pathRewrite": {"^/api1": ""}
    },
    "/api2": {
        "target": "https://service2.com",
        "pathRewrite": {"^/api2": ""}
    }
}

4. 常见问题与解决方案

4.1 接口404问题排查流程

1. 确认接口本身可用：

   • 使用Postman直接调用接口地址
   • 检查返回状态码和数据

2. 检查浏览器控制台：

   • 查看Network面板，确认请求是否发出
   • 检查请求URL是否正确
   • 查看响应状态码和内容

3. 验证代理是否生效：

   • 在浏览器中直接访问代理地址（如/aps/api/test）
   • 检查是否被正确代理到目标地址

4. 检查请求地址拼接：

   • 确认条件编译代码正确执行
   • 打印最终请求URL，确认符合预期

4.2 典型错误与修复

1. 代理配置修改不生效：

   • 问题原因：HBuilderX开发服务器缓存
   • 解决方案：关闭H5运行窗口，重新运行

2. Invalid Host header错误：

   • 问题原因：开发服务器主机检查
   • 解决方案：设置disableHostCheck: true

3. CORS跨域错误：

   • 问题原因：代理配置不正确
   • 解决方案：检查代理规则，确保请求被正确转发

4. HTTPS证书错误：

   • 问题原因：自签名证书不被信任
   • 解决方案：设置secure: false（仅限开发环境）

4.3 生产环境注意事项

1. 区分开发和生产配置：

   • 开发环境使用代理解决跨域
   • 生产环境应确保前端和后端同源，或配置CORS

2. API地址管理：

   • 使用环境变量管理不同环境的API地址
   • 避免在代码中硬编码地址

3. 代理前缀处理：

   • 生产环境构建时，可以通过环境变量动态设置代理前缀
   • 或者使用相对路径，由Web服务器配置重写规则

5. 高级配置与优化

5.1 多环境配置管理

建议使用.env文件管理不同环境的配置：

code复制// .env.development
VUE_APP_BASE_URL=/aps
VUE_APP_API_HOST=https://dev.example.com

// .env.production
VUE_APP_BASE_URL=/api
VUE_APP_API_HOST=https://api.example.com

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

javascript复制const baseUrl = process.env.VUE_APP_BASE_URL;

"h5": {
    "devServer": {
        "proxy": {
            [baseUrl]: {
                "target": process.env.VUE_APP_API_HOST,
                "pathRewrite": {
                    [`^${baseUrl}`]: "/"
                }
            }
        }
    }
}

5.2 自定义开发服务器配置

如果需要更复杂的代理配置，可以创建vue.config.js：

javascript复制module.exports = {
    devServer: {
        proxy: {
            '/aps': {
                target: 'https://xxx.com',
                ws: true,
                changeOrigin: true,
                pathRewrite: {
                    '^/aps': '/'
                }
            }
        }
    }
};

5.3 性能优化建议

1. 减少代理层级：

   • 尽量将多个接口服务聚合到同一域名下
   • 减少代理规则数量

2. 启用压缩：

   • 配置开发服务器启用响应压缩
   • 减小传输数据量

3. 合理设置超时：

   • 根据接口响应时间，设置适当的代理超时时间
   • 避免长时间等待

在实际项目中，我通常会创建一个proxy-config.js文件集中管理所有代理规则，然后在vue.config.js中引入。这种方式便于维护和团队协作，特别是在大型项目中效果显著。另外，建议在项目文档中详细记录代理配置规则，方便新成员快速上手。