Release· November 5, 2025

Nuxt Image v2

Nuxt Image v2 正式发布 —— 完全支持 TypeScript、IPX v3 以及全新提供者！

Daniel Roe

@danielroe.dev

我们很高兴地宣布 Nuxt Image v2！🎉 此版本重点提升了 TypeScript 支持、性能以及开发者体验。

Nuxt Image v2 兼容 Nuxt 3.1 及以上版本。如果你当前是 Nuxt 3.0.x 版本，需要先升级到至少 3.1。

🎯 TypeScript 支持

v2 最大的改进是模块全局的 TypeScript 支持 (#1802)。

带类型的组合式函数

$img 助手和 useImage() 组合式函数拥有完整的类型推断 (#1844)：

const img = useImage()

// 修饰符完全自动补全
const url = img('/image.jpg', { 
  width: 300,
  height: 200,
  fit: 'cover' // TypeScript 知道有效的值！
})

类型安全的配置

模块选项现在完全支持类型。例如，对需要 baseURL 的提供者，nuxt.config.ts 会在类型层级强制要求：

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    provider: 'bunny',
    bunny: {
      baseURL: '...' // 缺失会产生 TypeScript 错误！
    }
  }
})

带类型的提供者

最后，如果你使用自定义图片提供者，建议使用新的 defineProvider 来实现类型安全配置：

// 之前 (v1)
export const getImage = (src, { modifiers, baseURL }) => {
  // ...
  return { url }
}

// 现在 (v2)
import { defineProvider } from '@nuxt/image/runtime'

export default defineProvider({
  getImage(src, { modifiers, baseURL }) {
    // 修饰符拥有完整类型
    // ...
    return { url }
  }
})

🚀 IPX v3

我们已升级至 IPX v3 (#1799)，带来更高性能以及更好的 sharp 二进制处理。升级支持自动检测适合部署架构的 sharp 二进制。

🔌 服务器端工具

现在你可以直接在 Nitro 服务器端点中使用图片助手 (#1473)。

server/api/og-image.ts

export default defineEventHandler((event) => {
  const img = useImage()
  
  return {
    url: img('/hero.jpg', { 
      width: 1200, 
      height: 630,
      fit: 'cover' 
    })
  }
})

🎨 组件改进

模板引用

<NuxtImg> 现通过模板引用暴露底层 <img> 元素：

<script setup>
const img = useTemplateRef('img')

onMounted(() => {
  // 直接访问原生 img 元素
  console.log(img.value.imgEl)
})
</script>

<template>
  <NuxtImg ref="img" src="/image.jpg" />
</template>

类型化插槽

<NuxtImg> 和 <NuxtPicture> 均提供了类型化的默认插槽。

<template>
  <NuxtImg src="/image.jpg" custom>
    <template #default="{ imgAttrs, isLoaded, src }">
      <img v-bind="imgAttrs" :src="src">
      <span v-if="!isLoaded">加载中...</span>
    </template>
  </NuxtImg>
</template>

插槽参数说明：

imgAttrs - 所有计算后的图片属性（sizes、srcset 等）
isLoaded - 占位符是否已加载
src - 计算得到的图片源 URL

🌐 新提供者

Shopify

现在可以配置 Shopify 提供者 (#1890)：

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    provider: 'shopify',
    shopify: {
      baseURL: 'https://your-store.myshopify.com'
    }
  }
})

GitHub

此提供者支持注入 GitHub 头像及用户内容 (#1990)：

<!-- 宽高都设置 -->
<NuxtImg provider="github" src="nuxt" height="50" width="50" />

<!-- 仅设置宽度 -->
<NuxtImg provider="github" src="unjs" width="512" />

<!-- 默认尺寸 -->
<NuxtImg provider="github" src="npm" />

⚡ 性能

我们做了多项优化以减少包体积并提升运行时性能：

更好的 URL 编码 (#1813) — 切换到 URLSearchParams，更可靠地处理参数
精简运行时工具 (#1816) — 移除未使用代码并简化实现
优化屏幕尺寸 (#1931) — 默认断点与 Tailwind CSS 对齐

🎯 更佳的层支持

Nuxt Image 现在支持 Nuxt 层中的自定义图片目录 (#1880)，更方便模块化项目中组织图片。

⚠️ 重大变更

提供者 API

最大变更是提供者定义方式。所有提供者现在使用默认导出并配合 defineProvider：

- export const getImage = (src, { modifiers }) => { ... }
+ export default defineProvider({
+   name: 'my-provider',
+   getImage(src, { modifiers }) { ... }
+ })

如果你维护自定义提供者，需要更新代码。但回报是完整的 TypeScript 支持！