Vue3+Vite项目npm run build后Nginx部署资源加载失败问题排查

一、问题根源 #

从截图的404错误能看出来，核心就是资源请求路径和实际部署的文件路径对不上，常见原因有两个：

1. Vite默认用绝对根路径（/）构建资源，但你的Nginx部署的站点并非服务器根目录；
2. Nginx的站点根目录或location配置错了，导致没法正确找到构建后的静态文件。

二、具体解决步骤 #

1. 调整Vite项目的base配置 #

如果你的项目部署在Nginx的子路径下（比如http://xxx.com/my-app/），或者Nginx指向的目录不是dist的上级目录，先改Vite的base路径：

• 打开项目根目录的vite.config.js（或vite.config.ts），加上base配置：

  export default defineConfig({
    base: './', // 改成相对路径，适配任意部署路径；如果是固定子路径，比如'/my-app/'，直接写这个路径也行
    // 其他原有配置...
  })
  

• 改完重新跑npm run build生成新的dist目录，这时候index.html里引用资源的路径会变成相对路径（比如./assets/js/xxx.js），而不是原来的绝对路径/assets/js/xxx.js。

2. 修正Nginx配置 #

确保Nginx的server配置能正确指向dist目录，给个示例配置：

server {
    listen 80;
    server_name 你的域名或IP地址;

    # 指向构建后的dist目录绝对路径，比如你的dist在/home/user/my-project/dist就写这个
    root /usr/share/nginx/html/dist; 
    index index.html;

    # 处理SPA路由，避免刷新页面404（单页应用必须加）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存（可选，优化加载速度）
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico)$ {
        expires 30d;
        add_header Cache-Control "public, max-age=2592000";
    }
}

• 重点：root必须是dist目录的绝对路径，不能写错；
• 如果部署在子路径（比如http://xxx.com/my-app/），得同步调整base和Nginx配置：
  • Vite的base设为/my-app/；
  • Nginx配置改成：

    location /my-app/ {
        root /usr/share/nginx/html; # 这里指向dist的上级目录，因为/my-app/对应dist文件夹
        try_files $uri $uri/ /my-app/index.html;
    }
    

3. 验证效果 #

• 重启Nginx：执行nginx -s reload；
• 清空浏览器缓存后重新访问页面，检查资源是否正常加载。

内容的提问来源于stack exchange，提问作者zenereyes