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

1. 打开官网：https://nginx.org/en/download.html
2. 在 Windows version 下点击最新稳定版（如 nginx/Windows-1.25.5）
3. 下载后解压到任意目录，例如：

D:\tools\nginx-1.25.5 

注意：Windows 版本是'开发用途'，官方建议生产环境使用 Linux，但本地开发完全够用。

步骤 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. 访问前端：浏览器打开 http://localhost → 显示你的 Vue 应用
2. 调用 API：前端代码中请求 /api/login，实际被 Nginx 转发到 http://localhost:8080/login
3. 无跨域问题：因为浏览器只和 Nginx 通信（同源），Nginx 再与后端通信，完美绕过 CORS

六、常见问题排查

问题 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