Nginx 1.24 部署 Vue 3 项目：5个关键配置解决路由刷新404与跨域

Nginx 1.24 部署 Vue 3 项目5个关键配置解决路由刷新404与跨域1. 生产环境部署的核心挑战现代前端项目部署时往往会遇到两个顽固问题History模式路由刷新404和API请求跨域限制。这两个问题在开发环境可能被Vue CLI或Vite的dev server巧妙掩盖但一旦部署到生产环境就会暴露无遗。以Vue 3项目为例当使用vue-router的history模式时直接访问/about这样的子路由会出现404错误。这是因为Nginx默认会把这个路径当作实际文件路径去查找而我们的SPA应用其实只有唯一的入口文件index.html。跨域问题则更为常见。当前端应用运行在https://example.com而API服务在https://api.example.com时浏览器出于安全考虑会阻止这种跨域请求。虽然开发时可以通过代理解决但生产环境需要更严谨的配置。2. 基础Nginx配置模板先看一个最简化的生产环境配置模板server { listen 80; server_name yourdomain.com; root /var/www/vue-project/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }这个配置已经解决了SPA路由的基础问题但还远远不够完善。以下是各关键指令的作用指令作用必需性try_files按顺序检查文件是否存在解决路由问题的核心root指定项目静态文件根目录必须准确指向打包目录index默认入口文件通常保持默认即可3. 解决History模式路由的进阶方案上述基础配置在简单场景下可行但在企业级部署中还需要考虑以下情况3.1 带公共路径的部署当项目不是部署在域名根路径时如https://example.com/subpath/需要同步修改Vue和Nginx配置Vue配置vite.config.jsexport default defineConfig({ base: /subpath/, // 其他配置... })Nginx对应调整location /subpath/ { alias /var/www/vue-project/dist/; try_files $uri $uri/ /subpath/index.html; }关键区别使用alias而非root时路径匹配会更精确。注意alias末尾的/必须与location的/匹配3.2 静态资源缓存策略合理配置缓存可以显著提升性能location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, no-transform; access_log off; }这个配置会对静态资源设置1年缓存同时禁用日志记录减少IO压力。实际项目中可能需要根据版本控制策略调整缓存时间。4. 跨域代理的完整解决方案开发环境我们常用proxyTable生产环境则需要Nginx直接处理。以下是安全可靠的代理配置location /api/ { proxy_pass http://backend-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; # 安全相关头部 add_header X-Content-Type-Options nosniff; add_header X-Frame-Options SAMEORIGIN; }关键参数说明proxy_pass末尾的/确保路径完全转发三个超时设置避免长时间请求被中断X-Forwarded-For保留原始客户端IP安全头部防止点击劫持和MIME类型嗅探5. 性能优化与安全加固5.1 Gzip压缩配置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/xmlrss image/svgxml; gzip_min_length 1k;5.2 安全防护措施# 禁止敏感文件访问 location ~* (\.env|\.git|\.htaccess) { deny all; return 404; } # 防止点击劫持 add_header X-Frame-Options SAMEORIGIN always; add_header X-XSS-Protection 1; modeblock always; add_header X-Content-Type-Options nosniff always; # CSP策略根据项目调整 add_header Content-Security-Policy default-src self; script-src self unsafe-inline cdn.example.com; style-src self unsafe-inline; img-src self data:; always;6. 完整配置示例以下是一个整合所有要点的生产级配置worker_processes auto; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; # 基础优化参数 sendfile on; tcp_nopush on; keepalive_timeout 65; # 日志格式 log_format main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $http_x_forwarded_for; # Gzip配置 gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svgxml; server { listen 80; server_name example.com; # 静态资源 root /var/www/vue-project/dist; index index.html; # 主路由处理 location / { try_files $uri $uri/ /index.html; # 安全头部 add_header X-Frame-Options SAMEORIGIN; add_header X-Content-Type-Options nosniff; } # API代理 location /api/ { proxy_pass http://backend:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 静态资源缓存 location ~* \.(?:js|css|png|jpg|svg)$ { expires 1y; access_log off; add_header Cache-Control public; } # 禁止访问隐藏文件 location ~ /\. { deny all; } # 错误页面 error_page 500 502 503 504 /50x.html; location /50x.html { root /usr/share/nginx/html; } } }7. 部署后的验证清单路由测试访问所有定义的路由确保不出现404测试直接输入URL和页面内跳转API测试检查跨域请求是否正常验证POST等非简单请求性能检查使用Chrome DevTools查看静态资源缓存头确认Gzip压缩生效安全扫描使用securityheaders.com检查安全头测试敏感文件访问限制实际部署中遇到过最棘手的情况是CDN缓存了错误的配置导致修改不生效。这时需要特别注意缓存清除机制或者采用版本化路径方案。