Vue 项目部署后为何出现 404 错误？

Vue 项目部署后出现 404 错误，主要与路由模式和服务器配置相关，通常是单页应用（SPA）特性导致的。常见原因和解决方案如下：

一、 根本原因

1. SPA 路由机制问题：
   • Vue 应用是单页应用（SPA），最终部署时通常只有一个入口文件（如 index.html）。
   • 浏览器直接访问子路由（如 example.com/about）时，服务器会尝试在根目录寻找 /about 对应的物理文件，但该文件不存在，从而返回 404。
2. 路由模式未适配服务器：
   • Vue Router 默认使用 history 模式（基于浏览器的 pushState API），需服务器配置支持。若未配置，非根路径的请求会视为静态资源请求，导致 404。

二、 常见解决方案（针对不同服务器）

1. 配置后端服务器路由重定向

无论请求路径是什么，均返回 index.html（Vue 入口文件），由前端 Router 接管路由解析。

• Nginx 配置:

  location / {
    try_files $uri $uri/ /index.html;   # 当资源不存在时回退到 index.html
  }
  

• Apache 配置（需开启 mod_rewrite）:

  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
  

• Node.js（Express）配置（使用 middleware connect-history-api-fallback）：

  const history = require('connect-history-api-fallback');
  app.use(history());  // 需在静态资源中间件之前添加
  

2. 静态资源路径问题

若项目未部署到域名根路径（例如 /my-app），需在 Vue 项目中配置 publicPath：

• 修改 vue.config.js:

  module.exports = {
    publicPath: process.env.NODE_ENV === 'production' ? '/my-app/' : '/'
  };
  

  确保服务器能正确访问 /my-app/ 路径下的资源文件（JS、CSS）。

3. 部署缺失文件或缓存问题

• 确保完整上传打包文件：
  执行 npm run build 后，将生成的 dist/ 目录内容完整上传到服务器（不应遗漏 index.html）。
• 清除浏览器缓存：旧缓存可能干扰新资源的加载（尤其涉及静态文件命名更新）。

三、验证步骤

1. 直接访问域名根路径（如 example.com）是否正常显示。
2. 刷新子路由页面（如 example.com/about），若仍有 404 则表明路由重定向未生效。

注意：若仍使用 hash 模式（路由带 #），由于URL 变更不会触发服务器请求，通常不会出现此问题。