登录Nginx 部署 Vue3 项目完整指南
Nginx 部署 Vue3 项目完整指南
本文档详细说明如何使用 Nginx 部署 Vue3 单页应用，包括本地开发环境和服务端生产环境的配置差异。
目录
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 |
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. 检查 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
可能原因：
- root 路径配置错误
- 静态文件未正确上传
排查步骤：
# 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 |
部署核心流程：
- 本地打包
npm run build - 上传 dist 到服务器
- 配置 Nginx 指向 dist 目录
- 配置
try_files支持 Vue Router - 重载 Nginx 配置
- 测试访问
如有问题，优先查看 Nginx 错误日志进行排查。
