Nuxt静态站点执行npm run generate后部署时图片等资源无法加载问题

排查步骤 #

1. 核对基础路径配置 #

你遇到的差异表现（Netlify正常、GitHub Pages/Apache异常）大概率是部署路径问题导致：Netlify默认将站点部署在域名根路径，而GitHub Pages默认部署在/仓库名/子路径，自定义Apache部署也可能放在子路径下，资源默认按根路径请求就会404。
根据你使用的Nuxt版本添加对应配置：

• Nuxt2：在nuxt.config.js中添加

  export default {
    target: 'static',
    router: {
      base: '/你的部署子路径/' // GitHub Pages填仓库名，前后都加斜杠，根路径就填'/'
    }
  }
  

• Nuxt3：在nuxt.config.ts中添加

  export default defineNuxtConfig({
    app: {
      baseURL: '/你的部署子路径/' // 规则同上
    }
  })
  

2. 修正静态资源引用规则 #

• 放在public目录的静态资源，引用时不要加~前缀，直接写相对于根路径的地址，比如图片存为public/img/demo.jpg，引用写法为<img src="/img/demo.jpg" />，配置base后构建会自动补全路径前缀
• 放在assets目录的资源才需要用~/assets/xxx的写法，该路径会被构建工具处理，生成带哈希值的生产地址

3. 补充generate适配配置 #

在配置文件中添加fallback配置，适配静态站点的路由回退逻辑：

• Nuxt2添加配置：

  export default {
    generate: {
      fallback: '404.html'
    }
  }
  

• Nuxt3默认已生成对应回退文件，无需额外配置

4. 本地验证构建产物 #

不要直接打开dist目录下的HTML文件验证，file协议会存在路径和跨域限制。全局安装serve工具后执行serve dist，启动本地静态服务访问，确认资源加载正常后再交付部署。

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