Nginx代理是部署时在服务端配置的反向代理,用于生产环境解决跨域和路径统一问题;开发阶段必须用vue.config.js的devServer.proxy,因打包后H5请求直连网络,无代理则触发CORS或404。

直接说结论:Nginx 代理不是 uni-app 自身的配置,而是部署时在 Nginx 侧做的反向代理,用来解决生产环境跨域和接口路径统一问题。开发阶段用 vue.config.js 的 devServer.proxy,上线后必须切到 Nginx 的 location + proxy_pass,否则请求会 404 或跨域失败。
为什么不能只靠开发代理?
因为 devServer.proxy 只在 npm run serve 本地启动时生效,打包成 H5 后所有请求都走真实网络——此时浏览器直连后端,若域名、协议、端口不一致,就会触发 CORS。而 Nginx 作为服务端反向代理,能隐藏真实后端地址,让前端所有请求看起来都“同源”。
常见错误现象:
- 页面能打开,但接口全部 404(Nginx 没配
location /api/) - 接口返回 502(
proxy_pass地址写错,或后端没起来) - 登录态丢失(漏配
proxy_set_header Cookie $http_cookie,尤其带 session 的接口)
nginx.conf 里怎么写 location 和 proxy_pass
核心是两段:静态资源路由 + API 代理。不要把它们写进同一个 location / 块里。
正确写法示例(关键参数已加粗):
server {
listen 80;
server_name example.com;
<pre class='brush:php;toolbar:false;'># 静态资源(uni-app 打包后的 dist/build/h5)
location / {
root /var/www/html/uniapp;
index index.html;
try_files $uri $uri/ /index.html; # 必须!支持 hash 路由回退
}
# API 代理(假设后端接口地址是 http://192.168.1.100:3000)
location /api/ {
proxy_pass http://192.168.1.100:3000/; # 注意末尾斜杠:有则去掉前缀,无则保留
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}}
重点说明:
-
proxy_pass末尾带/:请求/api/user会被转发为http://.../user(自动剥离/api) -
proxy_pass末尾不带/:请求/api/user会被转发为http://.../api/user -
try_files $uri $uri/ /index.html是 uni-app 的刚需,否则刷新页面 404(hash 模式也依赖它) - 如果后端是 HTTPS,
proxy_pass必须写https://,且确保 Nginx 编译时含 OpenSSL 支持
uni-app 代码里请求路径怎么写?
前端代码中所有接口调用,路径必须跟 Nginx 的 location 前缀严格对齐。比如你配了 location /api/,那 JS 里就得写:
uni.request({
url: '/api/login', // ✅ 正确:以 /api/ 开头
method: 'POST',
success: res => console.log(res)
});不能写:
-
url: 'http://192.168.1.100:3000/login'(硬编码后端地址,上线必挂) -
url: '/login'(没加/api/前缀,Nginx 不会代理,直接跨域) -
url: 'api/login'(缺开头斜杠,变成相对路径,可能拼成http://example.com/current-path/api/login)
更稳妥的做法是抽成常量:
const API_BASE = '/api';
uni.request({ url: API_BASE + '/login' });HTTPS 环境下要注意什么?
如果用 HTTPS 域名访问前端,但 proxy_pass 指向 HTTP 后端,Nginx 默认允许(称作“mixed content”代理),但部分浏览器会拦截非安全响应。解决方案只有两个:
- 后端也上 HTTPS(推荐),
proxy_pass https://backend.example.com/ - 若后端暂不支持 HTTPS,需在 Nginx 的
location块中显式关闭 SSL 验证(仅限内网可信环境):proxy_ssl_verify off;proxy_ssl_trusted_certificate /path/to/ca.crt;
另外,SSL 配置本身要放在 server { listen 443 ssl; ... } 块里,别和 listen 80 混在一起;证书路径必须用绝对路径,且 Nginx 进程要有读取权限。
最容易被忽略的一点:Nginx reload 后,一定要检查 proxy_pass 目标服务是否真的可达——用 curl -v http://192.168.1.100:3000/health 在服务器本机测,别只看浏览器控制台报错。


















