1. 项目概述
最近在帮朋友部署一个Vue.js项目到Ubuntu 22.04服务器上,发现网上很多教程要么过于简单,要么步骤不完整。作为一个踩过不少坑的老手,我决定把完整的部署流程记录下来,特别是那些容易被忽略的细节和配置要点。
这个教程将带你从零开始,在Ubuntu 22.04系统上通过Nginx部署Vue项目。不同于其他教程只告诉你"怎么做",我会详细解释每个步骤"为什么"要这样做,以及在实际生产环境中需要注意哪些问题。
2. 环境准备
2.1 系统要求
首先确认你的服务器满足以下条件:
- Ubuntu 22.04 LTS(长期支持版本)
- 至少1GB内存(Vue项目本身不耗资源,但Nginx需要)
- 已配置好SSH访问
- 拥有sudo权限的用户
提示:如果是新服务器,建议先执行
sudo apt update && sudo apt upgrade -y更新系统
2.2 安装Nginx
Nginx的安装非常简单,但有几个关键点需要注意:
bash复制# 更新软件包索引
sudo apt update
# 安装Nginx
sudo apt install nginx -y
安装完成后,可以通过以下命令检查Nginx状态:
bash复制sudo systemctl status nginx
正常情况下应该看到"active (running)"的状态。此时在浏览器访问服务器IP,应该能看到Nginx的欢迎页面。
注意:如果无法访问,可能是防火墙阻止了80端口。Ubuntu默认使用ufw防火墙,可以通过
sudo ufw allow 'Nginx HTTP'开放端口。
3. 项目部署准备
3.1 Vue项目构建
在本地开发环境,进入Vue项目目录执行:
bash复制npm run build
这会生成dist目录,里面包含了所有静态文件。需要将这个目录上传到服务器,我推荐的位置是/var/www/vue-app:
bash复制# 在服务器上创建目录
sudo mkdir -p /var/www/vue-app
# 设置权限(确保Nginx能读取)
sudo chown -R $USER:$USER /var/www/vue-app
sudo chmod -R 755 /var/www/vue-app
然后使用scp或rsync将dist目录内容上传:
bash复制scp -r dist/* user@your_server_ip:/var/www/vue-app
3.2 Nginx目录结构解析
理解Nginx的配置文件结构非常重要:
code复制/etc/nginx/
├── nginx.conf # 主配置文件
├── sites-available/ # 所有可用的站点配置
├── sites-enabled/ # 实际启用的站点配置(软链接)
├── conf.d/ # 额外的配置文件
└── snippets/ # 可复用的配置片段
关键点:
sites-available是配置仓库,存放所有可能的配置sites-enabled通过软链接启用特定配置- 修改配置后一定要测试语法
sudo nginx -t
4. Nginx配置详解
4.1 创建Vue应用配置
在/etc/nginx/sites-available/下创建vue-app文件:
nginx复制server {
listen 80;
listen [::]:80;
server_name your_domain.com; # 如果没有域名就用_
root /var/www/vue-app;
index index.html;
location / {
try_files $uri $uri/ /index.html;
expires -1; # 禁用缓存,开发时很有用
}
# 代理API请求示例
location /api/ {
proxy_pass http://localhost:3000/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
expires 1y;
add_header Cache-Control "public, no-transform";
}
}
4.2 关键配置解析
-
SPA路由处理:
try_files $uri $uri/ /index.html确保Vue路由能正常工作- 没有这个配置,刷新非根路由会返回404
-
缓存控制:
- 根路径设置
expires -1禁用缓存,方便开发调试 - 静态资源设置长期缓存,利用浏览器缓存提升性能
- 根路径设置
-
API代理:
- 将
/api/开头的请求代理到后端服务 - 设置了必要的headers保证WebSocket等高级功能正常工作
- 将
4.3 启用配置
bash复制# 创建软链接启用配置
sudo ln -s /etc/nginx/sites-available/vue-app /etc/nginx/sites-enabled/
# 测试配置
sudo nginx -t
# 重启Nginx
sudo systemctl restart nginx
重要:如果之前有default配置,建议先删除:
sudo rm /etc/nginx/sites-enabled/default
5. 高级配置与优化
5.1 开启Gzip压缩
在/etc/nginx/nginx.conf的http块中添加:
nginx复制gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml application/json application/javascript application/xml+rss application/atom+xml image/svg+xml;
这可以显著减小传输体积,提升加载速度。
5.2 配置HTTPS
使用Let's Encrypt免费证书:
bash复制sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain.com
Certbot会自动修改Nginx配置并设置自动续期。
5.3 性能调优
根据服务器配置调整worker进程:
nginx复制worker_processes auto; # 自动根据CPU核心数设置
events {
worker_connections 1024; # 每个worker的最大连接数
}
在server块中添加:
nginx复制client_max_body_size 20M; # 允许上传大文件
keepalive_timeout 65; # 保持连接时间
6. 常见问题排查
6.1 403 Forbidden错误
可能原因:
- Nginx用户没有访问权限
- SELinux限制(如果是CentOS)
- 目录索引被禁用
解决方案:
bash复制sudo chown -R www-data:www-data /var/www/vue-app
sudo chmod -R 755 /var/www/vue-app
6.2 路由刷新404
确保配置中包含:
nginx复制location / {
try_files $uri $uri/ /index.html;
}
6.3 静态资源加载失败
检查:
- 文件路径是否正确
- 文件权限
- Nginx配置的root是否正确
- 是否配置了正确的MIME类型
6.4 Nginx启动失败
使用sudo nginx -t测试配置,常见错误:
- 缺少分号
- 括号不匹配
- 路径错误
7. 维护与监控
7.1 日志查看
Nginx日志位置:
- 访问日志:
/var/log/nginx/access.log - 错误日志:
/var/log/nginx/error.log
查看实时日志:
bash复制sudo tail -f /var/log/nginx/error.log
7.2 性能监控
安装ngxtop实时监控:
bash复制sudo apt install ngxtop
ngxtop
7.3 自动部署脚本
创建一个部署脚本deploy.sh:
bash复制#!/bin/bash
npm run build
rsync -avz --delete dist/ user@server:/var/www/vue-app/
ssh user@server "sudo systemctl restart nginx"
给执行权限:chmod +x deploy.sh
8. 安全加固建议
-
禁用服务器标识:
nginx复制server_tokens off; -
限制HTTP方法:
nginx复制if ($request_method !~ ^(GET|HEAD|POST)$ ) { return 405; } -
防止点击劫持:
nginx复制add_header X-Frame-Options "SAMEORIGIN"; -
XSS防护:
nginx复制add_header X-XSS-Protection "1; mode=block"; -
内容安全策略:
nginx复制add_header Content-Security-Policy "default-src 'self'";
9. 实际部署经验分享
在多次部署Vue项目到Nginx的过程中,我总结了以下经验:
-
缓存策略:
- 开发环境禁用缓存方便调试
- 生产环境对静态资源启用长期缓存
- 使用文件哈希解决缓存更新问题
-
路径问题:
- Vue项目中避免使用绝对路径
- 设置正确的publicPath
- 测试时使用相对路径
-
性能优化:
- 开启Brotli压缩(比Gzip更高效)
- 使用HTTP/2
- 配置合理的缓存头
-
零停机部署:
- 使用符号链接切换版本
- 先上传到临时目录再切换
- 回滚机制要提前测试
-
监控报警:
- 设置Nginx错误日志监控
- 配置uptime监控
- 关键API端点健康检查
部署完成后,建议进行以下测试:
- 多路由页面刷新测试
- 静态资源加载测试
- API代理功能测试
- 移动端访问测试
- 性能压力测试(如ab, wrk)
最后提醒,每次修改Nginx配置后,一定要先测试再重启:
bash复制sudo nginx -t && sudo systemctl restart nginx