用途:Netlify Image CDN 通过请求 /.netlify/images 端点并按需转换图片,这是当前唯一有文档的接口形式。
主要能力:GET /.netlify/images?url=<source>[&w=][&h=][&fit=][&position=][&fm=][&q=]。url 必填,其余可选。w、h 为像素整数;fit 取 contain(默认,保持比例)、cover(需同时提供 w 和 h,按 position 裁剪)、fill(拉伸填满);position 取 top、bottom、left、right、center(默认 center);fm 取 avif、jpg、png、webp、gif、blurhash,省略时按 Accept 头协商;q 为 1–100,默认 75,仅对 avif、jpg、gif、webp 生效。
使用方式:可直接请求端点,例如 curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'。远程图片需先在 netlify.toml 的 [images] remote_images 中允许,且远程 URL 需用 encodeURIComponent 编码。可用 _redirects 或 netlify.toml 重写把友好路径映射到端点。
适用场景:站点图片缩放、裁剪、格式转换;多数框架(Angular、Astro、Gatsby、Next.js、Nuxt)的内置图片优化会走此 CDN,只需配置远程允许列表。
限制:远程源须公开可访问,Authorization、Cookie 等凭据头不会转发;无效参数返回 404,新转换返回 200,缓存命中返回 304;fm=blurhash 返回文本字符串而非图片字节;本地需用 netlify dev 才能使用该端点;不支持 Split Testing,且不属于 HIPAA 合规托管范围。