一、先搞懂:前端视角的 Nginx 代理核心概念
1. 什么是 Nginx 代理?
Nginx 是一款高性能的 HTTP 服务器 / 反向代理服务器,对前端来说,「代理」就是:
- 前端请求 → 先发给 Nginx 服务器 → Nginx 代替前端请求后端接口 / 获取资源 → Nginx 将结果返回给前端。
- 核心价值:突破浏览器「同源策略」(跨域)、统一接口域名、优化资源加载(缓存 / 压缩)。
2. 代理的核心类型(前端只关注这 2 种)
| 代理类型 |
|---|
从前端视角详解 Nginx 反向代理的核心概念与应用场景。主要涵盖解决跨域问题、多环境接口转发、静态资源优化及本地开发代理替代方案。通过配置 proxy_pass、try_files 等指令,实现接口统一转发、路由兼容及缓存压缩,提升部署效率与性能。重点讲解了开发环境与生产环境的配置差异,以及如何处理 Vue/React 路由刷新 404 问题。
Nginx 是一款高性能的 HTTP 服务器 / 反向代理服务器,对前端来说,「代理」就是:
| 代理类型 |
|---|
| 核心作用 |
|---|
| 前端使用场景 |
|---|
| 反向代理(常用) | Nginx 代理前端请求到后端服务器(隐藏后端地址) | 解决跨域、接口转发、部署多环境 |
| 正向代理 | Nginx 代理前端访问外部网络(如翻墙) | 开发环境访问外网接口(极少用) |
对前端来说,99% 的场景都是「反向代理」,下文所有内容均围绕反向代理展开。
浏览器的「同源策略」要求前端页面和接口的「协议、域名、端口」必须一致,否则跨域。Nginx 代理能让前端请求先到 Nginx(同源),再由 Nginx 转发到后端(Nginx 无跨域限制)。
前端代码中请求写法(无需写完整后端地址,直接请求同源的 /api):
// 前端请求:http://localhost:8080/api/user → Nginx 转发到 http://192.168.1.100:8081/user
axios.get('/api/user').then(res => console.log(res));
配置示例(nginx.conf):
# 配置 Nginx 监听本地端口(和前端页面同源)
server {
listen 8080; # 前端页面运行在 http://localhost:8080
server_name localhost;
# 代理后端接口:前端请求 /api → 转发到后端真实地址
location /api/ {
proxy_pass http://192.168.1.100:8081/;
# 关键配置:传递请求头(解决跨域 + 后端识别来源)
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;
}
# 代理前端静态资源(本地打包后的 dist 目录)
location / {
root /Users/xxx/project/dist; # 前端 dist 目录绝对路径
index index.html index.htm;
try_files $uri $uri/ /index.html; # 解决 Vue/React 路由刷新 404
}
}
核心配置(生产环境优化版):
server {
listen 80;
server_name www.xxx.com; # 前端域名
# 静态资源缓存(优化加载速度)
location ~* \.(js|css|png|jpg|gif|svg)$ {
root /usr/share/nginx/html; # 前端 dist 目录
expires 7d; # 静态资源缓存 7 天
gzip on; # 开启 gzip 压缩
}
# 接口代理:前端请求 /api → 转发到后端服务器集群
location /api/ {
proxy_pass http://backend_server/; # 后端集群地址(可配置多个)
proxy_connect_timeout 60s; # 连接超时
proxy_read_timeout 60s; # 读取超时
# 跨域头(生产环境若前端和 Nginx 同源,可省略)
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods 'GET,POST,PUT,DELETE';
}
# 前端路由兼容(Vue/React History 模式)
location / {
root /usr/share/nginx/html;
index index.html index.htm;
try_files $uri $uri/ /index.html; # 刷新页面不 404
}
}
前端开发中常需切换接口环境(开发 / 测试 / 生产),Nginx 可通过不同 location 配置转发到不同后端:
server {
listen 8080;
server_name localhost;
# 开发环境接口
location /api/dev/ {
proxy_pass http://dev.xxx.com/;
}
# 测试环境接口
location /api/test/ {
proxy_pass http://test.xxx.com/;
}
# 生产环境接口
location /api/prod/ {
proxy_pass http://prod.xxx.com/;
}
}
前端只需修改请求路径(如 /api/dev/user → /api/test/user),即可切换环境,无需改代码。
Nginx 可代理前端静态资源(JS/CSS/ 图片),并配置缓存、压缩、防盗链,提升页面加载速度:
server {
listen 80;
server_name www.xxx.com;
# 静态资源配置
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
root /usr/share/nginx/html;
expires 30d; # 缓存 30 天
gzip on; # 开启 gzip 压缩(减小文件体积)
gzip_types text/css application/javascript image/png;
# 防盗链(只允许自己域名访问资源)
valid_referers www.xxx.com;
if ($invalid_referer) {
return 403;
}
}
# 前端页面
location / {
root /usr/share/nginx/html;
index index.html;
try_files $uri $uri/ /index.html;
}
}
Vue CLI 的 devServer.proxy、Vite 的 server.proxy 本质是「Node 代理」,但复杂场景(如多域名、自定义请求头)不如 Nginx 灵活。
npm run dev(运行在 http://localhost:5173);/api/user → Nginx 转发到后端,解决跨域。配置 Nginx 监听 5173,转发接口:
server {
listen 5173;
server_name localhost;
# 代理接口到后端
location /api/ {
proxy_pass http://192.168.1.100:8081/;
}
# 代理 Vite 开发服务器(前端页面)
location / {
proxy_pass http://localhost:5173/;
proxy_set_header Host $host;
}
}
brew install nginx;nginx.exe;yum install nginx(CentOS)/ apt install nginx(Ubuntu)。/usr/local/etc/nginx/nginx.conf;nginx-xxx/conf/nginx.conf;/etc/nginx/nginx.conf 或 /etc/nginx/conf.d/default.conf;server 块,添加代理规则(参考上面的场景配置)。# 启动 Nginx
nginx
# 重启 Nginx(修改配置后)
nginx -s reload
# 停止 Nginx
nginx -s stop
# 检查配置是否正确
nginx -t
/api/user),而非完整后端地址(如 http://192.168.1.100:8081/user);withCredentials),由 Nginx 处理。| 场景 | 核心配置关键词 |
|---|---|
| 跨域接口代理 | proxy_pass + 跨域头 |
| 前端路由兼容 | try_files $uri $uri/ /index.html |
| 静态资源缓存 | expires + gzip |
| 多环境接口转发 | 不同 location 配置 |
proxy_pass 时,末尾的 / 很关键:
proxy_pass http://backend/;:前端请求 /api/user → 转发到 http://backend/user;proxy_pass http://backend;:前端请求 /api/user → 转发到 http://backend/api/user;try_files 解决前端路由刷新 404 问题。简单记:对前端来说,Nginx 代理就是「解决跨域的中间服务器」+「部署优化的工具」,核心配置就围绕 proxy_pass(转发)、try_files(路由)、expires/gzip(资源)这几个关键点。
后端 Koa 服务 (app.js)
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
router.get('/api/login', async ctx => {
ctx.body = 'login success';
});
app.use(router.routes());
app.listen(3000, () => console.log('server running at port 3000...'));
前端页面 (index.html)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>前端页面</title>
</head>
<body>
<h1>前端页面,运行在 8000 端口</h1>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script>
axios.get('/api/login').then(res => {
console.log('data', res.data);
});
</script>
</body>
</html>
Nginx 反向代理配置
server {
listen 8080;
server_name localhost;
# 请求路径为/,代理到 8000 端口(前端)
location / {
proxy_pass http://localhost:8000;
}
# 请求路径为/api,代理到 3000 端口(后端)
location /api {
proxy_pass http://localhost:3000;
}
}

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online