---
title: "Nuxt Image v2"
description: "Nuxt Image v2 已发布 - 具备完整的 TypeScript 支持、IPX v3 和新的提供者！"
canonical_url: "https://nuxt.zhcndoc.com/blog/nuxt-image-v2"
---
# Nuxt Image v2

> Nuxt Image v2 已发布 - 具备完整的 TypeScript 支持、IPX v3 和新的提供者！

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

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

## 🎯 TypeScript 支持

v2 最大的改进是模块全局的 TypeScript 支持 ([#1802](https://github.com/nuxt/image/pull/1802))。

### 带类型的组合式函数

`$img` 助手和 `useImage()` 组合式函数拥有完整的类型推断 ([#1844](https://github.com/nuxt/image/pull/1844))：

```ts
const img = useImage()

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

### 类型安全的配置

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

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

### 带类型的提供者

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

```ts
// 之前 (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](https://github.com/nuxt/image/pull/1799))，带来更高性能以及更好的 `sharp` 二进制处理。升级支持自动检测适合部署架构的 `sharp` 二进制。

## 🔌 服务器端工具

现在你可以直接在 Nitro 服务器端点中使用图片助手 ([#1473](https://github.com/nuxt/image/pull/1473))。

```ts [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>` 元素：

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

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

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

### 类型化插槽

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

```vue
<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](https://github.com/nuxt/image/pull/1890))：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    provider: 'shopify',
    shopify: {
      baseURL: 'https://your-store.myshopify.com'
    }
  }
})
```

### GitHub

此提供者支持注入 GitHub 头像及用户内容 ([#1990](https://github.com/nuxt/image/pull/1990))：

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

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

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

## ⚡ 性能

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

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

## 🎯 更佳的层支持

Nuxt Image 现在支持 Nuxt 层中的自定义图片目录 ([#1880](https://github.com/nuxt/image/pull/1880))，更方便模块化项目中组织图片。

## ⚠️ 重大变更

### 提供者 API

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

```diff
- export const getImage = (src, { modifiers }) => { ... }
+ export default defineProvider({
+   getImage(src, { modifiers }) { ... }
+ })
```

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

### 移除的提供者

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

### URL 格式器

如果你有使用过 `joinWith` 进行参数格式化的自定义提供者，请改用带有 `createOperationsGenerator` 的 `formatter` 函数。详情请参见[迁移指南](https://image.nuxt.com/get-started/migration#url-formatter-changes)。

### 屏幕尺寸

默认屏幕尺寸调整为匹配 Tailwind CSS，移除了 `xs` (320px) 和 `xxl` (2560px)。关于如何恢复这些尺寸，请见[迁移指南](https://image.nuxt.com/get-started/migration#screen-size-changes)。

### 移除的工具

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

## ✅ 升级

请查看我们详尽的[迁移指南](https://image.nuxt.com/get-started/migration)，获取一步步的升级说明。

快速更新命令：

```bash [Terminal]
npm install @nuxt/image@latest
```

大多数应用无需更改代码即可升级。如果有自定义提供者，需要更新为使用 `defineProvider` —— 示例请参考[迁移指南](https://image.nuxt.com/get-started/migration#custom-provider-updates)。

## 🐛 Bug 修复

本版本修复了若干问题：

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

## 🙏 感谢

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

## 📚 资源

- [文档](https://image.nuxt.com)
- [GitHub 仓库](https://github.com/nuxt/image)
- [迁移指南](https://image.nuxt.com/get-started/migration)

## 👉 完整发布说明

::read-more{icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/image/releases/tag/v2.0.0"}
阅读 Nuxt Image `v2.0.0` 的完整发布说明。
::

祝你优化愉快！🖼️✨


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.