Angular 图片加载性能优化实战：从零掌握 NgOptimizedImage 指令

2026-09-06 18:26:00作者：翟萌耘Ralph

NgOptimizedImage 是 Angular 官方提供的图片加载性能指令，旨在让开发者用最低成本落地 Core Web Vitals 中与图片相关的最佳实践——包括 LCP（Largest Contentful Paint）图片的优先加载、非关键图片的默认懒加载、自动 srcset 生成与布局偏移（CLS）防护。本指南以本仓库 adev/src/content/guide/image-optimization.md 为骨架，结合 @angular/common 中 NgOptimizedImage 指令实现展开，读完你将能完成从 src 到 ngSrc 的迁移、配置图片 CDN Loader、使用占位符与 fill 模式，并理解各性能特性背后的实现机制。

版本说明：虽然 NgOptimizedImage 在 Angular 15 中被标记为稳定特性，但它同样以稳定形式向后移植到了 13.4.0 与 14.3.0 版本中，低版本项目同样可以放心使用。

NgOptimizedImage 能帮你解决什么

使用该指令后，框架会在运行时自动完成四件与加载优先级相关的关键动作：

在 <img> 标签上自动设置 fetchpriority 属性；
对其他图片默认启用懒加载（loading=lazy）；
在文档 <head> 中自动生成 preconnect 链接标签；
自动生成 srcset 属性；
若应用使用 SSR 服务端渲染，还会自动生成 preload 提示链接。

除加载性能外，NgOptimizedImage 还会强制约束图片编写规范，例如：使用图片 CDN URL 以便按需做尺寸/格式/质量变换、强制提供 width 与 height 以杜绝布局偏移、当宽高设置错误或图片渲染时会被视觉拉伸变形时给出开发期告警。

如果你正在使用 CSS 中的 background-image，请直接跳到后文迁移 CSS 背景图一节。而判定指令实现是否在开发环境生效，可以关注源码入口 ng_optimized_image.ts 中的 performanceMarkFeature('NgOptimizedImage') 标记。

快速开始：接入 NgOptimizedImage

第一步：导入指令

从 @angular/common 中导入 NgOptimizedImage：

import {NgOptimizedImage} from '@angular/common';

随后将其加入独立组件（standalone component）的 imports 数组，或加入 NgModule 的导入列表：

imports: [
  NgOptimizedImage,
  // ...
],

指令在源码中声明的选择器为 img[ngSrc]（见 ng_optimized_image.ts），因此它只会作用于带 ngSrc 属性的 <img> 元素。

第二步（可选）：配置一个 Image Loader

使用 NgOptimizedImage 并不强制要求配置 Image Loader。但配合图片 CDN 使用 Loader 才能激活更强大的性能特性，尤其是自动生成响应式 srcset。关于 Loader 的完整配置说明，见文末配置 Image Loader一节。

第三步：用 `ngSrc` 替换 `src` 以激活指令

要让指令生效，只需把图片原有的 src 属性替换为 ngSrc：

<img ngSrc="cat.jpg" />

需要留意的是，从源码看 ngSrc 是一个 @Input({required: true, ...})（ng_optimized_image.ts），也就是说它是必填输入；若你使用了内置的第三方 Loader，请务必不要在 ngSrc 中携带 base URL 路径，因为 Loader 会自动将 base URL 前置拼接。

至于为什么不能用 src，这与浏览器的图片加载机制有关：NgOptimizedImage 需要对 loading 属性做程序化修改，而一旦浏览器在修改之前看到 src 属性，就会立刻开始急切下载图片文件，后续的懒加载设置将被忽略。采用 ngSrc 正是为了让指令在写入 src 之前先把加载策略准备好。

第四步：为 LCP 图片标记 `priority`

请务必把页面上的 LCP 图片标记为 priority，以优先加载它：

<img ngSrc="cat.jpg" width="400" height="200" priority />

将图片标记为 priority 会带来以下优化：

设置 fetchpriority=high（即 Priority Hints）；
设置 loading=eager（覆盖默认懒加载）；
若为 SSR 服务端渲染场景，自动生成 preload 链接元素。

在开发模式下，如果 LCP 元素是一张未带 priority 属性的图片，Angular 会输出告警。由于页面 LCP 元素可能因用户屏幕尺寸等因素而变化，一个页面可以有多个应标记 priority 的图片。

第五步：必须提供 `width` 与 `height`

为防止与图片相关的布局偏移（layout shift），NgOptimizedImage 要求为图片显式指定高度与宽度：

<img ngSrc="cat.jpg" width="400" height="200" />

两者语义依据图片类型有所不同：

响应式图片（随视口增大缩小）：width、height 应填写图片文件的固有尺寸（intrinsic size）；同时建议为这类图片设置 sizes 值。
固定尺寸图片：width、height 应填写期望渲染出来的尺寸，且二者的宽高比应当始终与图片的固有宽高比一致。

如果你不知道图片尺寸，可以考虑使用下文介绍的 fill 模式来继承父容器的尺寸。

在源码中这两项输入均经过 numberAttribute 转换（ng_optimized_image.ts），并且非 fill 模式下会执行 assertNonEmptyWidthAndHeight 与宽高比失真检测等一系列开发期断言。

使用 `fill` 模式铺满容器

当你希望图片充满某个容器、实现类似"背景图"行为，或者你不知道图片精确宽高、但父容器尺寸已知并想让图片适配进去时，可使用 fill 属性。

添加 fill 后，不应（也无需）再提供 width 与 height：

<img ngSrc="cat.jpg" fill />

从指令宿主绑定（ng_optimized_image.ts）可以看到，fill 模式会在运行时把图片样式设为 position: absolute; width: 100%; height: 100%; inset: 0。因此可以借助 CSS 控制图片在容器内的呈现：

object-fit: contain：图片保持宽高比，被"信箱式"完整容纳在元素内；
object-fit: cover：图片保持宽高比铺满元素，超出部分被裁切；
也可使用 object-position 调整其在容器内的位置。

重要前提：要让 fill 图片正确渲染，其父元素必须设置为 position: relative、position: fixed 或 position: absolute 三者之一。此外，fill 模式还会默认把 sizes 兜底为 100vw，便于按视口宽度生成合适的候选图。

CSS 背景图（background-image）如何迁移到 NgOptimizedImage

NgOptimizedImage 并不直接支持 CSS background-image 属性，但它专门为"把图片当作某元素背景"的常见诉求设计了迁移路径。将承载背景图的元素称为"容器元素"，迁移步骤如下：

移除容器元素上的 background-image 样式。
确保容器元素具备 position: relative、position: fixed 或 position: absolute 定位。
在容器元素内部新建一个图片子元素，使用 ngSrc 激活 NgOptimizedImage 指令。
给该图片元素添加 fill 属性，同时不要设置 height 与 width。
若你认为这张图可能是 LCP 元素，再为图片元素补上 priority 属性。

之后可按上文 fill 模式一节的方式来调整背景图在容器中的填充表现。

使用占位符（Placeholder）

自动生成的低清占位符

如果你使用的 CDN 或图片托管服务支持自动缩放图片，那么只要给图片加上 placeholder 属性，NgOptimizedImage 就能为图片展示一个自动生成的模糊低清占位：

<img ngSrc="cat.jpg" width="400" height="200" placeholder />

添加该属性后，指令会通过你配置的 Image Loader 额外请求一张小尺寸图片；在正式图片加载完成前，这张小图会以 background-image 加 CSS 模糊（源码实现为 blur(15px)，见 ng_optimized_image.ts）的方式呈现在图片位置。如果没有配置任何 Image Loader，则无法生成占位图，指令会直接抛错。

占位图默认生成宽度为 30px。可通过 IMAGE_CONFIG 提供方（其定义与默认值位于 packages/core/src/application/application_tokens.ts）自定义尺寸：

providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],

注意：源码中的默认配置对象还包含 disableImageSizeWarning 与 disableImageLazyLoadWarning 两个开关（默认均为 false），用于关闭超大图片尺寸与 LCP 图片被懒加载的相关告警，可与 breakpoints 一并配置。

如果你希望模糊占位图四周轮廓锐利，可把图片包在一个设置了 overflow: hidden 的 <div> 中；只要该 <div> 与图片尺寸一致（例如配合 width: fit-content），占位图被模糊"溢出"的边缘就会被隐藏。

Data URL 占位符

在没有 Image Loader 的情况下，你还可以用 base64 Data URL 直接指定占位图，其格式为 data:image/[imagetype];[data]，其中 [imagetype] 为图片格式（如 png），[data] 为图片的 base64 编码：

<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />

但过大的 Data URL 会增大 Angular 产物体积并拖慢页面加载，因此官方建议：若无法使用 Image Loader，请将 base64 占位图控制在 4KB 以内，并只把它用于关键图片。除了缩小占位图尺寸，还可以调整保存时的图片格式或编码参数——在极低分辨率下这些参数对文件体积影响非常显著。源码同样给出了工程约束：DATA_URL_WARN_LIMIT = 4000（触发告警）、DATA_URL_ERROR_LIMIT = 10000（直接报错），见 ng_optimized_image.ts。

关闭占位图的模糊效果

默认情况下 NgOptimizedImage 会给占位图套一层 CSS 模糊。若想渲染不带模糊的占位图，可通过 placeholderConfig 传入包含 blur: false 的对象：

<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />

placeholderConfig 对应的 ImagePlaceholderConfig 接口定义在源码 ng_optimized_image.ts 中。

调整图片样式，避免失真告警

取决于图片自身的 CSS 样式，追加 width 与 height 属性后，图片的渲染结果可能与你预期不同。若样式导致图片以扭曲的宽高比渲染，NgOptimizedImage 会发出告警。通常的修复办法是给图片样式补上 height: auto 或 width: auto，让另一维度随固有宽高比自适应。

如果 width 与 height 属性妨碍了你想通过 CSS 调整尺寸，可以考虑改用 fill 模式并去调整图片父元素的样式。从源码看，非 fill 模式下会执行 assertNoImageDistortion 的尺寸失真校验，而 fill 模式因允许图片被有意拉伸/裁切/信箱化而会跳过该项检查（ng_optimized_image.ts）。

性能特性详解

NgOptimizedImage 内置了一系列旨在改善加载性能的特性，逐一说明如下。

添加资源提示（preconnect）

为图片源站添加 preconnect 资源提示可以确保 LCP 图片尽早建立连接。当把域名直接传给某个 Loader 时，preconnect 链接会被自动生成（该判断基于对应用的静态分析，要求域名硬编码在 Loader 参数中）。若图片源无法被自动识别、且 LCP 图片又没有对应的 preconnect 链接，开发模式下会输出告警，此时应在 index.html 的 <head> 中手工添加资源提示：

<link rel="preconnect" href="https://my.cdn.origin" />

如果想关闭 preconnect 告警，可注入 PRECONNECT_CHECK_BLOCKLIST token（该 token 定义于 preconnect_link_checker.ts）：

providers: [
  {provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

关于 preconnect 链接为何没有自动生成，详见 FAQ 一节。另外值得一提的是，SSR 场景下预加载链接也有数量红线：DEFAULT_PRELOADED_IMAGES_LIMIT = 5，超过该阈值框架会抛出错误，以避免过多 preload 标签拖累性能（见 tokens.ts）。

自动 `srcset`：按视口请求正确尺寸

定义 srcset 可以保证浏览器按用户视口请求合适尺寸的图片，避免下载过大的资源造成浪费。NgOptimizedImage 会根据图片标签上是否存在 sizes 属性及其取值，自动生成相应的 srcset。

固定尺寸图片

如果图片在各设备上渲染尺寸固定（仅像素密度不同），则无需设置 sizes。指令可从 width 与 height 属性直接推导并生成 srcset。例如会生成类似：

<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />

其背后的密度倍率取自源码常量 DENSITY_SRCSET_MULTIPLIERS = [1, 2]（ng_optimized_image.ts），即固定尺寸图片默认提供 1x 与 2x 两档候选。同时，为避免请求超大源图，固定尺寸 srcset 生成的宽度上限为 1920px、高度上限为 1080px（对应 FIXED_SRCSET_WIDTH_LIMIT / FIXED_SRCSET_HEIGHT_LIMIT）。超过密度上限的值也会被拒绝：源码中 ABSOLUTE_SRCSET_DENSITY_CAP = 3，超过 3x 的密度描述符会直接抛错，官方推荐值则是不超过 2x。

响应式图片

如果图片需要随视口伸缩，则需要通过 sizes 属性来驱动 srcset 的生成。

对 sizes 不熟悉的读者，推荐先按视口宽度来设：例如当 CSS 让图片占据 100% 视口宽度时，设 sizes="100vw"，浏览器会从 srcset 中选出（计入像素密度后）最接近视口宽度的候选图；若图片通常只占屏幕一半（如侧边栏），设 sizes="50vw" 即可让浏览器挑选更小的图。更复杂的行为见高级 sizes 取值。

需要说明的是，NgOptimizedImage 会自动为传入的 sizes 值前置 "auto"——这是针对支持 sizes="auto" 的浏览器提高选图精度的优化，不支持的浏览器会忽略它。响应式图片默认断点（breakpoints）如下：

[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]

这些默认值同时被定义在 application_tokens.ts 的 IMAGE_CONFIG_DEFAULTS 中。如需自定义，可通过 IMAGE_CONFIG 提供方覆盖：

providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],

在生成自动 srcset 时，源码还做了两处细节处理：超过 640px（VIEWPORT_BREAKPOINT_CUTOFF）的视口断点会参与"全宽图片"候选的按需裁剪；同时会检测请求尺寸是否远超实际渲染尺寸（OVERSIZED_IMAGE_TOLERANCE = 1000px 容差），从而对超大图给出告警。

手工指定 `ngSrcset`

如果你希望完全手动定义 srcset，可以使用 ngSrcset 属性：

<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" />

当 ngSrcset 存在时，指令会据此生成并写入最终的 srcset。注意 ngSrcset 中不要写图片文件名，指令会从 ngSrc 推断文件名，它同时支持宽度描述符（如 100w）与像素密度描述符（如 1x）：

<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />

关闭单张图片的自动 srcset 生成

若只想让某张图片不参与自动 srcset，可在该图片上添加 disableOptimizedSrcset 属性：

<img ngSrc="about.jpg" disableOptimizedSrcset />

关闭图片懒加载

默认情况下，所有未标记 priority 的图片都会被 NgOptimizedImage 设置 loading=lazy。你可以在非 priority 图片上显式设置 loading 属性来关闭这一行为，取值与标准 loading 属性一致：eager、auto、lazy。

<img ngSrc="cat.jpg" width="400" height="200" loading="eager" />

不过从源码的注释提醒来看，把图片设为 loading="eager" 或 loading="auto" 意味着它被视为非 priority 图片，可能损害加载性能；对可能是 LCP 元素的图片，应优先使用 priority 属性而不是 loading。

控制图片解码方式（decoding）

默认情况下 NgOptimizedImage 为所有图片设置 decoding="auto"，让浏览器自行决定取回图片后的最佳解码时机。而当图片标记为 priority 时，Angular 会自动设置 decoding="sync"，确保图片尽早解码并绘制，从而改善 LCP 指标。你也可以显式设置 decoding 属性覆盖该行为：

<!-- 默认：decoding 为 'auto' -->
<img ngSrc="gallery/landscape.jpg" width="1200" height="800" />

<!-- 异步解码，避免阻塞主线程 -->
<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async" />

<!-- priority 图片自动使用 decoding="sync" -->
<img ngSrc="awesome.jpg" width="500" height="625" priority />

<!-- 需要立即拿到像素时同步解码（可能阻塞渲染） -->
<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync" />

允许取值：

auto（默认）：让浏览器选择最优解码策略；
async：异步解码图片，尽量不阻塞主线程；
sync：立即解码图片，可能阻塞渲染，但能保证图片一可用像素即就绪。

高级 `sizes` 取值（媒体查询语法）

你可能会希望图片在不同尺寸屏幕上以不同宽度展示。栅格/多列布局是常见场景：手机端渲染单列，大屏端渲染两列。可以用 sizes 属性的媒体查询语法表达这一行为：

<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />

上面 sizes 的含义是："在宽度小于 768px 的设备上，我预期这张图占屏幕宽度的 100%；其余场景下占屏幕宽度的 50%。"

配置 Image Loader：CDN 服务与自定义规则

"Loader"是一个根据图片文件名生成图片变换 URL 的函数；在合适时机，NgOptimizedImage 会通过它设置图片的尺寸、格式与质量等变换参数。指令既提供不做任何变换的通用 Loader，也内置多个第三方图片服务 Loader，同时完全支持编写自定义 Loader。

Loader 类型	行为
通用 Loader（Generic loader）	返回的 URL 永远等于 `src` 原值，即不做任何变换，适合"用 Angular 自身托管图片"的站点，也是未做任何配置时的默认行为
第三方图片服务 Loader	返回 URL 遵循对应图片服务自身的 API 约定
自定义 Loader	行为由开发者定义；当你的图片服务不在预置 Loader 支持范围内时使用

ImageLoaderConfig 的类型定义位于 image_loader.ts：包含必填的 src，可选的 width、height、isPlaceholder（是否请求占位小图）以及 loaderParams。ImageLoader 类型本身是 (config: ImageLoaderConfig) => string 的函数签名。

结合 Angular 应用常用的图片服务，仓库预置了以下 Loader：

图片服务	Angular API	说明
Cloudflare Image Resizing	`provideCloudflareLoader`	基于 Cloudflare 图片缩放服务
Cloudinary	`provideCloudinaryLoader`	遵循 Cloudinary 缩放/裁剪 API
ImageKit	`provideImageKitLoader`	遵循 ImageKit API
Imgix	`provideImgixLoader`	遵循 Imgix API
Netlify	`provideNetlifyLoader`	遵循 Netlify Image CDN

这五个内置 Loader 均位于 packages/common/src/directives/ng_optimized_image/image_loaders/ 目录，并统一由 image_loader.ts 中的 createImageLoader 工厂函数包装生成。以 Imgix Loader 的源码实现（imgix_loader.ts）为例，它默认追加 auto=format，按需追加 w/h 参数，占位图请求时还会附带低质量参数 q，因此指令要求的 CDN 支持能力是真实存在的。

内置 Loader 的使用方式

使用第三方图片服务 Loader 时，把对应服务的 provider 工厂函数加入 providers 数组即可。例如使用 Imgix：

providers: [
  provideImgixLoader('https://my.base.url/'),
],

图片资源的 base URL 需要作为参数传给 provider 工厂函数。对大多数站点，base URL 应形如以下几种：

https://yoursite.yourcdn.com
https://subdomain.yoursite.com
https://subdomain.yourcdn.com/yoursite

createImageLoader 在注册时会校验 base path 的合法性，并对传入绝对 URL 的 ngSrc 抛出 INVALID_LOADER_ARGUMENTS 运行时错误——内置 Loader 期望 ngSrc 是相对路径而非绝对地址（image_loader.ts）。

自定义 Loader

使用自定义 Loader 时，把 loader 函数作为 IMAGE_LOADER DI token 的值提供即可。IMAGE_LOADER token 的默认工厂回落到 noopImageLoader（原样返回 src），这正是"不配置即通用行为"的原理（image_loader.ts）。下面的自定义 loader 返回以 https://example.com 开头、携带 src/width/height 参数：

providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}&height=${config.height}`;
    },
  },
],

NgOptimizedImage 的 loader 函数接收类型为 ImageLoaderConfig 的对象并返回图片资源的绝对 URL。注意：即使 width 不一定每次都会出现，自定义 loader 也必须基于它实现按宽度取图的能力，否则 ngSrcset 无法正常工作。

`loaderParams` 属性：向自定义 Loader 传参

NgOptimizedImage 额外支持 loaderParams 属性，它专门为自定义 Loader 设计：属性接收任意结构对象的取值，自身不做任何处理，但数据会被合并进传给 Loader 的 ImageLoaderConfig 对象中，从而控制 Loader 行为。一个典型用途是控制 CDN 的高级特性。

内置 Loader 的 `transform` 属性

Cloudinary、Cloudflare、ImageKit 与 Imgix 这四家内置 Loader 支持 loaderParams 中的特殊 transform 属性，用来施加 CDN 提供的自定义图片变换。它接受两种格式：

字符串格式——按 CDN 的变换语法提供逗号分隔字符串：

<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>

对象格式——以键值对提供变换参数：

<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>

注意：Netlify Loader 不支持 transform 属性，因为 Netlify 的图片 CDN 不提供自定义变换参数。源码层面，变换参数会被归一化拆解后拼进 URL 查询串（参见 imgix_loader.ts 对 loaderParams['transform'] 的处理）。

完整示例：带 loaderParams 的自定义 Loader

下面这个 loader 拼接 src、width、height，并借助 loaderParams 控制某个 CDN 的圆角特性：

const myCustomLoader = (config: ImageLoaderConfig) => {
  let url = `https://example.com/images/${config.src}?`;
  let queryParams = [];
  if (config.width) {
    queryParams.push(`w=${config.width}`);
  }
  if (config.height) {
    queryParams.push(`h=${config.height}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};

示例中 roundedCorners 是为了控制自定义 Loader 特性而自行发明的属性名。声明该 provider 后，在模板中即可这样启用圆角特性：

<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />

常见问题（FAQ）

`NgOptimizedImage` 是否支持 CSS `background-image`？

指令不直接支持 background-image CSS 属性，但设计上很容易满足"把图片作为另一元素背景"的需求。迁移步骤见前文迁移指南。

为什么 `NgOptimizedImage` 不能用 `src`？

由于浏览器加载机制的限制：NgOptimizedImage 需要程序化修改 loading 属性，若浏览器在修改前已看到 src，会立刻急切下载图片，懒加载设置随即失效。因此采用 ngSrc 作为指令触发器，确保时机可控。

为什么我的图片域名没有生成 preconnect 链接？

preconnect 的生成基于对应用的静态分析：图片域名必须被直接、硬编码地包含在 Loader 参数中，例如：

providers: [
  provideImgixLoader('https://my.base.url/'),
],

若用变量间接传递域名，或根本没有配置 Loader，静态分析将无法识别域名，自然也不会生成 preconnect 链接。此时应如前文所述手工在文档 <head> 中添加 preconnect 链接。

同一页面能使用两个不同的图片域名吗？

Loader 的 provider 模式为"单组件内只用一个图片 CDN"这种最常见场景把配置做到最简，但通过一个 provider 管理多个图片 CDN 也是完全可行的。推荐做法是编写一个自定义 Loader，利用 loaderParams 传入一个标识来选择图片 CDN，再按该标识分派到合适的 Loader 逻辑上。