netlify-image-cdn

Netlify Image CDN

通过请求带有 url 查询参数的端点来转换图片。这是当前唯一记录的用法——不存在旧版格式。

GET /.netlify/images?url=<source>[&w=][&h=][&fit=][&position=][&fm=][&q=]

# resize a deployed image to 50px wide
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'

url 为必填项；所有其他参数均为可选项。

查询参数

参数	用途	值	默认值
url	源资源（必填）	相对路径或远程 URL	—
w	宽度（像素）	整数	—
h	高度（像素）	整数	—
fit	调整大小的方式	contain、cover、fill	contain
position	fit=cover 时的裁剪锚点	top、bottom、left、right、center	center
fm	输出格式	avif、jpg、png、webp、gif、blurhash	根据内容协商
q	有损输出的质量	整数 1–100	75

常见转换

# resize + crop to a 50px square, retaining the left side
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left'

# convert JPEG to PNG (response carries content-type: image/png)
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=png'

# convert JPEG to AVIF at medium quality
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=avif&q=50'

fit 行为

• **contain（默认值）：**保持宽高比；返回的一个维度可能小于请求值。提供一个维度，另一个维度会自动计算。
• **cover：**填满指定尺寸，裁掉多余部分。必须同时提供 w 和 h——省略任意一个都无效。使用 position 选择要保留的部分。
• **fill：**填满指定尺寸；宽高比不同时会拉伸或压缩图片。

格式说明

• q 仅在输出格式为 avif、jpg、gif 或 webp 时生效。
• webp 和 gif 可以是静态或动态格式。
• 如果省略 fm，则根据 Accept 标头协商格式：如果支持 webp，则使用 webp；否则，如果支持 avif，则使用 avif；否则使用原始格式。仅请求源图片（不带其他参数）时，仍会转换为 webp/avif，但保持尺寸和形状不变。

远程源图片

必须先在 netlify.toml 中将远程源加入允许列表，才能进行转换，否则请求会失败。

[images]
  remote_images = ['https://my-images\.com/.*', 'https://animals.more-images.com/[bcr]at/.*']

将远程源 URL 放入 url 参数前，使用 encodeURIComponent 对其进行百分号编码——否则，包含 ? 或 & 的 URL 会导致问题。

const src = `/.netlify/images?url=${encodeURIComponent('https://my-images.com/owl.jpeg?v=2')}&w=400`;

限制：

• 远程源必须可公开访问。
• 获取远程源时，不会转发包含凭据的标头（Authorization、Cookie）。对于需要身份验证的源，请使用自身携带授权信息的 URL（例如 S3 预签名 URL），并确保 remote_images 模式与这些完整 URL 匹配。

remote_images 正则表达式转义

只有字面句点（\.）需要转义。正斜杠不是元字符——切勿写成 https:\/\/。在 netlify.toml 中，使用单引号字面字符串（'https://example\.com/.*'），或在双引号字符串中将反斜杠加倍（"https://example\\.com/.*"）。在双引号中直接使用 \. 是无效的 TOML。

响应代码

• 转换参数值无效 → 404。
• 有效的新转换 → 200，并返回内容和匹配的 content-type。
• 之前转换过的图片（已缓存） → 304。

在多张图片之间复用参数

使用重定向/重写将友好路径映射到端点。

_redirects：

/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200

netlify.toml：

[[redirects]]
  from = "/transform-small/*"
  to = "/.netlify/images?url=/:splat&w=50&h=50"
  status = 200

然后 GET /transform-small/owl.jpeg 会返回转换后的图片。不建议跨站重定向进行转换——这可能会降低网站性能。

缓存标头

为网站自有域名上的源图片应用自定义标头，这些标头会沿用到转换后的输出。

netlify.toml：

[[headers]]
  for = "/source-images/*"
  [headers.values]
    Cache-Control = "public, max-age=604800, must-revalidate"

• 自定义标头只能应用于网站域名上的源图片，不能应用于远程源图片（Netlify 会遵循外部域名发送的缓存标头）。
• 源图片上的 Cache-Control 仅适用于 Netlify 前面的浏览器和 CDN，不适用于 Netlify Cache 本身。

模糊占位图（fm=blurhash）

fm=blurhash 返回的是 BlurHash 文本字符串，而非图片字节。将其指定为 <img src>（或 CSS 背景）不会渲染任何内容。请提前获取该字符串，使用 BlurHash 库（https://blurha.sh）在客户端解码，并在不带 fm=blurhash 的单独请求中加载真实图片。

本地开发

/.netlify/images 端点、[images] 允许列表和图片重定向仅在 netlify dev（Netlify CLI）下存在。本地访问 /.netlify/images 出现 **404，几乎总是因为运行的是框架开发服务器（vite、next dev、astro dev），而不是 netlify dev**——URL 本身通常没有问题。使用 netlify dev` 启动本地环境。

用户上传图片的处理流水线

有关组合 Functions + Blobs + Image CDN 处理用户上传图片的流水线，请参阅 references/user-uploads.md。

框架图片处理

许多框架会通过 Netlify Image CDN 处理内置的图片优化——使用框架标准的图片组件／语法，只需配置远程允许列表。对于未列出的框架，请直接调用 /.netlify/images。

框架	前提条件	远程允许列表位置
Angular	无；NgOptimizedImage 会自动使用它	netlify.toml 中的 [images] remote_images
Astro	无；<Image /> 会自动使用它	astro.config.mjs 中的 image.domains 或 image.remotePatterns
Gatsby（5.13+ 和 5.11 或更早版本）	设置环境变量 NETLIFY_IMAGE_CDN=true；使用 Contentful／Drupal／WordPress 源插件	netlify.toml 中的 [images] remote_images
Next.js	Next.js 13.5+ 和 Next.js adapter v5	next.config.js 中的 remotePatterns
Nuxt	无；nuxt/image 模块会自动使用它	nuxt.config.ts 中的 image.domains

设置指南：Angular、Astro、Gatsby、Next.js、Nuxt。

其他限制

• 部署行为：转换遵循原子部署；在新部署中更改源图片后，后续请求会重新运行转换。
• 不支持 Split Testing——图片结果在不同的拆分测试分支中可能不一致。
• Netlify Image CDN 不属于 Netlify 符合 HIPAA 标准的托管服务。

交互式参数试用工具：https://image-cdn-playground.netlify.app/

Netlify 约定（image-cdn）

这些是组织约定，不是文档事实——由 ctx-gen 合并到渲染后的 skill 中，且不会自动生成。由技能维护者负责。

1. 对于用户上传图片的处理流程（组合使用 Functions、Blobs 和 Image CDN），请参阅此 skill 中的 references/user-uploads.md——这是一份编写完成的指南，没有单一的文档来源。
2. 将远程源 URL 放入 url 参数前，先对其进行百分号编码（encodeURIComponent）——否则，包含 ? 或 & 的 URL 会导致问题。
3. fm=blurhash 返回的是 BlurHash 文本字符串，而不是图片字节。将其指向 <img src>（或 CSS 背景）不会显示任何内容——请提前获取该字符串，在客户端使用 BlurHash 库解码，并单独发起请求加载实际图片，不要带上 fm=blurhash。
4. 本地访问 /.netlify/images 返回 404，通常意味着当前运行的是框架开发服务器（vite、next dev、astro dev），而不是 netlify dev——此端点、[images] 许可列表和图片重定向仅在 netlify dev 下存在。URL 本身通常没有问题。
5. 在 remote_images 模式中，有意义的正则转义是点号；正斜杠不是元字符——不要写成 https:\/\/。在 netlify.toml 中，请使用单引号字面字符串（'https://example\.com/.*'），或在双引号字符串中将反斜杠加倍（"https://example\\.com/.*"）——双引号内单独的 \. 是无效的 TOML。