Nginx 1.24.0 部署 Vue 3 项目5个关键配置解决路由刷新404与跨域1. 环境准备与基础配置在开始之前确保你已经安装了最新版本的Nginx 1.24.0。可以通过以下命令检查版本nginx -v如果尚未安装可以从Nginx官网或华为云镜像站获取wget https://mirrors.huaweicloud.com/nginx/nginx-1.24.0.tar.gz tar -zxvf nginx-1.24.0.tar.gz cd nginx-1.24.0 ./configure --prefix/usr/local/nginx make make install安装完成后基本的Nginx配置文件结构如下/usr/local/nginx/ ├── conf/nginx.conf # 主配置文件 ├── html/ # 默认网站根目录 └── logs/ # 日志文件2. 解决Vue路由刷新404问题Vue作为单页应用(SPA)使用前端路由时直接访问非根路径会导致Nginx返回404。这是因为Nginx会尝试查找对应的物理文件而Vue的路由是虚拟的。2.1 核心配置try_files指令在Nginx配置中添加以下内容server { listen 80; server_name your-domain.com; location / { root /path/to/your/vue-project/dist; index index.html; try_files $uri $uri/ /index.html; } }关键点解析try_files会按顺序检查文件是否存在当所有检查都失败时最后回退到/index.html这样Vue Router就能接管路由控制2.2 子路径部署的特殊处理如果项目部署在子路径下如/admin需要额外配置location /admin/ { alias /path/to/your/vue-project/dist/; index index.html; try_files $uri $uri/ /admin/index.html; }同时Vue项目中需要设置对应的publicPath// vue.config.js module.exports { publicPath: process.env.NODE_ENV production ? /admin/ : / }3. 跨域问题解决方案开发和生产环境中前端与API服务往往不在同一域名下导致跨域问题。Nginx的反向代理是完美解决方案。3.1 基础代理配置location /api/ { proxy_pass http://your-api-server:8080/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 300s; }3.2 多环境API配置技巧通过Nginx变量实现环境切换# 在http块中定义变量 map $http_origin $api_server { default http://production-api; ~*localhost http://dev-api; ~*staging.yourdomain.com http://staging-api; } # 在server块中使用 location /api/ { proxy_pass $api_server; # 其他代理配置... }4. 性能优化配置4.1 静态资源缓存location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, no-transform; access_log off; }4.2 Gzip压缩gzip on; gzip_min_length 1k; gzip_comp_level 6; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript; gzip_vary on;4.3 HTTP/2支持server { listen 443 ssl http2; # SSL证书配置... }5. 安全加固配置5.1 禁止敏感文件访问location ~ /\.(ht|git|svn) { deny all; }5.2 安全头部add_header X-Frame-Options SAMEORIGIN; add_header X-XSS-Protection 1; modeblock; add_header X-Content-Type-Options nosniff; add_header Referrer-Policy no-referrer-when-downgrade; add_header Content-Security-Policy default-src self https: data: unsafe-inline unsafe-eval;5.3 限流配置limit_req_zone $binary_remote_addr zoneapi_limit:10m rate10r/s; location /api/ { limit_req zoneapi_limit burst20 nodelay; # 其他代理配置... }完整配置示例user nginx; worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; events { worker_connections 1024; } 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; keepalive_timeout 65; # 性能优化 gzip on; gzip_min_length 1k; gzip_comp_level 6; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xmlrss text/javascript; gzip_vary on; # API服务器映射 map $http_origin $api_server { default http://production-api:8080; ~*localhost http://dev-api:8080; } server { listen 80; server_name your-domain.com; # 强制HTTPS return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # 安全头部 add_header X-Frame-Options SAMEORIGIN; add_header X-XSS-Protection 1; modeblock; add_header X-Content-Type-Options nosniff; # Vue项目部署 location / { root /var/www/vue-project/dist; index index.html; try_files $uri $uri/ /index.html; } # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, no-transform; access_log off; } # API代理 location /api/ { proxy_pass $api_server; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 300s; } # 禁止访问敏感文件 location ~ /\.(ht|git|svn) { deny all; } } }常见问题排查路由刷新仍然404检查try_files配置是否正确确保Vue项目的publicPath与Nginx配置匹配查看Nginx错误日志tail -f /var/log/nginx/error.log跨域问题依旧存在确认代理路径是否正确注意结尾的/检查API服务是否允许Nginx域名的跨域请求使用curl测试代理是否工作curl -v http://your-domain.com/api/test静态资源加载失败检查文件权限chown -R nginx:nginx /path/to/your/project确认文件路径是否正确检查MIME类型是否正确定义性能问题启用Nginx状态监控stub_status on调整worker进程数worker_processes auto;优化keepalive超时keepalive_timeout 30s;