# @desource/image-svelte 中文文档

规范地址：https://npmcn.com/package/%40desource/image-svelte/

版本：0\.5\.0
npm 元数据更新时间：2026-10-31T16:16:08.799Z
中文译文更新时间：2026-11-12T01:36:42.919Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40desource/image-svelte
原文对照：https://npmcn.com/package/%40desource/image-svelte/?lang=original
项目主页：https://github.com/DeSource-Labs/image#readme
源码仓库：https://github.com/DeSource-Labs/image

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：69.4 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：ipx ^3\.1\.1 \|\| ^4\.0\.0-beta\.1，vite ^6\.0\.0 \|\| ^7\.0\.0 \|\| ^8\.0\.0，svelte ^5\.29\.0
- 首次发布：2026-09-07T12:45:24.844Z
- 最新版本发布：2026-10-31T16:16:08.377Z
- 近 30 天下载量：17239（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Svelte和SvelteKit的高质量图像优化,具有响应性输出,部署意识提供者选择,数十个内置提供者模块,以及IPX.

## 安装

```sh
npm install @desource/image-svelte
```

也可以使用：`pnpm add @desource/image-svelte`、`yarn add @desource/image-svelte`、`bun add @desource/image-svelte`

## README

# 来源图像  
Svelte 和 SvelteKit 优化图像

**Svelte和SvelteKit的高质量图像优化,具有响应性,供应商第一和SSR友好的工作流程.**

[![npm version](https://img.shields.io/npm/v/@desource/image-svelte?color=blue&logo=svelte)](https://www.npmjs.com/package/@desource/image-svelte) [![Coverage](https://codecov.io/gh/DeSource-Labs/image/branch/main/graph/badge.svg)](https://codecov.io/gh/DeSource-Labs/image) [![SonarCloud](https://sonarcloud.io/api/project_badges/measure?project=DeSource-Labs_image&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DeSource-Labs_image) [![Ask Context7](https://img.shields.io/badge/Ask%20Context7-059669.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHZpZXdCb3g9IjAgMCAyOCAyOCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTI0IDBINEMxLjc5MDg2IDAgMCAxLjc5MDg2IDAgNFYyNEMwIDI2LjIwOTEgMS43OTA4NiAyOCA0IDI4SDI0QzI2LjIwOTEgMjggMjggMjYuMjA5MSAyOCAyNFY0QzI4IDEuNzkwODYgMjYuMjA5MSAwIDI0IDBaIiBmaWxsPSIjRjdGMkU4IiBmaWxsLW9wYWNpdHk9IjAuNjUiLz4KPHBhdGggZD0iTTEwLjYgMTUuMjk5MkMxMC42IDE3LjQ5OTIgOS43MDAwNSAxOS4zOTkyIDguMjAwMDUgMjEuMDk5MkgxMS42VjIyLjc5OTJINi4zMDAwNVYyMS4xOTkyQzguMDAwMDUgMTkuMzk5MiA4LjYwMDA1IDE3Ljg5OTIgOC42MDAwNSAxNS4yOTkySDEwLjZaTTE3LjQgMTUuMjk5MkMxNy40IDE3LjQ5OTIgMTguMyAxOS4zOTkyIDE5LjggMjEuMDk5MkgxNi40VjIyLjc5OTJIMjEuN1YyMS4xOTkyQzIwIDE5LjM5OTIgMTkuNCAxNy44OTkyIDE5LjQgMTUuMjk5MkgxNy40Wk0xMC42IDEyLjY5OTJDMTAuNiAxMC40OTkyIDkuNzAwMDUgOC41OTkyMiA4LjIwMDA1IDYuODk5MjJIMTEuNlY1LjE5OTIySDYuMzAwMDVWNi43OTkyMkM4LjAwMDA1IDguNTk5MjIgOC42MDAwNSAxMC4wOTkyIDguNjAwMDUgMTIuNjk5MkgxMC42Wk0xNy40IDEyLjY5OTJDMTcuNCAxMC40OTkyIDE4LjMgOC41OTkyMiAxOS44IDYuODk5MjJIMTYuNFY1LjE5OTIySDIxLjdWNi43OTkyMkMyMCA4LjU5OTIyIDE5LjQgMTAuMDk5MiAxOS40IDEyLjY5OTJIMTcuNFoiIGZpbGw9ImJsYWNrIi8+Cjwvc3ZnPgo=)](https://context7.com/desource-labs/image) [![Ask DeepWiki](https://img.shields.io/badge/Ask%20DeepWiki-1c398e.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCIgZmlsbD0iI2NiY2JjYiIgYXJpYS1oaWRkZW49InRydWUiPjxwYXRoIGQ9Ik0xOC42IDIwLjFxMS0uNiAyLjItLjZoLjNhNCA0IDAgMCAxIDIgLjdoLjJ2LjFsMSAxaC4xdi4yaC4xbC4xLjF2LjFxLjcgMSAuNyAyLjN0LS42IDIuMnYuMWwtLjIuMkE0IDQgMCAwIDEgMjMgMjhoLS4ydi4xbC0xLjQuNGgtLjVxLTEuMyAwLTIuMy0uNWwtNC4xLTIuNC04LjMgNC44djkuNWw4LjMgNC44IDguMi00LjhWMzVxMC0xLjIuNi0yLjJ2LS4xbC4yLS4yYTQgNCAwIDAgMSAxLjctMS41bDEuMy0uNGguNnExLjMgMCAyLjMuNmw0LjIgMi4zIDguMi00Ljd2LTkuNmwtOC4yLTQuNy00LjIgMi4zcS0xIC42LTIuMi42aC0uM2E0IDQgMCAwIDEtMi0uNmwtLjItLjEtMS0xaC0uMXYtLjJoLS4xbC0uMS0uMnYtLjFxLS43LTEtLjctMi4yVjguMmwtOC4yLTQuNy04LjMgNC43djkuNWw4LjIgNC44eiIvPjwvc3ZnPg==)](https://deepwiki.com/DeSource-Labs/image) [![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/DeSource-Labs/image/blob/main/LICENSE)

AI协助开发将想法迅速转移到工作产品. DeSource Image将图像准备保留在该开发回路内. 添加一个合适的本地或远程源,然后用组件道具控制其输出.

保留 `/img/hero.jpg` 而不是导出 `hero-480.webp`, (中文(简体) ), `hero-960.webp`,以及 `hero-1600.webp`。DeSource Image 将一个图像输入到提供者 URL,响应 `srcset`, (中文(简体) ), `<picture>` 源,占位符,预装元数据,预设,别名,源验证,以及本地IPX路由.

对于MVP和日常产品开发,图像质量成为了代码编辑. 变动 `quality={80}` 改为 `quality={65}` 并保留相同的源文件、组件和 URL.

`@desource/image-svelte` 使本地图像标记不包含包装元素,并提供组件,动作,Svelte 5.29+附件,SSR道具帮助器,Vite dev/preview中间软件,以及生产服务器处理器. 本地路径和动态URL使用相同的组件 API.

提供者配置是可选的 。 在Vercel,Netlify,或AWS Amplify上,DeSource图像从部署环境中选择平台图像服务. 在其它任何地方,它会倒回内置的IPX路径. 明确提供商总是赢.

套件在使用附件时需要Svelte 5.29或更新. 部件和行动需要Svelte 5.

## 为什么Svelte的Desource图像?

斯维尔特基特的 `@sveltejs/enhanced-img` 是一个用于导入本地文件的强大的构建时间工具。 DeSource Image按需要转换本地图像并接受来自一个CMS,数据库,API,对象商店,CDN,或用户通过同一组件API上传的源.

-   **已建成快速产品迭代.** 改变斯维尔特的图像质量,格式,裁剪,或响应大小. 源文件和文件名保持不变.
-   **本地和动态来源.** 使用本地路径, CMS 响应, 数据库值, API 结果, 对象存储 URL, CDN URL, 或者用户上传相同组件道具.
-   **部署意识提供者选择.** 离开 `provider` 打开 `auto`. DeSource Image可探测Vercel,Netlify,或AWS 放大并用于本地环境或其他环境.
-   **原生框架 API.** 使用组件,动作,Svelte 5附件,片段,或SSR道具帮助器. 产出仍属本地 `<img>` 财务报告和审定财务报表 `<picture>` 标记.
-   **数十个内置供应商模块.** 导入一个提供者子路径, 使用完整的注册, 或注册一个输入的自定义提供者 .
-   **内建局部优化器.** Vite中相软件和SvelteKit服务器处理器可以在没有单独图像服务的情况下服务IPX转换.
-   **反应图像和现代格式.** 生成宽度或密度候选人, 断点意识 `sizes`,命令 AVIF/WebP 源头,以及倒置图像.

### 如何比较

| 选项 | 最适合 | 如何选择优化 | 选择来源图像时 |
| --- | --- | --- | --- |
| [`@sveltejs/enhanced-img`](https://svelte.dev/docs/kit/images) | 在Vite建造期间改变的静态当地资产 | 图像在构建时处理. 部署目标不会将其切换到运行时间图像服务. | 您希望本地图像按需转换以节省时间 。 您的图像来自 CMS, 数据库, API, 对象商店, 或 CDN, 或者同一源码应该在当地使用 IPX , 而部署平台的优化器在生产中 . |
| [无相斯维尔特](https://unpic.pics/img/svelte/) | 在可识别的 CDN 或 CMS URL 上已托管的跨框架响应图像 | 检测每个提供者 `src` URL (中文(简体) ). 本地或未知来源需要倒置或明示提供者;部署本身不是选择信号. | Vercel, Netlify, 或 AWS Amplify 应为每个源选择优化器, 包括相对路径, 您还需要预设, 化名, 源规则, `<picture>`,或服务器适配器. |

使用 `enhanced:img` 当每个图像在构建时间被导入时, 您想要在构建期间生产的所有变体, 没有运行时间优化器 。 为按需转换的本地图像选择DeSource图像,动态源,或者在部署后进行优化.

## 安装

```sh
npm install @desource/image-svelte
```

安装 `ipx` 当应用程序服务于本地时 `/_ipx` 开发、预览或生产中的转换:

```sh
npm install ipx
```

保留 `ipx` 在使用生产服务器适配器时生产依赖性。 当每个图像使用主机提供者时是可选的. 添加 `@desource/image` (a) 只有在申请提供商从它进口工厂或公用事业时,才构成直接依赖.

## 配置斯维尔特基特

安装后添加 Vite 集成 `ipx`数字 :

```ts
// vite.config.ts
import { dsImage } from '@desource/image-svelte/vite';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [dsImage({ dirs: ['static'] }), sveltekit()]
});
```

插件服务 `/_ipx` 中。 它还能将检测到的提供者烘烤成客户端和服务器捆绑,使水分使用同一种提供者.

当需要默认、预设、别名或验证规则时,在根布局中设定共享配置:

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { setDsImageConfig } from '@desource/image-svelte';
  import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

  setDsImageConfig({
    provider: 'cloudinary',
    quality: 80,
    screens: { sm: 640, md: 768, lg: 1024 },
    domains: ['images.example.com'],
    providers: {
      cloudinary: cloudinaryProvider({ cloudName: 'demo' })
    },
    presets: {
      avatar: { width: 96, height: 96, fit: 'cover', format: 'webp' }
    }
  });

  let { children } = $props();
</script>

{@render children()}
```

配置通过斯维尔特上下文继承,每配置对象一次解决. 在没有明确提供者的情况下,共享运行时间从构建环境检测出Vercel,Netlify,或AWS Amplify,并倒回IPX.

## Dsimage 组件

```svelte
<script lang="ts">
  import { DsImage } from '@desource/image-svelte';

  let loaded = $state(false);
</script>

<DsImage
  src="/img/hero.jpg"
  alt="Aurora above a mountain lake"
  width={1600}
  height={900}
  sizes="100vw md:50vw lg:800px"
  format="webp"
  quality={82}
  placeholder
  preload={{ fetchPriority: 'high' }}
  class="hero"
  onload={() => (loaded = true)}
/>
```

`alt` 需要时间。 原生图像属性和斯维尔特事件属性通过生成 `<img>`。 。 。 .

## DsPicture 组件

```svelte
<script lang="ts">
  import { DsPicture } from '@desource/image-svelte';
</script>

<DsPicture
  src="/img/hero.jpg"
  alt="Responsive mountain landscape"
  width={1600}
  height={900}
  sizes="100vw md:50vw lg:800px"
  formats={['avif', 'webp']}
  fallbackFormat="jpg"
  class="hero-frame"
  imgAttrs={{ class: 'hero' }}
/>
```

这让本地人 `<picture>`, (中文(简体) ), `<source>`,以及 `<img>` 要素。 逗号分隔 `format="avif,webp"`数组 `format`,则 `legacyFormat` 支持别名.

## 自定义渲染片段

使用 `custom` 与 `children` 当图像需要自定义标记的同时保留生成的属性和占位符状态时片断 :

```svelte
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder custom>
  {#snippet children({ imgAttrs, src, isLoaded })}
    <figure data-src={src} data-loaded={isLoaded}>
      <img {...imgAttrs} />
      <figcaption>Mountain lake</figcaption>
    </figure>
  {/snippet}
</DsImage>
```

## 为本地要素采取的行动

动作对常态元素提供相同的反应行为:

```svelte
<script lang="ts">
  import { dsImageAction, dsPictureAction } from '@desource/image-svelte';

  let width = $state(720);
  const imageOptions = $derived({
    src: '/img/card.jpg',
    alt: 'A coastal village',
    width,
    height: 480,
    densities: '1x 2x',
    placeholder: true
  });
</script>

<img alt="A coastal village" use:dsImageAction={imageOptions} />

<picture
  use:dsPictureAction={{
    src: '/img/card.jpg',
    alt: 'A coastal village at sunset',
    width,
    height: 480,
    formats: ['avif', 'webp']
  }}
>
  <img alt="A coastal village at sunset" />
</picture>
```

图片动作需要回落一次 `<img>` 并管理生成 `<source>` 周围的元素.

## Svelte 5.29+附件

附件以斯维尔特更新的元素生命周期 API 曝光了同一引擎:

```svelte
<script lang="ts">
  import { dsImageAttachment, dsPictureAttachment } from '@desource/image-svelte';
</script>

<img
  alt="Mountain lake"
  {@attach dsImageAttachment({
    src: '/img/hero.jpg',
    alt: 'Mountain lake',
    width: 960,
    format: 'webp'
  })}
/>

<picture
  {@attach dsPictureAttachment({
    src: '/img/hero.jpg',
    alt: 'Mountain lake',
    width: 960,
    formats: ['avif', 'webp']
  })}
>
  <img alt="Mountain lake" />
</picture>
```

动作和附件支持更新、加载/反调、占位符解码、分类清理和 `onStateChange`。 。 。 .

## 一次绑入一个配置

使用 `createDsImageBindings()` 当多个本地元素共享一个明确的配置时:

```svelte
<script lang="ts">
  import { createDsImageBindings, createDsImageConfig } from '@desource/image-svelte';

  const config = createDsImageConfig({ provider: 'ipx' });
  const { dsImageAction, dsImageAttachment, dsPictureAction, dsPictureAttachment } = createDsImageBindings(config);
</script>
```

返回的职能不再需要 `config` 字段中的每个选项对象.

## SSR 道具助手

`getDsImageProps()` 财务报告和审定财务报表 `getDsPictureProps()` 生成未安装组件的已键入的本地属性。 它们在片段、安全部门改革产出和一体化方面是有用的:

```ts
import { getDsImageProps, getDsPictureProps } from '@desource/image-svelte';

const image = getDsImageProps({
  src: '/img/hero.jpg',
  alt: 'Hero',
  width: 800,
  format: 'webp'
});

const picture = getDsPictureProps({
  src: '/img/hero.jpg',
  alt: 'Hero',
  width: 800,
  formats: ['avif', 'webp']
});
```

过 `true` 当完整图像已装入且配置了占位符时,应当跳过第二个参数.

## 响应图像、占位符和预装

`sizes` 接受断点字符串, 如 `100vw sm:50vw lg:600px` 或记录. `densities` 接受字符串、数字或数组。 被选中的供应商的候选宽度被简化并正常化.

```svelte
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder placeholderClass="blur" />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder={[48, 32, 25, 8]} />
<DsImage src="/img/hero.jpg" alt="Hero" width={1200} placeholder="data:image/png;base64,..." />
```

-   布尔占位符生成一个小的被转换的图像.
-   拖倒控制了宽度、高度、质量和模糊度.
-   完整图像仅在解码成功后替换占位符.
-   `placeholderClass` 仅存在于占位符可见时.
-   `preload` 插入响应 `<link rel="preload" as="image">` 输入标题和引用计数重复链接.
-   `priority` 设置急速装入和高优先级。 使用 `preload` 当需要头链接时.

安全部门改革和初步水合产出是决定性的.

## 可调用图像助手

```svelte
<script lang="ts">
  import { useDsImage } from '@desource/image-svelte';

  const $img = useDsImage();
  const hero = $img('/img/hero.jpg', { width: 800, format: 'webp', quality: 75 });
</script>
```

可调用帮助者暴露 `getImage`, (中文(简体) ), `getSizes`, (中文(简体) ), `getMeta`, (中文(简体) ), `getAttrs`, (中文(简体) ), `getPicture`, (中文(简体) ), `getPreloadLink`,并配置了预设快捷键.

## 供应商和预设

在共享配置中注册内置或自定义提供者 :

```svelte
<script lang="ts">
  import { cloudinaryProvider } from '@desource/image/providers/cloudinary';
  import { setDsImageConfig } from '@desource/image-svelte';

  setDsImageConfig({
    provider: 'cloudinary',
    providers: {
      cloudinary: cloudinaryProvider({ cloudName: 'demo' })
    },
    presets: {
      avatar: { width: 96, height: 96, fit: 'cover', quality: 80 }
    }
  });
</script>
```

```svelte
<DsImage preset="avatar" src="/users/ada.jpg" alt="Ada" />
```

供应商模块和定制供应商公用事业记录如下: [`@desource/image`](https://github.com/DeSource-Labs/image/tree/main/packages/core)。 。 。 .

## 生产部署

Vite插件只向Vite开发和预览服务器提供最优化的中间软件. 生产必须使用平台图像端点或安装IPX服务器适配器.

### Vercel 本地图像

配置 `@sveltejs/adapter-vercel` 因此它的构建输出 API 包含图像设置 :

```js
// svelte.config.js
import adapter from '@sveltejs/adapter-vercel';

export default {
  kit: {
    adapter: adapter({
      images: {
        sizes: [640, 768, 1024, 1280, 1536],
        domains: ['images.example.com'],
        minimumCacheTTL: 2678400,
        formats: ['image/avif', 'image/webp'],
        dangerouslyAllowSVG: false
      }
    })
  }
};
```

在Vercel上建造时,自动检测发射 `/_vercel/image` URLs (英语). 保持适配器图像大小并允许与应用程序配置相匹配的远程域.

### 生产 IPX 的 SvelteKit

安装 `ipx` 作为生产依赖并添加服务器钩:

```ts
// src/hooks.server.ts
import { createDsImageHandle } from '@desource/image-svelte/server';

export const handle = createDsImageHandle({
  dirs: ['static'],
  domains: ['images.example.com'],
  maxAge: 60 * 60 * 24 * 30
});
```

`createDsImageWebHandler()` 可用于其他获取 API 服务器,以及 `createDsImageNodeMiddleware()` 用于连接/Express风格的节点服务器.

所有IPX适配器都以懒散的方式加载优化器,只在所配置的路径下处理请求. 远程优化默认被拒绝 。 添加可信赖 `domains`,或设置 `allowAllDomains: true` 仅供有意公开优化者使用.

## 链接

-   [仓库](https://github.com/DeSource-Labs/image)
-   [核心一揽子计划](https://github.com/DeSource-Labs/image/tree/main/packages/core)
-   [角软件包](https://github.com/DeSource-Labs/image/tree/main/packages/angular)
-   [反应软件包](https://github.com/DeSource-Labs/image/tree/main/packages/react)
-   [SvelteKit 图像文件](https://svelte.dev/docs/kit/images)
-   [安全政策](https://github.com/DeSource-Labs/image/blob/main/SECURITY.md)

## 许可证

麻省理工学院,2026年

## 常见问题

### @desource/image-svelte 是什么？

Svelte和SvelteKit的高质量图像优化,具有响应性输出,部署意识提供者选择,数十个内置提供者模块,以及IPX\.

### 如何安装 @desource/image-svelte？

在项目目录运行 npm install @desource/image-svelte，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.29\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @desource/image-svelte 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @desource/image-svelte 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @desource/image-svelte 可以商用吗？

@desource/image-svelte 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @desource/image-svelte 的下载量有多少？

根据 npm 官方下载统计，@desource/image-svelte 在 2026/10/12 – 2026/11/10 这 30 天内被下载 17,239 次，日均约 575 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @desource/image-svelte 还在维护吗？

最新版本 0\.5\.0 发布于 2026/11/01（11 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/09/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。