Lzh on GitHub

配置

Nuxt Image 模块具有合理的默认配置。

要配置图像模块并自定义其行为，您可以在 nuxt.config 中使用 image 属性：

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    // Options
  }
})

inject

默认情况下，Nuxt Image v1 采用可组合的方法。如果您不使用组件，则不会向您的包中添加额外的代码。但如果您希望全局初始化一个 $img 辅助函数，使其在您的整个应用程序中可用，您可以这样做。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    inject: true
  }
})

quality

生成的图像的质量。

您也可以通过使用 quality prop 在组件级别覆盖此选项。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    quality: 80
  }
})

format

默认值: ['webp']

您可以使用此选项配置 <NuxtPicture> 使用的图像的默认格式。可用格式有 webp、avif、jpeg、jpg、png 和 gif。格式的顺序很重要，因为浏览器支持的第一种格式将被使用。您可以传递多个值，例如 ['avif', 'webp']。

您也可以通过使用 format prop 在组件级别覆盖此选项。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    format: ['webp']
  }
})

screens

预定义的屏幕尺寸列表。

这些尺寸将用于生成图像的调整大小和优化版本（例如，使用 sizes 修改器）。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    // The screen sizes predefined by `@nuxt/image`:
    screens: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      xxl: 1536,
      '2xl': 1536
    }
  }
})
我们与 Tailwind CSS 共享相同的命名和尺寸，并增加了 xs 和 xxl（为了向后兼容）。

domains

要启用外部网站的图像优化，请指定允许优化的域名。此选项将用于检测远程图像是否应该被优化。这是为了确保外部 URL 不会被滥用。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    domains: ['nuxtjs.org']
  }
})
防止恶意滥用 该配置是一种安全策略，避免攻击者通过构造非法图片 URL 消耗服务器资源（例如 DDoS 攻击）。仅白名单内的域名可触发优化。

presets

预设是您的项目预定义配置的集合。预设将帮助您统一项目中的所有图像。

export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        modifiers: {
          format: 'jpg',
          width: 50,
          height: 50
        }
      }
    }
  }
})

providers

为了创建和使用 自定义提供商，您需要使用 providers 选项并定义您的自定义提供商。

export default defineNuxtConfig({
  image: {
    providers: {
      random: {
        provider: '~/providers/random',
        options: {}
      }
    }
  }
})

provider

默认值：ipx（如果与静态 nitro 预设一起使用，例如当您运行 nuxt generate 时，则为 ipxStatic）

默认引擎 ipx 适用于本地图片（存储在 public/ 目录），无需外部服务，自动优化图片格式、尺寸。

我们可以指定在组件中未指定或调用 $img 时要使用的默认提供商。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    provider: 'twicpics',
    twicpics: {
      baseURL: 'https://nuxt-demo.twic.pics'
    }
  }
})
该配置项用于指定底层的图像优化与转换服务，它决定了图片的优化逻辑、处理方式和性能表现。

不同 Provider 的适用场景对比：
Provider适用场景优势配置示例
ipx (默认)纯静态站点、本地图片优化零配置、无外部依赖无需额外配置
cloudinary需高级编辑（缩略图/滤镜/叠加层）支持 120+ 转换参数，AI 智能裁剪baseURL + modifiers 参数
imgix大型媒体库、响应式多尺寸适配实时格式转换、自动 DPR 适配sizes="sm:100vw lg:50vw"
自定义 Provider私有云/特殊图像服务完全自主控制优化逻辑需实现 createProvider 接口

modifiers

您可以为所选提供商设置默认修饰符。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    provider: 'cloudinary',
    cloudinary: {
      baseURL: 'https://res.cloudinary.com/<company>/image/fetch',
      modifiers: {
        effect: 'sharpen:100',
        quality: 'auto:best'
      }
    }
  }
})

densities

默认值: [1, 2]

指定一个值以处理 devicePixelRatio > 1 的设备（这些是视网膜显示器和其他设备）。您必须指定要适应图像的 devicePixelRatio 值。

您可以在 MDN 上 阅读更多关于 devicePixelRatio 的信息。

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    densities: [1, 2, 3]
  }
})

dir

默认值: public

此选项允许您在使用 ipx 或 ipxStatic 提供商时指定源图像的位置。

例如，您可能希望源图像位于 assets/images 目录而不是默认的 public 目录，这样源图像就不会被复制到 dist 并部署：

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    dir: 'assets/images'
  }
})

注意:

  • 对于 ipxStatic 提供商，如果图像在生成期间未被抓取（无法访问的模态、页面或动态运行时大小），将 dir 从 public 更改会导致 404 错误。
  • 对于 ipx 提供商，请确保也部署自定义的 dir。
  • 对于某些提供商（如 vercel），不支持将 public/ 以外的目录用于资产，因为调整大小发生在运行时（而不是构建/生成时），并且源是从 public/ 目录（部署 URL）获取的。

alias

此选项允许您为 src 指定别名。

当使用默认的 ipx 提供商时，URL 别名在服务器端被缩短。

这对于优化外部 URL 而不将其包含在 HTML 中特别有用。

当使用其他提供商时，别名在运行时解析并包含在 HTML 中。（仅简化了用法）

示例:

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    domains: [
      'images.unsplash.com'
    ],
    alias: {
      unsplash: 'https://images.unsplash.com'
    }
  }
})

使用别名 之前:

<NuxtImg src="https://images.unsplash.com/<id>" />

生成：

<img src="/_ipx/https://images.unsplash.com/<id>">

使用别名 之后：

<NuxtImg src="/unsplash/<id>" />

生成：

<img src="/_ipx/unsplash/<id>">

用法和输出都简化了！