Netlify部署Nuxt3应用成功但图片无法加载如何解决

故障现象 #

部署完成后站点可正常访问，但所有图片资源无法加载，控制台对应图片请求返回404状态：

当前项目图片存放目录结构如下：

核心原因 #

该问题绝大多数由两类配置错误导致：

• 图片引用路径不符合Nuxt3静态资源处理规则，写死的相对路径在构建后无法匹配重命名后的资源文件
• Netlify平台缺少Nuxt3专属的部署重写规则，静态资源请求被错误拦截转发

修复步骤 #

• 修正图片引用逻辑
  Nuxt3有两类静态资源存放目录，引用规则完全不同，不能混用：
  • 若图片存放在assets目录：资源会经过Vite构建处理（自动加hash、压缩），引用时必须用~开头的别名路径，禁止写相对路径，示例：

    <!-- 正确写法 -->
    <img src="~/assets/images/your-image.png" alt="示例图">
    <!-- 错误写法，构建后路径会失效 -->
    <img src="./assets/images/your-image.png" alt="示例图">
    

  • 若不想让构建工具处理图片，直接把图片文件夹移动到项目根目录的public文件夹下，引用时直接写根路径即可，这种方式路径容错率最高，适合固定静态资源：

    <img src="/images/your-image.png" alt="示例图">
    

• 新增Netlify适配配置
  在项目根目录新建netlify.toml配置文件，写入Nuxt3官方推荐的构建与转发规则，避免静态资源被路由规则拦截：

  [build]
    command = "npm run build"
    publish = ".output/public"
  
  [[redirects]]
    from = "/*"
    to = "/.netlify/functions/__nuxt"
    status = 200
  

• 核对Nuxt基础配置
  打开项目根目录的nuxt.config.ts，如果没有子路径部署需求，不要随意修改app.baseURL字段，保持默认值'/'即可；如果确实需要部署到子目录，要确保baseURL末尾携带斜杠，例如'/your-sub-path/'。
• 重新部署验证
  将修改后的代码推送到关联Netlify的Git仓库，等待自动构建部署完成后，清空浏览器缓存访问站点即可看到图片正常加载。

内容的提问来源于stack exchange，提问作者Amine EL GHAZALI