企业官网建设流程全解析

• Web框架
• 后端
• 前端

@sveltejs/enhanced-img是 SvelteKit 官方仓库中提供的一个 Vite 插件：它在构建时运行一个 Svelte 预处理器来定位图片，并在打包阶段将图片转换为多格式、多尺寸的响应式资源。本文以 packages/enhanced-img/README.md 为主体，结合该包的源码、测试与示例应用，完整讲解它的工作原理、接入方式、<enhanced:img>组件用法、动态选图、尺寸策略与实验性状态，帮助你在 SvelteKit 项目中一步到位获得 AVIF/WebP 自动降级、宽度/像素密度描述符与sizes支持。

一、这是什么：构建期图片优化插件

1.1 一句话定位

官方 README 对它的定义是：

A Vite plugin which runs a Svelte preprocessor to locate images and then transform them at build-time.

即：一个 Vite 插件，通过运行 Svelte 预处理器来定位图片，并在构建时对它们进行转换。核心卖点是"构建期（build-time）"，意味着优化发生在打包阶段而非运行时，最终产出的是一组已经生成好的多尺寸、多格式图片文件，页面加载时直接命中最优资源，不消耗服务端与客户端的额外算力。

1.2 与 vite-imagetools 的关系

@sveltejs/enhanced-img本身不实现底层的图片缩放与格式编码，而是：

• 基于vite-imagetools完成图片处理管线（缩放、格式转换、生成srcset）；
• 基于svelte-preprocess-import-assets的思路实现标记到<picture>的转换逻辑（README 的 Acknowledgements 部分明确致谢了这两个项目）。

从 package.json 的依赖可以看到具体分工：

1.3 实验性状态（重要前提）

README 在开头给出了明确的WARNING：

This package is experimental. It uses pre-1.0 versioning and may introduce breaking changes with every minor version release.

当前仓库中该包版本为1.0.0-next.5（见 package.json），采用 pre-1.0 的版本号策略，每一个 minor 版本都可能引入破坏性变更。引入生产项目前请锁好版本、关注 CHANGELOG。

二、安装与接入

2.1 安装与运行环境要求

根据 package.json 中的声明，安装前请确认环境：

• Node.js >= 22（engines字段，CHANGELOG 中标记为 breaking 变更）；
• peerDependencies：
  • svelte: ^5.0.0
  • vite: >=8.0.12（Vite 8，首个内置稳定 rolldown 1.0.0 的版本）
  • @sveltejs/vite-plugin-svelte: ^7.0.0（插件运行依赖它注入的配置 API）

安装命令：

pnpm add -D @sveltejs/enhanced-img # 或 npm install -D @sveltejs/enhanced-img

若缺失@sveltejs/vite-plugin-svelte，插件会在configResolved阶段直接抛错："@sveltejs/enhanced-imgrequires@sveltejs/vite-plugin-svelte6 or higher to be installed"（见 src/vite-plugin.js）。

2.2 在 vite.config 中启用

在 Vite 配置中导入并调用enhancedImages()，必须放在sveltekit()之前，且这是测试应用的实际用法（见 test/apps/basics/vite.config.js）：

// vite.config.js import { sveltekit } from '@sveltejs/kit/vite'; import { enhancedImages } from '@sveltejs/enhanced-img'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [enhancedImages(), sveltekit()] });

入口实现位于 src/index.js：enhancedImages()会创建vite-imagetools实例，并返回两个插件组成的数组——image_plugin（标记转换预处理）与imagetools_instance（图片资源加载/处理），顺序是先标记转换、再资源处理：

export function enhancedImages() { const imagetools_instance = imagetools_plugin(); return !process.versions.webcontainer ? [image_plugin(imagetools_instance), imagetools_instance] : []; }

注意其中的 WebContainer 分支：在 WebContainers 环境中该函数返回空数组（因为sharp无法在其中运行），插件会静默失效。

三、核心用法：<enhanced:img>组件

3.1 基础用法（静态字符串 src）

在任意.svelte组件中，把<img>换成<enhanced:img>即可。src 支持相对当前模块的字符串路径：

<enhanced:img src="./birds.jpg" alt="birds" />

官方测试应用（test/apps/basics/src/routes/+page.svelte）展示了三种典型用法：

<!-- 标准位图：会被构建期优化 --> <enhanced:img id="birds" src="./birds.jpg" alt="birds" /> <!-- SVG：不会被处理管线转换，但会补充尺寸 --> <enhanced:img id="playwright" src="./playwright-logo.svg" alt="Playwright logo" /> <!-- 动态图片：传入 ?enhanced 导入的 Picture 对象 --> <enhanced:img id="logo" src={logo} alt="Svelte logo" />

3.2 可优化文件类型

源码中定义了可优化资源的正则（src/vite-plugin.js）：

const OPTIMIZABLE = /^[^?]+\.(avif|heif|gif|jpeg|jpg|png|tiff|webp)(\?.*)?$/;

即avif / heif / gif / jpeg / jpg / png / tiff / webp这些位图格式会被完整转换；SVG 等格式不会被转换，但插件仍会用sharp读取其固有尺寸并自动补上width/height属性（见下面 3.4 节），避免布局偏移。

3.3 构建期转换的产物

对于可优化图片，插件在构建时会把<enhanced:img>替换成<picture>元素：为 AVIF、WebP 以及回退格式各生成一个<source srcset=... type="image/...">，回退格式由 src/index.js 的fallback_format决定：

function fallback_format(meta) { if (meta.pages && meta.pages > 1) { return meta.format === 'tiff' ? 'tiff' : 'gif'; } if (meta.hasAlpha) { return 'png'; } return 'jpg'; }

• 多页图（GIF/多页 TIFF）→ 回退为gif（或tiff）；
• 含透明通道（alpha）→ 回退为png；
• 其他 → 回退为jpg。

因此一张不透明 JPG 会产出avif;webp;jpg三种格式。snapshot 测试（test/Output.svelte）中的真实产物形如：

<picture> <source srcset="/1 1440w, /2 960w" type="image/avif" /> <source srcset="/3 1440w, /4 960w" type="image/webp" /> <source srcset="5 1440w, /6 960w" type="image/png" /> <img src="/7" alt="dev test" width=1440 height=1440 /> </picture>

（开发模式路径形如/@imagetools/...，生产模式则替换为 Vite 的__VITE_ASSET__...哈希资源，参见 src/vite-plugin.js 对__VITE_ASSET__需用双引号包裹以配合 Vite asset 插件的处理。）

3.4 自动补充尺寸，消除布局偏移

对于静态 src 的图片，无论是否可优化，插件都会尽力补全width/height：

• 可优化图片：直接取转换结果中的原始宽高（image.img.w/image.img.h）；
• 不可优化图片（如 SVG）：用sharp读取元数据（src/vite-plugin.js），若读取失败仅打印警告而不中断构建。

更精细的是 serialize_img_attributes 的"缺谁补谁"逻辑：若你只写了width，它会按原图宽高比推算height，反之亦然；只有两者都缺失时才直接补上原图宽高。测试输入（test/Input.svelte）width="5" height="10"在输出中保持原样（test/Output.svelte），而其他测试项则自动获得了width=1440 height=1440，验证了这一行为。

3.5 其他属性、事件与透传

除src外，其他所有属性（alt、class、id、onclick事件、{...spread}展开属性等）都会被原样透传到最终<img>上——测试中专门覆盖了 spread 属性（{...{ foo }}）与事件处理器（onclick）场景（test/Input.svelte）。注意：sizes属性会被从<img>上抽离并复制到每个<source>上（见 src/vite-plugin.js）。

3.6 CSS 选择器改写

如果你在样式中使用enhanced:img选择器，插件会把组件内 CSS 中的enhanced\:img替换为img（src/vite-plugin.js），使样式在转换后的<picture><img>结构上依然生效。

四、响应式与尺寸策略

4.1 未指定 sizes 时：2x 像素密度（x 描述符）

若<enhanced:img>没有提供sizes，插件默认生成两种宽度：原图宽度与一半宽度（向下取整），并使用x像素密度描述符（src/index.js）：

return { widths: [Math.round(width / 2), width], kind: 'x' };

basePixels会取较小那个宽度，保证 2x 屏选择大图、1x 屏选择小图。源码注释解释了为什么上限是 2x：大多数声称 3x 的 OLED 屏实际在红蓝子像素上只有 1.5x，且人眼难以分辨 3x 级别的细节（引用了 Twitter 工程博客关于"上限图像保真度"的讨论），多出的数据量并不带来可感知的画质提升。

4.2 指定 sizes 时：常见设备宽度（w 描述符）

一旦提供了sizes，插件认为图片可能以差异很大的尺寸渲染，于是采用w宽度描述符，并生成一份常见物理设备像素宽度清单（src/index.js）：

const widths = [540, 768, 1080, 1366, 1536, 1920, 2560, 3000, 4096, 5120]; widths.push(width);

之所以包含 1080，是因为 Lighthouse 的移动端模拟设备（Moto G4，360 逻辑像素 × 3x）需要它。最终会把这组宽度与图片原始宽度一起交给vite-imagetools生成多张图。

4.3 显式指令（directives）覆盖

<enhanced:img>的字符串 src 支持带查询参数（?），例如在src上直接追加vite-imagetools风格的指令来覆盖默认策略：

<!-- 显式指定宽度列表 --> <enhanced:img src="./dev.png?w=1024,640,320" sizes="(min-width: 60rem) 80vw, (min-width: 40rem) 90vw, 100vw" alt="sizes test" /> <!-- 显式指定模糊滤镜等处理指令 --> <enhanced:img src="./dev.png?blur=5" alt="directive test" />

这两行都来自测试输入 test/Input.svelte。w指令来自vite-imagetools的默认指令集，而插件自己的defaultDirectives（src/index.js）在检测到 URL 带有enhanced标记时才介入——imgSizes/imgWidth查询参数正是由预处理阶段从sizes/width属性转写而来（src/vite-plugin.js）。

五、动态选图：src={...}与?enhanced

当src是一个表达式而非字符串字面量时，插件无法在构建期静态确定图片，因此要求你显式用?enhanced查询参数导入一个Picture对象：

<script> import hero from '#lib/assets/hero.jpg?enhanced'; </script> <enhanced:img src={hero} alt="..." />

类型定义（types/index.d.ts）对此有明确约束：动态src必须为Picture类型；而静态字符串 src 时Picture对象由插件自动创建，无需手动导入。

5.1 转换产物：运行时的分支渲染

对于动态src，插件生成的模板会在运行时判断值类型（src/vite-plugin.js）：

{#if typeof src === 'string'} {#if import.meta.env.DEV && !width && !height} {src} was not enhanced. Cannot determine dimensions. {:else} <img src={src} /> {/if} {:else} <picture> {#each Object.entries(src.sources) as [format, srcset]} <source {srcset} type={'image/' + format} /> {/each} <img src={src.img.src} width={src.img.w} height={src.img.h} /> </picture> {/if}

• 传入的是Picture对象 → 渲染多格式<picture>；
• 传入的仍是字符串（例如未加?enhanced的普通导入）→ 降级为普通<img>；开发模式下若未指定宽高还会打印 "was not enhanced. Cannot determine dimensions" 提示，帮助你定位漏掉?enhanced的导入。

测试输出 test/Output.svelte 展示了这一完整分支结构。

5.2 表达式缓存：{@const}与防碰撞命名

当src是复杂表达式（如函数调用get_image(i)、条件foo ? a : b、成员访问object.image）时，插件不会重复求值表达式，而是将其缓存到自动生成的变量中（src/vite-plugin.js）：

{#if true}{@const __img_1 = get_image(i)}

选择{@const}而非{const}的原因在源码注释中有详细交代：{@const}是响应式的、带 memo 缓存，且在 Svelte 5 的 legacy 模式与 runes 模式下都可用（{const}声明标签在 legacy 模式会编译报错且只求值一次，破坏响应性）。同时插件会收集组件内所有标识符，为生成的变量选择不与现有代码冲突的名字（__img、__img_1、__img_2…）。snapshot 测试专门断言了{@const __img_1 = get_image(i)}、{@const __img_2 = get_image(j)}、{@const __img_3 = foo ? manual_image1 : manual_image2}的存在以及不会生成{@const ... = src}之类多余缓存（test/markup-plugin.spec.js）。

5.3 属性简写与混合场景

• 属性简写：<enhanced:img {src} alt="..." />会被识别为表达式形式并走动态分支（见 test/Input.svelte 与输出中的分支结构）。
• 条件/成员表达式：src={foo ? a : b}、src={object.image}同样被当作动态选图处理，自动生成缓存变量（对应输出见 test/Output.svelte）。
• 非可优化格式的动态导入（如./no.png不带?enhanced）：typeof image === 'string'分支直接兜底渲染<img src={image} />，这正是测试中images数组场景的行为。

六、路径解析与别名

<enhanced:img>的src遵循 Svelte/Vite 的资源解析规则，官方测试覆盖了多种写法（test/Input.svelte）：

<!-- 相对路径 --> <enhanced:img src="./dev.png" alt="dev test" /> <!-- 别名 #lib（SvelteKit 新增，等价于原 $lib） --> <enhanced:img src="#lib/dev.png" alt="alias test" /> <!-- 绝对路径（项目根） --> <enhanced:img src="/src/dev.png" alt="absolute path test" />

值得注意的是 CHANGELOG 中记录了$lib别名到#lib的文档级替换（chore: replace the $lib alias with #lib in docs），即当前推荐使用#lib形式的别名（对应 types/index.d.ts 中的示例）。

6.1 解析失败时的错误提示

若图片无法解析，插件会区分两种情况抛出带指引的错误（src/vite-plugin.js）：

• 文件位于publicDir（即static/）时：提示"Please move it to be located relative to the page in the routes directory or reference it beginning with /static/"——放在static/里的图片不会经过处理管线，请移到路由目录附近或按 Vite 资源规范引用；
• 其他情况：提示参考 Vite 文档中关于资源引用的说明。

七、构建与测试验证

7.1 单元测试：markup-plugin snapshot

test/markup-plugin.spec.js 使用 vitest 对image_plugin做快照测试：用一个 mock 的vite-imagetools实例分别模拟 dev / prod 两种产物（prod 使用__VITE_ASSET__...哈希），验证：

• 转换结果可通过svelte/compiler的compile重新编译（expect(() => compile(transformed_code, { filename })).not.toThrow()）；
• 生成的{@const}缓存变量名符合预期；
• 输出与 test/Output.svelte 快照一致；
• parse_object能解析压缩与非压缩两种形式的Picture对象文本。

7.2 集成测试：basics 示例应用

test/apps/basics 是一个可直接运行的 SvelteKit 示例应用，其 vite.config.js 通过相对路径引用../../../src/index.js引入enhancedImages()，页面 src/routes/+page.svelte 同时覆盖了标准位图（birds.jpg）、SVG、动态?enhanced导入三种场景，可用作你接入时的最小参考实现。

运行测试的命令（见 package.json）：

pnpm test:unit # 运行 vitest 单元测试 pnpm test:integration # 运行 Playwright 集成测试

八、限制与注意事项

1. 实验性版本：1.0.0-next.x，minor 版本即可能引入破坏性变更，升级前务必查阅 CHANGELOG。
2. 环境要求严格：Node >= 22、Vite >= 8.0.12、Svelte 5、@sveltejs/vite-plugin-svelte7（peer 依赖声明于 package.json）。
3. static/目录中的图片不会被处理：需要优化请放到路由目录附近或使用资源导入规范。
4. WebContainer 环境静默禁用：process.versions.webcontainer存在时enhancedImages()返回空数组（src/index.js）。
5. 动态选图必须?enhanced：字符串型动态src不会自动增强，需要显式import img from '...?enhanced'。
6. SVG 等非位图：不会被转换，但会自动补尺寸属性；AVIF/WebP 等输出格式与回退策略由fallback_format决定，且格式列表不可直接配置（源码 TODO 注释明确"formats or sizes configurable"仍待实现，见 src/index.js）。

结语

@sveltejs/enhanced-img把"响应式图片"从手工劳动变成了一行组件：静态src全自动转<picture>+ 多格式 + 多尺寸，动态场景用?enhanced导入Picture对象配合运行时分支渲染，sizes/width属性则直接驱动w/x两种描述符策略。虽然它仍处于实验阶段、对依赖版本要求苛刻，但构建期优化的思路（零运行时开销、天然支持 AVIF/WebP 降级、自动补尺寸防布局偏移）使其成为 SvelteKit 项目处理图片资源的低成本高收益方案。建议在真实项目引入前，先对照 test/apps/basics 示例验证你所需的图片格式与路径写法。

• Web框架
• 后端
• 前端