图片

Nuxt 提供了 <NuxtImg> 和 <NuxtPicture> 两个组件，自动优化图片尺寸、格式和加载行为。

NuxtImg

优化图片的 <img> 组件，支持自动裁剪、格式转换、懒加载等。

<template>
  <!-- 基本用法 -->
  <NuxtImg src="/images/photo.jpg" alt="Photo" />

  <!-- 指定宽高（自动裁剪） -->
  <NuxtImg src="/photo.jpg" width="400" height="300" />

  <!-- 格式转换 -->
  <NuxtImg src="/photo.jpg" format="webp" quality="80" />

  <!-- 懒加载 -->
  <NuxtImg src="/photo.jpg" loading="lazy" />

  <!-- 占位符（低分辨率预览） -->
  <NuxtImg src="/photo.jpg" placeholder />

  <!-- 响应式 -->
  <NuxtImg
    src="/photo.jpg"
    width="400"
    height="300"
    densities="x1 x2"
    sizes="sm:100vw md:50vw lg:400px"
  />
</template>

Props

Prop	类型	默认值	说明
src	string	-	图片路径（必填）
width	number | string	-	宽度
height	number | string	-	高度
format	string	-	格式：webp、avif、jpg、png
quality	number	-	质量 0-100
fit	string	-	cover、contain、fill、inside、outside
loading	string	-	lazy 或 eager
placeholder	boolean | string	false	显示占位符
densities	string	-	设备像素密度（如 x1 x2）
sizes	string	-	响应式尺寸
modifiers	object	-	自定义修饰符
preset	string	-	预设名称

图片优化原理

原始图片 → NuxtImg → 自动处理：
1. 根据宽高裁剪/缩放
2. 转换格式（webp/avif 体积更小）
3. 生成 srcset 适配不同设备
4. CDN 缓存优化后的图片

配置图片域名

使用外部图片时，需要在 nuxt.config.ts 中配置允许的域名：

export default defineNuxtConfig({
  image: {
    domains: ['images.unsplash.com', 'cdn.example.com'],
    // 使用 IPX 作为图片处理服务
    provider: 'ipx',
  },
})

图片预设

定义可复用的图片配置：

export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        width: 100,
        height: 100,
        format: 'webp',
        fit: 'cover',
      },
      hero: {
        width: 1920,
        height: 1080,
        format: 'webp',
        quality: 80,
      },
    },
  },
})

<template>
  <NuxtImg src="/user.jpg" preset="avatar" />
  <NuxtImg src="/banner.jpg" preset="hero" />
</template>

---

NuxtPicture

自动生成多格式 <picture> 组件，浏览器会选择最优格式加载。

<template>
  <!-- 自动生成 webp + 原始格式 -->
  <NuxtPicture src="/photo.jpg" width="400" height="300" />

  <!-- 指定格式 -->
  <NuxtPicture src="/photo.jpg" format="avif" />
</template>

NuxtPicture vs NuxtImg

特性	NuxtImg	NuxtPicture
输出元素	<img>	<picture> + <source>
多格式	❌ 单一格式	✅ 自动生成多格式
浏览器适配	使用指定格式	浏览器自选最优格式
代码体积	更轻量	稍重
推荐场景	简单场景、图标	需要多格式优化的大图

选择建议

需要图片优化？
├── 是 → 图片类型？
│   ├── 照片/大图 → NuxtPicture（多格式 + 响应式）
│   ├── 图标/小图 → NuxtImg（轻量 + 格式转换）
│   └── 不确定 → NuxtPicture（更优兼容性）
└── 否 → 普通 <img>

INFO

️ 使用 NuxtImg/NuxtPicture 需要安装 @nuxt/image 模块：npx nuxi module add image