❌

阅读视图

发现新文章，点击刷新页面。

Nginx 部署 Vue3 项目完整指南

✇掘金 前端
H5开发新纪元

Nginx 部署 Vue3 项目完整指南

本文档详细说明如何使用 Nginx 部署 Vue3 单页应用，包括本地开发环境和服务端生产环境的配置差异。

目录

  1. Nginx 基础知识
  2. 本地开发环境配置
  3. 服务器生产环境配置
  4. 本地与服务器的配置差异
  5. 完整部署流程
  6. 常用命令速查
  7. 常见问题排查

1. Nginx 基础知识

1.1 什么是 Nginx？

Nginx 是一个高性能的 HTTP 和反向代理服务器，也是一个 IMAP/POP3/SMTP 服务器。在 Web 开发中，主要用途：

  • 静态资源服务器：托管 HTML、CSS、JS、图片等静态文件
  • 反向代理：将请求转发到后端服务器
  • 负载均衡：将请求分发到多台服务器

1.2 Nginx 目录结构

nginx-1.24.0/
├── conf/               # 配置文件目录
│   ├── nginx.conf      # 主配置文件（最重要）
│   ├── mime.types      # 文件类型映射
│   └── ...
├── html/               # 默认静态文件目录
│   ├── index.html
│   └── 50x.html
├── logs/               # 日志目录
│   ├── access.log      # 访问日志
│   └── error.log       # 错误日志
├── temp/               # 临时文件目录
├── contrib/            # 扩展模块
├── docs/               # 文档
└── nginx.exe           # Windows 可执行文件

1.3 配置文件基本结构

# 全局块 - 影响 Nginx 整体运行
worker_processes  1;  # 工作进程数

# events 块 - 影响网络连接
events {
    worker_connections  1024;  # 每个进程最大连接数
}

# http 块 - Web 服务器配置
http {
    # http 全局配置
    include       mime.types;

    # server 块 - 虚拟主机配置
    server {
        listen       80;        # 监听端口
        server_name  localhost; # 域名/IP

        # location 块 - 路由匹配
        location / {
            root   html;        # 静态文件目录
            index  index.html;  # 默认首页
        }
    }
}

2. 本地开发环境配置

2.1 当前项目配置

配置文件位置：C:\Users\EDY\Downloads\nginx-1.24.0\nginx-1.24.0\conf\nginx.conf

#user  nobody;
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;

        # 你的 Vue3 项目打包后的目录
        root   D:/test/vue3-h5/dist;
        index  index.html index.htm;

        location / {
            # Vue 是单页应用，所有路由都要返回 index.html
            try_files $uri $uri/ /index.html;
        }

        # 开启 gzip 压缩，加快加载速度
        gzip on;
        gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
        gzip_min_length 1000;

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }
}

2.2 配置详解

配置项 值 说明
listen 80 监听端口，本地访问用 localhost:80
server_name localhost 本地测试用 localhost
root D:/test/vue3-h5/dist 指向本地打包目录
try_files uriuri uri/ /index.html Vue SPA 路由支持
gzip on 开启压缩，提升加载速度

2.3 启动步骤

# 1. 进入 Nginx 目录
cd C:\Users\EDY\Downloads\nginx-1.24.0\nginx-1.24.0

# 2. 启动 Nginx
start nginx

# 3. 访问测试
# 浏览器打开 http://localhost

3. 服务器生产环境配置

3.1 完整的服务器配置

# 生产环境配置示例

# 根据 CPU 核心数设置工作进程
worker_processes  auto;

# 错误日志级别设为 warn
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    # 最大连接数，根据服务器配置调整
    worker_connections  2048;
    # 提高并发性能
    use epoll;
    multi_accept on;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 日志格式
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    # 访问日志
    access_log  /var/log/nginx/access.log  main;

    # 性能优化
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    types_hash_max_size 2048;

    # 开启 gzip 压缩
    gzip  on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 1000;
    gzip_types
        text/plain
        text/css
        text/xml
        application/json
        application/javascript
        application/xml
        application/xml+rss
        text/javascript
        image/svg+xml;

    # 安全头配置
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # 上传文件大小限制（如果需要）
    client_max_body_size 10M;

    # Vue 应用服务器配置
    server {
        listen       80;
        server_name  your-domain.com;  # 替换为你的域名

        # 静态文件目录（服务器上的路径）
        root   /var/www/vue3-h5/dist;
        index  index.html index.htm;

        # Vue Router history 模式支持
        location / {
            try_files $uri $uri/ /index.html;
        }

        # 静态资源缓存（js、css、图片等）
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        # 禁止访问隐藏文件
        location ~ /\. {
            deny all;
        }

        # 错误页面
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   /usr/share/nginx/html;
        }
    }

    # HTTPS 配置（推荐使用）
    # server {
    #     listen       443 ssl http2;
    #     server_name  your-domain.com;
    #
    #     # SSL 证书配置
    #     ssl_certificate      /etc/nginx/ssl/your-domain.com.pem;
    #     ssl_certificate_key  /etc/nginx/ssl/your-domain.com.key;
    #
    #     # SSL 优化配置
    #     ssl_session_timeout  1d;
    #     ssl_session_cache    shared:SSL:50m;
    #     ssl_session_tickets  off;
    #
    #     # 现代 SSL 配置
    #     ssl_protocols TLSv1.2 TLSv1.3;
    #     ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    #     ssl_prefer_server_ciphers  on;
    #
    #     # HSTS
    #     add_header Strict-Transport-Security "max-age=31536000" always;
    #
    #     root   /var/www/vue3-h5/dist;
    #     index  index.html;
    #
    #     location / {
    #         try_files $uri $uri/ /index.html;
    #     }
    # }

    # HTTP 自动跳转 HTTPS
    # server {
    #     listen 80;
    #     server_name your-domain.com;
    #     return 301 https://$server_name$request_uri;
    # }
}

3.2 反向代理配置（如果需要调用后端 API）

server {
    listen       80;
    server_name  your-domain.com;

    root   /var/www/vue3-h5/dist;
    index  index.html;

    # 前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api/ {
        proxy_pass http://backend-server: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;

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

4. 本地与服务器的配置差异

4.1 差异对比表

配置项 本地开发环境 服务器生产环境 说明
worker_processes 1 auto 生产环境根据 CPU 核心数自动设置
worker_connections 1024 2048+ 服务器并发要求更高
server_name localhost your-domain.com 本地用 localhost，服务器用域名
root 路径 D:/test/vue3-h5/dist /var/www/vue3-h5/dist Windows 和 Linux 路径格式不同
error_log 注释掉 /var/log/nginx/error.log warn 生产环境需要记录日志
access_log 注释掉 /var/log/nginx/access.log main 生产环境需要访问日志
gzip 基础配置 完整配置 生产环境需要更细致的压缩配置
缓存配置 无 有 生产环境需要静态资源缓存
安全头 无 有 生产环境需要安全防护
HTTPS 无 推荐 生产环境强烈推荐 HTTPS
反向代理 通常不需要 常需要 生产环境常需要代理后端 API

4.2 路径格式差异

Windows 本地路径：

root   D:/test/vue3-h5/dist;    # 使用正斜杠 /
root   D:\\test\\vue3-h5\\dist;  # 或使用双反斜杠转义

Linux 服务器路径：

root   /var/www/vue3-h5/dist;   # Linux 标准路径格式

4.3 域名配置差异

本地开发：

server_name  localhost;          # 本机访问
# 或
server_name  127.0.0.1;         # 本机 IP

服务器生产：

server_name  your-domain.com;    # 你的域名
server_name  www.your-domain.com; # 多个域名
server_name  192.168.1.100;      # 或直接用服务器 IP

4.4 端口配置差异

本地开发（80 端口可能被占用）：

listen  8080;   # 如果 80 被占用，可以用其他端口

服务器生产：

listen  80;     # HTTP 默认端口
listen  443 ssl http2;  # HTTPS 端口

5. 完整部署流程

5.1 本地部署步骤

# 1. 打包 Vue 项目
cd D:/test/vue3-h5
npm run build
# 打包后会生成 dist 目录

# 2. 修改 Nginx 配置
# 编辑 C:\Users\EDY\Downloads\nginx-1.24.0\nginx-1.24.0\conf\nginx.conf
# 设置 root 指向 dist 目录

# 3. 启动 Nginx
cd C:\Users\EDY\Downloads\nginx-1.24.0\nginx-1.24.0
start nginx

# 4. 访问测试
# 浏览器打开 http://localhost

5.2 服务器部署步骤

第一步：准备服务器环境
# 以 Ubuntu/Debian 为例
# 1. 更新系统
sudo apt update && sudo apt upgrade -y

# 2. 安装 Nginx
sudo apt install nginx -y

# 3. 检查 Nginx 状态
sudo systemctl status nginx

# 4. 设置开机自启
sudo systemctl enable nginx
第二步：上传打包文件
# 方式一：使用 scp 上传
scp -r D:/test/vue3-h5/dist user@server-ip:/var/www/vue3-h5/

# 方式二：使用 FTP 工具（如 FileZilla）上传

# 方式三：在服务器上直接打包
# 先上传源码，在服务器上运行 npm run build
第三步：配置 Nginx
# 1. 创建配置文件
sudo nano /etc/nginx/sites-available/vue3-h5

# 2. 写入配置内容（参考上面的生产环境配置）

# 3. 创建软链接启用配置
sudo ln -s /etc/nginx/sites-available/vue3-h5 /etc/nginx/sites-enabled/

# 4. 测试配置是否正确
sudo nginx -t

# 5. 重载 Nginx
sudo systemctl reload nginx
第四步：配置域名（如果有）
# 1. 在域名服务商处添加 DNS 解析
#    类型: A
#    主机: @
#    值: 服务器 IP

# 2. 等待 DNS 生效（几分钟到几小时）

# 3. 测试访问
curl -I http://your-domain.com
第五步：配置 HTTPS（推荐）
# 使用 Let's Encrypt 免费证书

# 1. 安装 Certbot
sudo apt install certbot python3-certbot-nginx -y

# 2. 自动配置 HTTPS
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# 3. 测试自动续期
sudo certbot renew --dry-run

# Certbot 会自动修改 Nginx 配置，添加 SSL 相关配置

5.3 部署检查清单

  • 项目已打包（npm run build）
  • dist 目录已上传到服务器
  • Nginx 已安装并运行
  • Nginx 配置文件已正确设置
  • root 路径指向正确的 dist 目录
  • server_name 已设置正确的域名/IP
  • 防火墙已开放 80/443 端口
  • 域名 DNS 已解析到服务器
  • HTTPS 证书已配置（推荐）
  • 网站可以正常访问

6. 常用命令速查

6.1 Windows 本地命令

# 进入 Nginx 目录
cd C:\Users\EDY\Downloads\nginx-1.24.0\nginx-1.24.0

# 启动 Nginx
start nginx

# 停止 Nginx
nginx -s stop          # 快速停止
nginx -s quit          # 优雅停止（处理完当前请求）

# 重载配置（修改配置后）
nginx -s reload

# 重新打开日志文件
nginx -s reopen

# 测试配置文件语法
nginx -t

# 查看 Nginx 版本
nginx -v

# 查看 Nginx 进程
tasklist | findstr nginx

# 强制结束所有 Nginx 进程
taskkill /F /IM nginx.exe

6.2 Linux 服务器命令

# 启动 Nginx
sudo systemctl start nginx

# 停止 Nginx
sudo systemctl stop nginx

# 重启 Nginx
sudo systemctl restart nginx

# 重载配置（不中断服务）
sudo systemctl reload nginx

# 查看 Nginx 状态
sudo systemctl status nginx

# 设置开机自启
sudo systemctl enable nginx

# 取消开机自启
sudo systemctl disable nginx

# 测试配置文件
sudo nginx -t

# 查看 Nginx 版本
nginx -v

# 查看错误日志
sudo tail -f /var/log/nginx/error.log

# 查看访问日志
sudo tail -f /var/log/nginx/access.log

6.3 Vue 项目相关命令

# 开发环境运行
npm run dev

# 生产环境打包
npm run build

# 预览打包结果
npm run preview

7. 常见问题排查

7.1 页面空白

可能原因：

  1. 路由模式问题
  2. 静态资源路径问题
  3. 打包配置问题

排查步骤：

# 1. 检查 dist 目录是否有 index.html
ls dist/index.html

# 2. 检查浏览器控制台错误
# F12 打开开发者工具，查看 Console 和 Network

# 3. 检查 vite.config.ts 的 base 配置
# 如果部署在子路径，需要设置 base

解决方案：

// vite.config.ts
export default defineConfig({
  // 部署在根路径
  base: '/',

  // 如果部署在子路径（如 http://domain.com/app/）
  // base: '/app/',
})

7.2 404 Not Found

可能原因：

  1. root 路径配置错误
  2. 静态文件未正确上传

排查步骤：

# 1. 检查 root 路径是否正确
ls /var/www/vue3-h5/dist/index.html

# 2. 检查 Nginx 配置
sudo nginx -t

# 3. 检查文件权限
ls -la /var/www/vue3-h5/dist

解决方案：

# 修复文件权限
sudo chown -R www-data:www-data /var/www/vue3-h5
sudo chmod -R 755 /var/www/vue3-h5

7.3 刷新页面 404

原因：Vue Router 使用 history 模式，需要 Nginx 配置支持

解决方案：确保 Nginx 配置中有：

location / {
    try_files $uri $uri/ /index.html;
}

7.4 端口被占用

Windows 排查：

# 查看端口占用
netstat -ano | findstr :80

# 结束占用进程（PID 是上面查到的进程 ID）
taskkill /PID <进程ID> /F

Linux 排查：

# 查看端口占用
sudo lsof -i :80

# 或
sudo netstat -tlnp | grep :80

# 结束占用进程
sudo kill -9 <PID>

7.5 Nginx 配置修改不生效

# 1. 测试配置是否正确
nginx -t

# 2. 重载配置
nginx -s reload      # Windows
sudo systemctl reload nginx  # Linux

# 3. 清除浏览器缓存后刷新页面
# Ctrl + F5 强制刷新

7.6 跨域问题

问题现象：API 请求报 CORS 错误

解决方案一：Nginx 反向代理

location /api/ {
    proxy_pass http://backend-server: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;
}

解决方案二：添加 CORS 头

location /api/ {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';

    if ($request_method = 'OPTIONS') {
        return 204;
    }

    proxy_pass http://backend-server:8080/;
}

附录：配置文件模板

A. 本地开发配置模板

# 简化版本地配置
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;

        root   D:/test/vue3-h5/dist;
        index  index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }

        gzip on;
        gzip_types text/plain text/css application/json application/javascript;
    }
}

B. 服务器生产配置模板

# 生产环境完整配置
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  2048;
    use epoll;
    multi_accept on;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;

    gzip  on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_min_length 1000;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    server {
        listen       80;
        server_name  your-domain.com;

        root   /var/www/vue3-h5/dist;
        index  index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }

        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        location ~ /\. {
            deny all;
        }

        error_page 500 502 503 504 /50x.html;
        location = /50x.html {
            root /usr/share/nginx/html;
        }
    }
}

总结

环境 关键配置 访问方式
本地 localhost + 本地路径 http://localhost
服务器 域名/IP + 服务器路径 + 优化配置 your-domain.com

部署核心流程：

  1. 本地打包 npm run build
  2. 上传 dist 到服务器
  3. 配置 Nginx 指向 dist 目录
  4. 配置 try_files 支持 Vue Router
  5. 重载 Nginx 配置
  6. 测试访问

如有问题，优先查看 Nginx 错误日志进行排查。

❌