Nuxt `<NuxtImg>` 组件实战指南：用一行标签完成图片自动优化

2026-09-07 19:28:44作者：齐冠琰

<NuxtImg> 是 Nuxt 生态中面向图片优化的开箱即用组件，可视为原生 <img> 标签的“无缝替换方案”（drop-in replacement）。在 Nuxt 项目中启用 @nuxt/image 官方模块后，开发者可以直接用 <NuxtImg> 接管本地与远程图片的尺寸缩放、格式转换与响应式尺寸生成，无需自行对接 CDN 或编写优化逻辑。阅读完本指南，你将掌握 <NuxtImg> 的安装启用方式、核心能力、进阶属性（如响应式 sizes、原生懒加载、预加载优先级）以及在真实项目中的性能优化用法。

`<NuxtImg>` 是什么

Nuxt 官方文档对 <NuxtImg> 的定义十分明确——它是原生 <img> 标签的直接替代组件。与手写 <img> 相比，它带来以下增强能力：

使用内置 provider（提供方）优化本地与远程图片
将 src 转换为 provider 优化后的 URL
根据 width 与 height 自动缩放图片尺寸
在提供 sizes 选项时自动生成响应式尺寸
支持原生懒加载以及其他全部 <img> 原生属性

需要指出的是，<NuxtImg> 组件本体并非由当前 Nuxt 仓库（packages/ 下仅包含 Nuxt 框架核心）直接维护，而是位于独立的 @nuxt/image（Nuxt Image）模块中；当前仓库提供的 .vue stub 与文档负责说明其组件契约与使用方式。与之配套的还有面向 <picture> 标签的 <NuxtPicture> 组件，二者的使用方式几乎一致，<NuxtPicture> 额外支持在可用时优先输出 webp 等现代格式。

安装与启用（Setup）

要在应用中使用 <NuxtImg>，需要先安装并启用 Nuxt Image 模块。当前仓库的多个官方文档统一推荐使用 Nuxt 自带的模块管理命令完成一键安装：

npx nuxt module add image

该命令会自动将 @nuxt/image 写入 package.json 依赖，并把模块注册进 nuxt.config.ts 的 modules 数组。参考 Nuxt 官方对模块系统的说明（见 Nuxt Modules 概念文档），模块也可以在配置文件中手动声明：

export default defineNuxtConfig({
  modules: [
    // 使用包名注册（推荐用法）
    '@nuxt/image',
  ],
})

完成安装后，组件会以全局自动导入的方式可用，模板中直接书写 <NuxtImg> 即可，无需手动 import。

基本用法

<NuxtImg> 直接输出一个原生 img 标签（外层不会包裹任何多余元素），因此它的用法与 <img> 标签几乎完全一致：

<NuxtImg src="/nuxt-icon.png" />

渲染结果等价于：

<img src="/nuxt-icon.png" />

正因为输出的是标准原生元素、无额外 wrapper，开发者可以将它放心地放入现有的布局与样式体系，无需担心破坏 CSS 上下文或语义化结构。src 既可以指向应用 public/ 目录下的本地静态资源，也可以填写远程图片地址，交由 provider 统一处理。

核心能力逐项解析

1. 内置 provider：本地与远程图片的统一优化入口

<NuxtImg> 的底层核心是“provider（提供方）”抽象。开启模块后，图片请求会经由内置的优化管线处理——既可调用开箱即用的本地优化器，也可对接你偏好的图片 CDN。因此无论图片托管在本地还是远端，src 最终都会被转换为 provider 可识别的优化 URL，由后端完成压缩、格式协商等重活，前端无需关心实现细节。

2. 基于 `width` / `height` 的自动缩放

为组件显式声明宽高后，provider 会按此尺寸对图片进行缩放后再下发，而不是让浏览器下载原始大图后靠 CSS 压缩展示。这一行为与性能文档中的建议高度吻合：宽高明确的图片可避免布局抖动（Layout Shift），配合 loading 与 fetchpriority 还能进一步优化首屏加载体验。

<NuxtImg
  src="/hero-banner.jpg"
  format="webp"
  loading="eager"
  width="200"
  height="100"
/>

3. `sizes` 选项与响应式尺寸生成

当需要适配多端屏幕时，可以传入 sizes 选项，组件会自动生成一组不同分辨率的候选地址（srcset），交由浏览器依据当前视口宽度挑选最合适的版本下载。这是提升移动端加载性能、避免“一刀切”下载大图的关键手段。

4. 原生懒加载与其余 `<img>` 属性透传

<NuxtImg> 完整保留了对原生 loading、alt、fetchpriority 等属性的支持，因此可以零成本地使用浏览器原生懒加载机制。例如在 Nuxt 官方性能最佳实践中，团队将图片按首屏优先级拆分为两类（示例出自 docs/3.guide/2.best-practices/performance.md）：

<template>
  <!-- 🚨 需要立即加载（如 LCP 元素） -->
  <NuxtImg
    src="/hero-banner.jpg"
    format="webp"
    :preload="{ fetchPriority: 'high' }"
    loading="eager"
    width="200"
    height="100"
  />

  <!-- 🐌 可以延迟加载 -->
  <NuxtImg
    src="/facebook-logo.jpg"
    format="webp"
    loading="lazy"
    fetchpriority="low"
    width="200"
    height="100"
  />
</template>

其中 format="webp" 请求将图片转换为更现代的 WebP（或 Avif）格式以减小体积；首屏图显式声明 eager + 高优先级预加载，非关键图则使用 lazy + 低 fetchpriority，让浏览器资源调度始终聚焦在最重要内容上。由于图片体积直接左右 Largest Contentful Paint（LCP）指标，这类配置对于真实站点的性能优化价值显著。

预加载（preload）在框架层如何工作

<NuxtImg preload> 这类由 Nuxt Image 模块写入 <head> 的预加载链接，在 Nuxt 运行时中会被专门的插件处理。见仓库中的服务端插件 packages/nuxt/src/app/plugins/prefetch-preload-tags.server.ts：

它通过 FORWARDED_RELS 白名单（preload、modulepreload）筛选页面 head 中用户自定义的 link 标签，注释明确写到这些标签来源包括 nuxt/image 的 <NuxtImg preload>；
插件在 SSR 阶段把这些链接序列化写入 ssrContext.payload.prefetchLinks；
当前文档 docs/3.guide/6.going-further/1.experimental-features.md 中进一步说明：当 <NuxtLink> 预取的目标路由启用了 payload extraction（预渲染与缓存路由的默认行为）时，会把这些来自 <NuxtImg preload> 等处的 <link rel="preload"> 提示转发到当前文档中，让关键图片资源能在路由切换前提前就位。

从这段源码可以看出，<NuxtImg> 的“预加载”能力并非简单的一次性标签输出，而是与 Nuxt 的 payload 提取、链接预取机制深度联动，属于框架级的能力设计。

模块的启用与禁用管理

由于 Nuxt Image 与框架之间是“模块注册制”，<NuxtImg> 是否可用完全取决于 @nuxt/image 模块的加载状态。Nuxt v4.3 起支持通过将模块对应的配置键设为 false 来禁用模块（参考 Nuxt Modules 文档）：

export default defineNuxtConfig({
  // 禁用 `@nuxt/image` 模块
  image: false,
})

这一写法在基于层的项目结构中尤其有用——当父层（layer）启用了 Nuxt Image 而你希望覆盖该行为时，可在当前应用的配置中直接关闭。image 就是 @nuxt/image 模块定义的顶层配置键，与 pinia（对应 @pinia/nuxt）、content（对应 @nuxt/content）同理，具体配置键以各模块文档为准（见 Layers 指南）。

小结

围绕 <NuxtImg>，Nuxt 生态给出了一套完整的图片优化闭环：

一键启用：npx nuxt module add image 完成模块安装与注册；
无缝替换：用 <NuxtImg> 直接替代 <img>，自动获得本地/远程图片优化、URL 转换、按宽高缩放与响应式 sizes；
原生属性兼容：loading、fetchpriority、alt 等全部透传，可配合 format、preload 等扩展属性精细控制资源优先级；
框架级联动：<NuxtImg preload> 产出的预加载提示会经由 Nuxt 服务端插件进入 payload，与路由预取协同工作；
可控可关：模块级能力可通过 image: false 在单应用或层继承场景下灵活启停。