NuxtImage 404 错误排查与正确配置指南-js教程-PHP中文网

NuxtImage 404 错误排查与正确配置指南

NuxtImage 默认从 public/ 目录查找图片，若图片实际位于 assets/img/ 下，需在 nuxt.config.ts 中显式配置 image.dir，否则会因路径解析失败导致 IPX 返回 404。

nuxtimage 默认从 `public/` 目录查找图片，若图片实际位于 `assets/img/` 下，需在 `nuxt.config.ts` 中显式配置 `image.dir`，否则会因路径解析失败导致 ipx 返回 404。

在 Nuxt 3 项目中使用组件时，遇到 404 (IPX_FILE_NOT_FOUND) 是常见问题，根本原因在于 Nuxt Image（基于 IPX）的默认静态资源解析路径与实际文件位置不匹配。

默认情况下，Nuxt Image 将 src 属性视为相对于 public/ 目录的路径。例如：

<nuxtimg src="/my-image.jpg"></nuxtimg>

会尝试读取 public/my-image.jpg，并经由 IPX 处理为 /_ipx/_/my-image.jpg。但如果你的图片实际存放在 assets/img/my-image.jpg（即属于构建时被 Webpack/Vite 处理的源资产），则直接使用该路径（如 _nuxt/assets/img/...）是无效的——因为 assets/ 下的文件不会被直接复制到输出目录，且 _nuxt/ 是构建产物路径，不应在源码中硬编码引用。

✅ 正确做法是：

在 nuxt.config.ts 中声明图片源目录：

export default defineNuxtConfig({
  image: {
    dir: 'assets/img' // 告知 Nuxt Image：从此目录下解析相对路径
  }
})

在模板中使用相对于该目录的路径（不带前导 / 或带 / 均可，推荐简洁写法）：

<!-- ✅ 推荐：src 为 assets/img/ 下的相对路径 -->
<nuxtimg src="my-image.jpg"></nuxtimg><!-- ✅ 也可写作（等效） --><nuxtimg src="/my-image.jpg"></nuxtimg>

⚠️ 注意事项：

不要使用 src="_nuxt/assets/img/..." 或 src="/_nuxt/..." —— 这些是构建输出路径，非源码路径，且 Nuxt Image 不支持解析此类内部构建路径；
assets/ 中的图片会被 Vite/Webpack 加载并哈希处理，而 Nuxt Image 的 dir 配置让其能直接访问原始文件（开发时）或构建后拷贝的资源（生产时，需确保 assets/img/ 内容被正确纳入静态资源处理流程）；
若你希望图片走构建优化（如自动压缩、格式转换），建议将图片放在 assets/img/ 并配合 dir 配置；若只需简单托管，可移至 public/img/，此时无需额外配置 dir，直接用即可。

总结：NuxtImage 的 404 本质是路径映射错位。通过 image.dir 显式指定源资产根目录，并统一使用该目录下的相对路径调用组件，即可彻底解决该问题。