Vue 3 打包部署 Nginx 404 问题解决方案

这是Vue 3 SPA应用部署到Nginx时最常见的问题。当用户直接访问非根路径（如 /about、/user/123）时，Nginx会在服务器上查找对应的物理文件，但Vue应用是单页面应用，这些路由实际上是由前端路由控制的。

1. 问题根源

Vue 3应用打包后：

• 只有 index.html是真实存在的物理文件
• 其他路由如 /about、/contact是前端路由
• 当直接访问这些路由时，Nginx在服务器上找不到对应的 about.html文件
• 因此返回 404 错误

2. 完整解决方案

2.1 方案一：Nginx 配置（推荐）

核心思路：让Nginx对所有找不到的路径都返回 index.html，由Vue Router处理路由

server {
    listen 80;
    server_name your-domain.com;  # 你的域名
    root /usr/share/nginx/html;   # Vue打包文件所在目录
    index index.html;

    # 处理Vue路由 - 核心配置
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存优化
    location ~* .(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }

    # Gzip压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        application/atom+xml
        application/geo+json
        application/javascript
        application/x-javascript
        application/json
        application/ld+json
        application/manifest+json
        application/rdf+xml
        application/rss+xml
        application/xhtml+xml
        application/xml
        font/eot
        font/otf
        font/ttf
        image/svg+xml
        text/css
        text/javascript
        text/plain
        text/xml;
}

关键配置说明：

• try_files $uri $uri/ /index.html;：按顺序尝试查找文件

  1. 先找 $uri（请求的路径）
  2. 再找 $uri/（目录）
  3. 都找不到就返回 /index.html（由Vue处理路由）

2.2 方案二：Docker部署配置

如果你使用Docker部署，Nginx配置：

# Dockerfile
FROM nginx:alpine

# 复制打包文件
COPY dist/ /usr/share/nginx/html/

# 复制自定义Nginx配置
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# nginx.conf
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # 核心配置：处理Vue路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源优化
    location ~* .(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

2.3 方案三：Vue Router 配置检查

确保你的Vue Router配置正确：

// router/index.js
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  // 关键：使用createWebHistory，而不是createWebHashHistory
  history: createWebHistory(process.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'Home',
      component: () => import('@/views/Home.vue')
    },
    {
      path: '/about',
      name: 'About',
      component: () => import('@/views/About.vue')
    },
    {
      path: '/:pathMatch(.*)*',  // 404页面
      name: 'NotFound',
      component: () => import('@/views/NotFound.vue')
    }
  ]
})

export default router

重要：生产环境必须使用 createWebHistory，而不是 createWebHashHistory（URL带#号的那种）。

2.4 方案四：Vue 项目配置检查

检查 vite.config.js或 vue.config.js：

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/',  // 确保base路径正确
  build: {
    outDir: 'dist',
    assetsDir: 'assets'
  }
})

// vue.config.js (Vue CLI)
module.exports = {
  publicPath: '/',  // 确保publicPath正确
  outputDir: 'dist',
  assetsDir: 'assets'
}

3. 部署验证步骤

3.1 本地验证打包结果

打包前先验证：

# 打包
npm run build

# 查看dist目录结构
ls -la dist/
# 应该看到类似：
# index.html
# assets/
#   index-xxx.js
#   index-xxx.css

3.2 本地测试部署

可以使用 serve测试打包结果：

# 安装serve
npm install -g serve

# 在dist目录启动服务
serve -s dist

# 访问 http://localhost:3000
# 测试直接访问路由：http://localhost:3000/about

3.3 部署到Nginx后的验证

部署后测试：

1. 访问根路径：http://your-domain.com（应该正常）
2. 直接访问路由：http://your-domain.com/about（应该正常）
3. 刷新页面：http://your-domain.com/about（应该正常）

4. 常见问题排查

4.1 问题：配置了try_files但还是404

排查步骤：

1. 检查Nginx配置是否生效

   nginx -t  # 检查配置语法
   nginx -s reload  # 重新加载配置
   

2. 检查Nginx错误日志

   tail -f /var/log/nginx/error.log
   

3. 检查文件权限

   chmod -R 755 /usr/share/nginx/html/
   

4.2 问题：静态资源404

解决方案：确保静态资源路径正确

location /assets/ {
    alias /usr/share/nginx/html/assets/;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

4.3 问题：开发环境正常，生产环境404

原因：

• 开发环境使用webpack-dev-server，自带路由处理
• 生产环境需要Nginx配置支持

解决：按照上面的Nginx配置进行设置

5. 进阶配置

5.1 子路径部署

如果你的应用部署在子路径下（如 http://domain.com/myapp/）：

// vite.config.js
export default defineConfig({
  base: '/myapp/',
  // ...
})

server {
    listen 80;
    server_name domain.com;
    root /usr/share/nginx/html;
    
    location /myapp/ {
        alias /usr/share/nginx/html/;
        try_files $uri $uri/ /myapp/index.html;
        index index.html;
    }
}

5.2 多环境配置

# 开发环境
server {
    listen 8080;
    server_name dev.domain.com;
    # 开发环境配置
}

# 生产环境
server {
    listen 80;
    server_name domain.com;
    # 生产环境配置
}

6. 一键部署脚本

#!/bin/bash
# deploy.sh

echo "开始部署Vue应用..."

# 1. 打包
echo "打包Vue应用..."
npm run build

# 2. 备份旧版本
if [ -d "/usr/share/nginx/html" ]; then
    echo "备份旧版本..."
    tar -czf /tmp/vue-app-backup-$(date +%Y%m%d%H%M%S).tar.gz /usr/share/nginx/html
fi

# 3. 复制新版本
echo "复制新版本到Nginx目录..."
sudo cp -r dist/* /usr/share/nginx/html/

# 4. 设置权限
echo "设置文件权限..."
sudo chown -R nginx:nginx /usr/share/nginx/html/
sudo chmod -R 755 /usr/share/nginx/html/

# 5. 重启Nginx
echo "重启Nginx服务..."
sudo nginx -t && sudo nginx -s reload

echo "部署完成！"

7. 总结

Vue 3 SPA部署404问题的核心解决方案：

1. Nginx配置：try_files $uri $uri/ /index.html;
2. Vue Router配置：使用 createWebHistory
3. 打包配置：确保 base路径正确
4. 文件权限：确保Nginx有读取权限

按照上述配置部署后，直接访问任何路由都能正常工作。

**