Nuxt Image v2

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

🎯 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 会在类型层级强制要求：

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)。

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)：

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({
+   getImage(src, { modifiers }) { ... }
+ })

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

移除的提供者

废弃的 layer0 和 edgio 提供者已被移除。

URL 格式器

如果你有使用过 joinWith 进行参数格式化的自定义提供者，请改用带有 createOperationsGenerator 的 formatter 函数。详情请参见迁移指南。

屏幕尺寸

默认屏幕尺寸调整为匹配 Tailwind CSS，移除了 xs (320px) 和 xxl (2560px)。关于如何恢复这些尺寸，请见迁移指南。

移除的工具

删除了若干未使用的运行时工具。如果你直接引入了内部工具，请检查它们是否仍然存在。

✅ 升级

请查看我们详尽的迁移指南，获取一步步的升级说明。

快速更新命令：

npm install @nuxt/image@latest

大多数应用无需更改代码即可升级。如果有自定义提供者，需要更新为使用 defineProvider —— 示例请参考迁移指南。

🐛 Bug 修复

本版本修复了若干问题：

• 预加载链接：修复多密度预加载时单一尺寸问题 (#1851)
• 跨域属性：修正预加载链接的 crossorigin 属性 (#1836)
• 提供者格式：AWS Amplify 和 Vercel 现在有正确的格式允许列表 (#1996)
• Hygraph：防止出错的图片 URL (#1999)
• 预设尺寸：修复 sizes 未定义时预设尺寸未应用的问题 (#1919)
• Cloudflare：无操作时不添加 baseURL (#1790)
• IPX：提供外部 baseURL 时始终使用 IPX 提供者 (#1800)

🙏 感谢

感谢所有为此次发布贡献力量的开发者！包括数十位社区成员，他们在功能开发、修复问题、文档完善和反馈方面做出了贡献。

📚 资源

• 文档
• GitHub 仓库
• 迁移指南

👉 完整发布说明

祝你优化愉快！🖼️✨