UniApp H5 代理失效的终极替代方案

放弃 manifest.json，用 vite.config.js 配置（推荐，100% 生效）

在 UniApp（Vue3）H5 端配置代理不生效是高频问题，核心原因是 UniApp 对 H5 端 devServer 代理的解析规则、配置格式与纯 Vue CLI/Vite 项目存在差异，且容易忽略多环境、路径匹配、编译模式等细节。以下是针对性的排查和修复方案：

一、先确认核心前提（90% 问题出在这里）

UniApp 的 H5 端代理仅在 H5 开发模式（npm run dev:h5） 下生效，且需满足：

配置文件是 manifest.json（根目录），且修改后必须重启 H5 开发服务 （停止 dev:h5 后重新启动）；
前端请求必须是相对路径 （不能写 http://localhost:8080/dev-api/xxx 这类绝对路径，需直接写 /dev-api/xxx）；
仅 H5 端生效，小程序 / APP 端不支持 devServer 代理（需用真机调试或配置跨域白名单）。

二、修正 manifest.json 代理配置格式（关键）

UniApp 对 h5.devServer.proxy 的配置格式有严格要求，你的配置看似正确，但需确认以下细节：

正确的 manifest.json 配置示例（JSON 格式严格）

ruby 复制代码

{
  "vueVersion": "3",
  "h5": {
    "devServer": {
      "proxy": {
        "/dev-api": {
          "target": "http://192.168.31.24:9999",
          "changeOrigin": true,
          "pathRewrite": {
            "^/dev-api": ""
          },
          // 新增：UniApp 部分版本需显式开启 secure（非 HTTPS 目标设为 false）
          "secure": false,
          // 可选：开启日志，排查代理是否命中
          "logLevel": "debug"
        }
      },
      "https": false,
      // 可选：指定 H5 开发服务端口，避免端口冲突
      "port": 8080
    }
  }
}

三、代理不生效的高频排查点（逐一验证）

1. 检查请求路径是否为相对路径（最常见）

错误示例（绝对路径，不走代理）：

csharp 复制代码

// ❌ 绝对路径会绕过代理，直接请求 localhost:8080
axios.get('http://localhost:8080/dev-api/user/info')

正确示例（相对路径，触发代理）：

csharp 复制代码

// ✅ 相对路径，会被代理转发到 192.168.31.24:9999/user/info
axios.get('/dev-api/user/info')

// 或配置 axios baseURL（推荐）
const request = axios.create({
  baseURL: '/dev-api', // 开发环境
  timeout: 5000
})
request.get('/user/info')

2. 确认 UniApp 编译模式（Vue3 需匹配 Vite 规则）

UniApp Vue3 版本默认使用 Vite 编译，而 Vite 的代理配置中，pathRewrite 需替换为 rewrite（部分 UniApp 版本未兼容旧字段）。

修改为 Vite 兼容的代理配置：

json 复制代码

{
  "h5": {
    "devServer": {
      "proxy": {
        "/dev-api": {
          "target": "http://192.168.31.24:9999",
          "changeOrigin": true,
          // Vite 中用 rewrite 替代 pathRewrite（UniApp Vue3 需此写法）
          "rewrite": "(path) => path.replace(/^/dev-api/, '')"
        }
      }
    }
  }
}

3. 检查后端是否限制跨域（代理生效但后端拦截）

即使代理配置正确，若后端未配置跨域允许，仍会报错：

后端需添加跨域响应头（以 SpringBoot 为例）：

typescript 复制代码

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:8080") // H5 开发地址
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

若后端用 Nginx 代理，需添加：

arduino 复制代码

add_header Access-Control-Allow-Origin http://localhost:8080;
add_header Access-Control-Allow-Credentials true;

4. 排查 UniApp 版本兼容问题

部分 UniApp 版本（如 3.0.0~3.2.0）存在 H5 代理解析 Bug，可：

升级 UniApp 核心版本：

sql 复制代码

npm update @dcloudio/uni-app @dcloudio/uni-cli-shared

或降级到稳定版本（如 3.4.0+）：
css 复制代码
```
npm install @dcloudio/uni-app@3.4.0
```

5. 验证代理是否命中（开启日志）

在 devServer 中添加 logLevel: "debug"，重启 H5 服务后，查看终端日志：

若日志中出现 [proxy] proxying request /dev-api/user/info to http://192.168.31.24:9999，说明代理已命中；
若无此日志，说明路径匹配失败（检查请求路径是否以 /dev-api 开头）。

四、UniApp H5 代理失效的终极替代方案

若以上配置仍不生效，可绕过 manifest.json，直接修改 Vite 配置（UniApp Vue3 基于 Vite 编译）：

在项目根目录创建 vite.config.js（UniApp 会自动识别）；
写入 Vite 原生代理配置：

javascript 复制代码

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';

export default defineConfig({
  plugins: [uni()],
  server: {
    // 直接配置 Vite 代理（优先级高于 manifest.json）
    proxy: {
      '/dev-api': {
        target: 'http://192.168.31.24:9999',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^/dev-api/, ''),
        logLevel: 'debug'
      }
    },
    // 确保端口与 manifest.json 一致
    port: 8080,
    https: false
  }
});

重启 npm run dev:h5，此方案优先级高于 manifest.json 中的 h5.devServer，几乎 100% 生效。

五、小程序 / APP 端的替代方案（重要）

UniApp 的 devServer 代理仅对 H5 端生效，小程序 / APP 端无法使用：

小程序端：需在微信开发者工具中配置 "不校验合法域名"（仅调试），或在微信公众平台添加后端域名白名单；
APP 端：无需跨域（APP 无同源策略），直接请求后端真实地址 http://192.168.31.24:9999/xxx 即可。

总结

UniApp H5 端代理不生效的核心修复步骤：

确保请求为相对路径 （/dev-api/xxx）；
重启 H5 开发服务（修改配置后必须重启）；
优先使用 vite.config.js 配置 Vite 原生代理（替代 manifest.json）；
验证后端跨域配置，避免代理生效但后端拦截。

按以上步骤配置后，请求 /dev-api/user/info 会被正确代理到 http://192.168.31.24:9999/user/info（移除 /dev-api 前缀）。

放弃 manifest.json，用 vite.config.js 配置（推荐，100% 生效）

UniApp Vue3 底层基于 Vite 编译，直接在 vite.config.js 中写 Vite 原生代理配置（支持 JS 函数），优先级高于 manifest.json，且不会有格式兼容问题：

1. 根目录创建 / 修改 vite.config.js

javascript 复制代码

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';

export default defineConfig({
  plugins: [uni()],
  server: {
    // H5 开发服务器代理配置（Vite 原生语法，支持函数）
    proxy: {
      '/dev-api': {
        target: 'http://192.168.31.24:9999',
        changeOrigin: true,
        // Vite 原生 rewrite 配置（函数形式，正确写法）
        rewrite: (path) => path.replace(/^/dev-api/, ''), 
        secure: false, // 非 HTTPS 目标需设为 false
        logLevel: 'debug' // 开启日志，便于排查
      }
    },
    port: 8080, // 与 manifest.json 保持一致（可选）
    https: false
  }
});

2. 清理 manifest.json 中的无效代理配置

将 manifest.json 中 h5.devServer.proxy 部分删除（避免冲突），保留必要配置即可：

json 复制代码

{
  "vueVersion": "3",
  "h5": {
    "devServer": {
      "https": false,
      "port": 8080 // 仅保留端口/HTTPS 配置，代理交给 vite.config.js
    }
  }
}

3. 重启 H5 开发服务

停止当前 npm run dev:h5，重新执行命令，代理即可生效。

方案二：强制适配 manifest.json（仅 JSON 格式，兼容旧版本）

如果必须在 manifest.json 中配置，需避开 JS 函数，改用 UniApp 兼容的 字符串替换规则 （部分 UniApp 版本支持 pathRewrite 字符串格式）：

json 复制代码

{
  "vueVersion": "3",
  "h5": {
    "devServer": {
      "proxy": {
        "/dev-api": {
          "target": "http://192.168.31.24:9999",
          "changeOrigin": true,
          // 改用 pathRewrite（JSON 字符串格式，UniApp 可解析）
          "pathRewrite": {
            "^/dev-api": ""
          },
          "secure": false
        }
      },
      "https": false
    }
  }
}

关键说明：

manifest.json 是纯 JSON 文件，只能写键值对 / 字符串 / 数字 / 布尔值 ，不能写函数、正则表达式（/^/dev-api/ 这种正则在 JSON 中会被解析为字符串，部分版本 UniApp 能兼容）；
此方案仅适配 UniApp 对 pathRewrite 的兼容解析，若仍报错，优先用方案一（vite.config.js）。

报错原因补充

你之前写的 "rewrite": "(path) => path.replace(/^/dev-api/, '')" 存在两个问题：

JSON 中无法解析箭头函数，最终 rewrite 是字符串类型，而非函数，导致 UniApp/Vite 执行 opts.rewrite(path) 时报错；
正则表达式写法错误：/^/dev-api/ 应为 /^/dev-api/（JSON 中需转义反斜杠，或在 JS 中直接写）。

验证是否生效

重启 npm run dev:h5 后，前端发送请求：

csharp 复制代码

// 示例：用 axios 发送请求
axios.get('/dev-api/user/info')

查看终端日志（开启 logLevel: 'debug' 后），若出现：

bash 复制代码

[proxy] proxying request /dev-api/user/info to http://192.168.31.24:9999/user/info

说明代理已成功移除 /dev-api 前缀，配置生效。

最终建议

UniApp Vue3 项目优先使用 vite.config.js 配置代理：

兼容 Vite 原生语法，支持函数 / 正则，无格式限制；
避开 manifest.json 的 JSON 格式约束；
配置逻辑与纯 Vite 项目一致，维护成本更低。