Back to Details

netlify-image-cdn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Netlify Image CDN

Netlify Image CDN

Every Netlify site has a built-in 
/.netlify/images
endpoint for on-the-fly image transformation. No configuration required for local images.
每个Netlify站点都内置了
/.netlify/images
端点，用于实时图片转换。本地图片无需额外配置。

Basic Usage

基础用法

html
<img src="/.netlify/images?url=/photo.jpg&w=800&h=600&fit=cover&q=80" />
html
<img src="/.netlify/images?url=/photo.jpg&w=800&h=600&fit=cover&q=80" />

Query Parameters

查询参数

ParamDescriptionValues
url
Source image path (required)Relative path or absolute URL
w
Width in pixelsAny positive integer
h
Height in pixelsAny positive integer
fit
Resize behavior
contain
(default), 
cover
, 
fill
position
Crop alignment (with 
cover
)
center
(default), 
top
, 
bottom
, 
left
, 
right
fm
Output format
avif
, 
webp
, 
jpg
, 
png
, 
gif
, 
blurhash
q
Quality (lossy formats)1-100 (default: 75)
When 
fm
is omitted, Netlify auto-negotiates the best format based on browser support (preferring 
webp
, then 
avif
).
参数说明取值
url
源图片路径（必填）相对路径或绝对URL
w
宽度（像素）任意正整数
h
高度（像素）任意正整数
fit
缩放行为
contain
（默认）、
cover
、
fill
position
裁剪对齐（配合
cover
使用）
center
（默认）、
top
、
bottom
、
left
、
right
fm
输出格式
avif
、
webp
、
jpg
、
png
、
gif
、
blurhash
q
质量（有损格式）1-100（默认：75）
当省略
fm
时，Netlify会根据浏览器支持自动协商最佳格式（优先选择
webp
，其次是
avif
）。

Remote Image Allowlisting

远程图片白名单

External images must be explicitly allowed in 
netlify.toml
:
toml
[images]
remote_images = ["https://example\\.com/.*", "https://cdn\\.images\\.com/.*"]
Values are regex patterns.
外部图片必须在
netlify.toml
中明确允许：
toml
[images]
remote_images = ["https://example\\.com/.*", "https://cdn\\.images\\.com/.*"]
取值为正则表达式模式。

Clean URL Rewrites

简洁URL重写

Create user-friendly image URLs with redirects:
toml
undefined
通过重定向创建用户友好的图片URL：
toml
undefined

Basic optimization

基础优化

[[redirects]] from = "/img/*" to = "/.netlify/images?url=/:splat" status = 200
[[redirects]] from = "/img/*" to = "/.netlify/images?url=/:splat" status = 200

Preset: thumbnail

预设：缩略图

[[redirects]] from = "/img/thumb/:key" to = "/.netlify/images?url=/uploads/:key&w=150&h=150&fit=cover" status = 200
[[redirects]] from = "/img/thumb/:key" to = "/.netlify/images?url=/uploads/:key&w=150&h=150&fit=cover" status = 200

Preset: hero

预设：首图

[[redirects]] from = "/img/hero/:key" to = "/.netlify/images?url=/uploads/:key&w=1200&h=675&fit=cover" status = 200
undefined
[[redirects]] from = "/img/hero/:key" to = "/.netlify/images?url=/uploads/:key&w=1200&h=675&fit=cover" status = 200
undefined

Caching

缓存

  • Transformed images are cached at the CDN edge automatically
  • Cache invalidates on new deploys
  • Set cache headers on source images to control caching:
toml
[[headers]]
for = "/uploads/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"
  • 转换后的图片会自动在CDN边缘缓存
  • 缓存会在新部署时失效
  • 可设置源图片的缓存头来控制缓存：
toml
[[headers]]
for = "/uploads/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"

User-Uploaded Images

用户上传图片

Combine Netlify Functions (upload handler) + Netlify Blobs (storage) + Image CDN (serving/transforming) to build a complete user-uploaded image pipeline. See references/user-uploads.md for the full pattern.
结合Netlify Functions（上传处理器）+ Netlify Blobs（存储）+ Image CDN（提供/转换服务），构建完整的用户上传图片流程。完整模式请参考references/user-uploads.md。