登录
UniApp H5 代理失效的终极替代方案
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 格式严格）
{
"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. 检查请求路径是否为相对路径（最常见）
错误示例（绝对路径，不走代理）：
// ❌ 绝对路径会绕过代理，直接请求 localhost:8080
axios.get('http://localhost:8080/dev-api/user/info')
正确示例（相对路径，触发代理）：
// ✅ 相对路径，会被代理转发到 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 兼容的代理配置：
{
"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 为例）：
@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 代理，需添加：
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 核心版本：
npm update @dcloudio/uni-app @dcloudio/uni-cli-shared -
或降级到稳定版本（如 3.4.0+）：
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 原生代理配置：
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
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 部分删除（避免冲突），保留必要配置即可：
{
"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 字符串格式）：
{
"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 后，前端发送请求：
// 示例：用 axios 发送请求
axios.get('/dev-api/user/info')
查看终端日志（开启 logLevel: 'debug' 后），若出现：
[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 项目一致，维护成本更低。
