图片优化

把一张原始尺寸的图片放进 src/ 或 public/，用 <img> 指向它，sitelo 就会缩放它、转成现代格式，并把标签重写为带 srcset 的版本。不用 import，也没有组件要学。

启用

export default {
  images: true,
}

编码工作由 sharp 完成，它是一个可选的 peer 依赖 —— 启用图片功能时请与 sitelo 一并安装：

npm install -D sharp

不做图片优化的站点则完全不需要安装它。

写一个普通的 <img>

export default () => `
  <html lang="zh">
    <body>
      <img src="/images/hero.png" alt="港口上的日出">
    </body>
  </html>
`

import { html, body, img } from 'javascript-to-html'

export default () =>
  html({ lang: 'zh' },
    body(
      img({ src: '/images/hero.png', alt: '港口上的日出' }),
    ),
  )

export default function Home() {
  return (
    <html lang="zh">
      <body>
        <img src="/images/hero.png" alt="港口上的日出" />
      </body>
    </html>
  )
}

一张 3000×2000 的原图，出来是这样：

<img src="/assets/img/hero.a1b2c3d4-1200.webp"
     alt="港口上的日出"
     sizes="(max-width: 1200px) 100vw, 1200px"
     width="1200" height="800"
     loading="lazy" decoding="async"
     srcset="/assets/img/hero.9f8e7d6c-400.webp 400w,
             /assets/img/hero.5b4a3c2d-800.webp 800w,
             /assets/img/hero.a1b2c3d4-1200.webp 1200w">

你会得到什么

永不放大的缩放 —— 600px 的原图配上 widths: [400, 800, 1200]，只会产出 400 和 600，到此为止。
现代格式 —— 只配一种格式会得到普通的 <img srcset>；两种或更多则会包进 <picture>，并保留原格式作为回退。
没有布局偏移 —— width 和 height 会依据真实图片补全，同时加上 loading="lazy" 和 decoding="async"。
开发时是同一套标记 —— sitelo（dev）会重写页面并按需提供各个变体，你预览到的就是将来发布的样子。
共享缓存 —— 变体按内容哈希存放在 node_modules/.sitelo/images，因此开发和重复构建都不会把同一张图片编码两次。

重写作用于构建出的 HTML，因此来自 src/ 和 public/ 的图片都会被覆盖到。

选项

export default {
  images: {
    widths: [400, 800, 1200],
    formats: ['avif', 'webp'],
    quality: { avif: 55, webp: 78, jpeg: 82 },
    exclude: ['**/og/**'],
  },
}

widths —— 默认 [400, 800, 1200]；最大值同时也是上限
formats —— 默认 ['webp']；可选 avif、webp、jpeg、png
quality —— 默认 { avif: 55, webp: 78, jpeg: 82 }；按格式设置编码质量（png 用的是压缩级别，而非质量）
sizes —— sizes 属性；标签上已有的 sizes 始终优先
dimensions —— 默认 true；补上 width / height
lazy —— 默认 true；补上 loading 和 decoding
exclude —— 要跳过的图片 URL 的 glob 或正则
assetsDir —— 默认 'assets/img'
cacheDir —— 默认 'node_modules/.sitelo/images'
remote —— 默认 false；在构建时优化 https:// 图片
prune —— 默认 false；删除已无人引用的原图
dev —— 默认 true；设为 false 可在开发时直接提供未处理的原图
concurrency —— 并行编码数，默认 CPU 核数 − 1（最多 8）；开启 remote 时为 1

两种格式会得到

AVIF 更小但比 WebP 年轻，同时列出两者可以让浏览器自行选择，并为旧浏览器保留回退：

<picture>
  <source type="image/avif" srcset="/assets/img/hero.*-400.avif 400w, ..." sizes="...">
  <source type="image/webp" srcset="/assets/img/hero.*-400.webp 400w, ..." sizes="...">
  <img src="/assets/img/hero.*-1200.png" alt="..." srcset="..." width="1200" height="800">
</picture>

如何排除

已经带有 srcset、位于 <picture> 内部，或指向 SVG、动图 GIF、远程 URL 的标签都不会被改动。其他情况请显式声明：

<img src="/images/exact.png" alt="像素画" data-no-optimize>

社交卡片和 favicon 的图片写在 <meta> 和 <link> 里，这里永远不会重写它们 —— 它们的 URL 保持固定。

远程图片

从 CMS 导入的内容往往指向别人的服务器。开启 remote，这些图片就会被下载、优化，并从你自己的域名提供：

export default {
  images: {
    remote: true,
    prune: true,
  },
}

抓取失败时标签会原封不动地保留，并给出警告 —— 不稳定的源站永远不会让你的构建失败。随后 prune 会清除已无人引用的本地原图。