Windows 下 Nginx 配置全指南：前端 Vue + 后端服务一体化部署

在现代 Web 开发中，前后端分离架构已成为主流。前端使用 Vue、React 等框架构建 SPA（单页应用），后端提供 RESTful API 服务。为了在本地或生产环境中高效部署这类应用，Nginx 是一个非常优秀的轻量级 Web 服务器和反向代理工具。

本文将手把手教你如何在 Windows 系统下下载、安装并配置 Nginx，实现：

• 前端 Vue 项目的静态资源托管
• 后端 API 请求的反向代理（解决跨域）
• 统一入口访问（如 http://localhost）

一、准备工作

1. 系统要求

• Windows 7 / 10 / 11 / Server 系列
• 已安装 Node.js（用于构建 Vue 项目）
• 后端服务（如 Spring Boot、Node.js、Python Flask 等）已能正常运行（例如监听 http://localhost:8080）

二、下载并安装 Nginx（Windows 版）

Nginx 官方不提供 Windows 安装包，但提供了可直接运行的压缩包。

步骤 1：下载 Nginx

步骤 2：启动 Nginx

• 打开命令提示符（CMD）或 PowerShell，进入 Nginx 目录：cd D:\\tools\\nginx-1.25.5
• 启动 Nginx：start nginx
• 打开浏览器访问 http://localhost，看到 “Welcome to nginx!” 页面即表示启动成功。

小贴士：

• 停止 Nginx：nginx -s stop
• 重载配置：nginx -s reload（修改配置后必须执行！）
• 查看进程：任务管理器中查找 nginx.exe

三、构建并部署 Vue 前端项目

假设你已有一个 Vue 项目（Vue 2 或 Vue 3）。

步骤 1：构建生产版本

cd your-vue-project
npm run build

生成的静态文件默认在 dist/ 目录下。

步骤 2：将 dist 文件夹复制到 Nginx

建议结构如下：

D:\\tools\\nginx-1.25.5\\
├── html/
│ └── vue-app/ ← 把 dist 内容放这里
├── conf/
│ └── nginx.conf ← 主配置文件
└── …

或者直接替换 html 目录下的内容（简单场景）：

# 清空原 html，放入你的 Vue 构建产物
rmdir /s /q html
xcopy dist html /e /i

四、配置 Nginx：前端 + 后端一体化

关键在于 反向代理（Reverse Proxy） —— 将 /api 开头的请求转发给后端服务，其余请求返回前端页面。

修改 conf/nginx.conf

打开 nginx.conf，找到 server 块，替换为以下内容：

server {
listen 80;
server_name localhost;

# 前端静态资源
location / {
root html/vue-app; # 指向你的 Vue dist 目录
index index.html index.htm;
try_files $uri $uri/ /index.html; # 支持 Vue Router 的 history 模式
}

# 后端 API 反向代理（解决跨域）
location /api/ {
proxy_pass http://localhost:8080/; # 注意结尾的斜杠！
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;
}

# 可选：其他后端服务（如 WebSocket）
# location /ws/ {
# proxy_pass http://localhost:9000;
# proxy_http_version 1.1;
# proxy_set_header Upgrade $http_upgrade;
# proxy_set_header Connection "upgrade";
# }
}

配置说明：

• root html/vue-app;：指定前端资源根目录
• try_files $uri $uri/ /index.html;：确保 Vue Router 的 history 模式能正常刷新页面
• proxy_pass http://localhost:8080/;：将 /api/xxx 请求代理到后端（如 Spring Boot 默认端口 8080）

  注意：proxy_pass 结尾的 / 很重要！

  • 有 /：/api/user → http://localhost:8080/user
  • 无 /：/api/user → http://localhost:8080/api/user

重载配置

修改完后，在 Nginx 目录下执行：

nginx -s reload

五、验证效果

六、常见问题排查

问题1：404 页面找不到

• 检查 root 路径是否正确（建议用绝对路径）
• 确保 try_files 配置存在（Vue Router 必需）

问题2：API 请求 502 Bad Gateway

• 后端服务未启动？检查 http://localhost:8080 是否能直接访问
• proxy_pass 地址写错？注意端口号和协议（http/https）

问题3：修改配置后未生效

• 必须执行 nginx -s reload
• 检查配置语法：nginx -t 可验证配置文件是否正确

七、进阶建议

• 多环境配置：可为 dev/test/prod 创建不同 nginx.conf
• HTTPS 本地测试：使用 mkcert 生成本地证书，配置 SSL
• 开机自启：将 start nginx 加入 Windows 任务计划程序
• 日志分析：查看 logs/access.log 和 logs/error.log