# @desource/image 中文文档

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

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

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

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

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

- 包体积（解压后）：602 kB，256 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-09-07T12:45:21.938Z
- 最新版本发布：2026-10-31T16:16:03.072Z
- 近 30 天下载量：16600（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

框架独立图像优化 具有响应输出,部署意识选择,预设,化名,IPX,以及数十个内置提供商模块.

## 安装

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

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

## README

# 来源图像  
框架独立图像优化

**`@desource/image` 为任何JavaScript运行时间提供 URL 生成,应答属性,图片源,配置,预设,化名,以及提供者工具.**

[![npm version](https://img.shields.io/npm/v/@desource/image?color=blue&logo=typescript)](https://www.npmjs.com/package/@desource/image) [![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`。核心引擎生成提供者 URL,响应 `srcset` 数据, `<picture>` 源、占位符和预装元数据,然后应用预设、别名和源验证.

对于MVP和日常产品开发,图像质量成为了代码编辑. 变动 `quality: 80` 改为 `quality: 65` ,并在应用程序代码中保留相同的源文件、帮助呼叫和 URL.

`@desource/image` 赋予Angular,React,和Svelte包的权力,但它不依赖于DOM或框架渲染器. 在需要相同的图像 URL 和响应输出规则的地方使用它:服务器模板,工人,元数据管道,电子邮件,设计系统,或自定义组件.

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

## 为什么直接使用核心包?

使用 `@desource/image` 当图像规则应活在一个组件上方时:

-   更改代码中的图像质量、格式、裁剪或响应大小,而源和文件名保持不变.
-   从一个合适的图像开始,生成每个屏幕所需的宽度和格式.
-   生成一个 URL 或完成 `src`, (中文(简体) ), `srcset`, (中文(简体) ), `sizes`, (中文(简体) ), `<picture>`、占位符和预装数据.
-   让部署中选择Vercel,Netlify,或AWS Amplify,为本地环境和其他环境使用IPX.
-   共享部署检测,提供者配置,预设,化名,以及源规则横跨Angular,React,Svelte,工人,和节点脚本.
-   创建可调用 `$img` cSS,元数据,画布,OpenGraph图像,电子邮件或CMS预览的帮助者.
-   构建自定义渲染器,不重用宽度候选人,密度候选人,格式倒置,或预装元数据.
-   作者一个打字提供者,并从每个框架包中使用.
-   在到达公共优化器端点之前验证本地和远程源.

如果您仅通过一个框架包渲染图像, 请先安装框架包 。 这已经取决于 `@desource/image`。 。 。 .

## 安装

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

## 快开始

```ts
import { createImage } from '@desource/image';

const image = createImage({
  quality: 76,
  screens: {
    sm: 640,
    md: 768,
    lg: 1024
  },
  presets: {
    avatar: {
      width: 96,
      height: 96,
      fit: 'cover',
      format: 'webp'
    }
  }
});

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

const attrs = image.getAttrs({
  src: '/img/hero.jpg',
  alt: 'Mountain lake',
  width: 1600,
  height: 1000,
  sizes: '100vw md:760px',
  placeholder: true
});

const picture = image.getPicture({
  src: '/img/hero.jpg',
  alt: 'Mountain lake',
  width: 1600,
  height: 1000,
  formats: ['avif', 'webp'],
  fallbackFormat: 'jpg'
});

const avatarUrl = image.avatar('/people/ada.jpg');
```

打电话的帮手也暴露了 `getImage`, (中文(简体) ), `getSizes`, (中文(简体) ), `getMeta`, (中文(简体) ), `getPreloadLink`,每个配置的预设都有一个快捷键.

## 它会产生什么

| API 密码 | 产出 |
| --- | --- |
| `image(src, modifiers)` | 优化 URL 字符串 . |
| `getImage()` | 提供方通过URL结果并优化元数据. |
| `getSizes()` | 正常化 `srcset`, (中文(简体) ), `sizes`,候选宽度,以及描述数据. |
| `getAttrs()` | 土著 `<img>` 属性、占位符 URL 和占位符类. |
| `getPicture()` | 土著 `<picture>` 数据: 命令源外加倒回图像 . |
| `getPreloadLink()` | 响应 `<link rel="preload" as="image">` 属性. |
| `getMeta()` | 当一个提供者或运行时间可以加载时,图像尺寸和元数据. |

在不需要求助者时,可提供无国籍的帮助:

```ts
import { getImageAttrs, getImagePreloadLink, getImageSizes, getPictureAttrs } from '@desource/image';

const attrs = getImageAttrs({
  src: '/img/hero.jpg',
  alt: 'Mountain lake',
  width: 1600,
  height: 1000,
  sizes: '100vw md:760px',
  format: 'webp',
  quality: 76
});
```

其他公共发电机包括: `generateSrcset`, (中文(简体) ), `generatePictureSources`, (中文(简体) ), `generateSizes`, (中文(简体) ), `generateDensities`, (中文(简体) ), `parseSizes`,以及 `parseDensities`。 。 。 .

## 配置

```ts
import type { ImageConfig } from '@desource/image';
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export const config: ImageConfig = {
  provider: 'cloudinary',
  baseURL: '/',
  quality: 76,
  format: 'webp',
  screens: {
    sm: 640,
    md: 768,
    lg: 1024,
    xl: 1280
  },
  densities: [1, 2],
  providerSizes: [320, 480, 640, 768, 1024, 1280, 1536],
  aliases: {
    media: 'https://assets.example.com'
  },
  domains: ['assets.example.com'],
  localPatterns: [{ pathname: '/img/**' }],
  remotePatterns: [{ protocol: 'https', hostname: '*.example.com', pathname: '/media/**' }],
  presets: {
    card: {
      width: 960,
      height: 640,
      sizes: '100vw md:480px',
      format: 'webp'
    }
  },
  providers: {
    cloudinary: cloudinaryProvider({ cloudName: 'demo' })
  },
  providerOptions: {
    cloudinary: {
      modifiers: { quality: 'auto' }
    }
  },
  onInvalidSource: 'warn'
};
```

`resolveImageConfig(config)` 一次就能恢复正常. `createImageContext(config)` 返回已解析的配置加绑定 `getImage`, (中文(简体) ), `getImageAttrs`, (中文(简体) ), `getPictureAttrs`, (中文(简体) ), `getPreloadLink`,以及 `getMeta` 方法。 。 .

### 提供者检测

`provider: 'auto'` 默认值。 DeSource Image一次检测部署环境并选择其图像后端:

| 运行时间 | 提供者 |
| --- | --- |
| 维塞尔 | `vercel` |
| AWS 扩展 | `awsAmplify` |
| 净化 | `netlifyImageCdn` |
| 将大型媒体网化 | `netlifyLargeMedia` |
| 其他/当地 | `ipx` |

一个明确的提供者绕过检测. React和Svelte Vite集成可以将结果编译为客户端和SSR捆绑,防止提供者在水分化过程中漂移.

检测是基于部署,而不是源URL. 这让同一本地路径在生产中使用平台优化器,并在当地开发期间使用IPX. 该包不读取 DeSource Image 特有的环境变量,也不从浏览器主机名推断出提供者.

### 源验证

当一个优化端点只转换已知源时使用源控:

```ts
const config: ImageConfig = {
  domains: ['images.example.com'],
  localPatterns: [{ pathname: '/img/**' }],
  remotePatterns: [{ protocol: 'https', hostname: '*.example.com', pathname: '/media/**' }],
  onInvalidSource: 'throw'
};
```

无效的源策略 :

-   `throw`: 扔出一个错误.
-   `warn`:记录一个警告,并通过源.
-   `passthrough`:通过源头而不进行伐木.

接受模式 `*` 用于一个路径段和 `**` 用于递归匹配.

## 响应输出

支助 `sizes` 窗体:

```text
100vw
sm:100vw md:50vw lg:400px
100vw md:760px
```

对象语法也被接受 :

```ts
{
  sm: '100vw',
  md: '50vw',
  lg: 600
}
```

与 `sizes`,输出使用宽度描述符和提供者大小候选人。 无 `sizes`,一个已知宽度使用密度描述符。 复制最终 URL 被删除, 这对将请求的宽度正常化到配置断点的提供者很重要 .

## 占位符和图片回落

占位符值 :

-   `placeholder: true` → `[10, 10, 50, 3]`
-   `placeholder: 24` • 宽度和高度 `24`
-   `placeholder: [24, 16, 40, 2]` • 自定义宽度、高度、质量、模糊
-   `placeholder: 'data:…'` ~ 直接使用字符串

框架软件包使用生成的 `placeholderSrc` 财务报告和审定财务报表 `placeholderClass` 以显示一个小图像,直到完整图像解码.

图片输出跳过生成源用于SVG输入,避免重复格式,并保持透明安全的PNG倒置行为.

## 供应商

主要条目包括一个小型的默认注册:

-   `ipx`
-   `ipxStatic`
-   `vercel`
-   `awsAmplify`
-   `netlify`
-   `netlifyImageCdn`
-   `netlifyLargeMedia`
-   `none`

仅在需要时导入所有内置提供者模块 :

```ts
import { BUILT_IN_PROVIDER_NAMES, createBuiltInProviders } from '@desource/image/providers';
```

应用程序代码的优先提供者子路径 :

```ts
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';
import { imgixProvider } from '@desource/image/providers/imgix';
import { sanityProvider } from '@desource/image/providers/sanity';
```

提供者模块 :

`aliyun`, (中文(简体) ), `appwrite`, (中文(简体) ), `awsAmplify`, (中文(简体) ), `builderio`, (中文(简体) ), `bunny`, (中文(简体) ), `caisy`, (中文(简体) ), `cloudflare`, (中文(简体) ), `cloudflareimages`, (中文(简体) ), `cloudimage`, (中文(简体) ), `cloudinary`, (中文(简体) ), `contentful`, (中文(简体) ), `contentstack`, (中文(简体) ), `directus`, (中文(简体) ), `edgeonePages`, (中文(简体) ), `fastly`, (中文(简体) ), `filerobot`, (中文(简体) ), `filestack`, (中文(简体) ), `flyimg`, (中文(简体) ), `github`, (中文(简体) ), `glide`, (中文(简体) ), `gumlet`, (中文(简体) ), `hygraph`, (中文(简体) ), `imageengine`, (中文(简体) ), `imagekit`, (中文(简体) ), `imgix`, (中文(简体) ), `imgproxy`, (中文(简体) ), `ipx`, (中文(简体) ), `ipxStatic`, (中文(简体) ), `keycdn`, (中文(简体) ), `netlify`, (中文(简体) ), `netlifyImageCdn`, (中文(简体) ), `netlifyLargeMedia`, (中文(简体) ), `none`, (中文(简体) ), `picsum`, (中文(简体) ), `prepr`, (中文(简体) ), `prismic`, (中文(简体) ), `sanity`, (中文(简体) ), `shopify`, (中文(简体) ), `sirv`, (中文(简体) ), `storyblok`, (中文(简体) ), `strapi`, (中文(简体) ), `strapi5`, (中文(简体) ), `supabase`, (中文(简体) ), `twicpics`, (中文(简体) ), `umbraco`, (中文(简体) ), `unsplash`, (中文(简体) ), `uploadcare`, (中文(简体) ), `vercel`, (中文(简体) ), `wagtail`,以及 `weserv`。 。 。 .

提供方的行为是针对存在可比较的行为的被钉住的"Nuxt Image"包进行对等测试. 框架融合仍然是Angular、React和Svelte的本土.

## 自定义提供者

供应商合同是DeSource Image自己的外形. 它故意小:一个提供者收到一个正态的源,合并的选项,和一个图像上下文,然后返回一个URL.

```ts
import { configureProvider, defineProvider } from '@desource/image';

interface AcmeOptions {
  baseURL: string;
  token?: string;
}

const setup = defineProvider<AcmeOptions>({
  validateDomains: true,
  getImage(src, { modifiers, baseURL, token }, context) {
    const query = new URLSearchParams({
      src,
      width: String(modifiers.width ?? ''),
      quality: String(modifiers.quality ?? '')
    });

    if (token) query.set('token', token);

    return {
      url: `${baseURL}?${query}`,
      isOptimized: true
    };
  }
});

export const acmeProvider = configureProvider(
  setup,
  {
    baseURL: 'https://images.example.com/transform'
  },
  'acme'
);
```

提供商的设置是被纪念的. 每个配置 `providerOptions[name]` 在配置的默认值上合并,标准宽度/高度/质量/格式修改符最后合并。 上下文揭示了已解决的选项和被缅怀的 `$img` 帮手.

设定 `acceptsOpaqueSource: true` 仅针对来源为资产ID而不是路径或URL的提供者. 设定 `validateDomains: true` 当远程输入必须匹配配置时 `domains` 或者说 `remotePatterns`。 。 。 .

### 提供方公用事业

主要出口可重复使用的供应商原始产品:

-   `defineProvider`, (中文(简体) ), `configureProvider`, (中文(简体) ), `resolveProviderRegistration`
-   `createMappedQueryProvider`, (中文(简体) ), `mappedQueryURL`, (中文(简体) ), `mappedModifiers`
-   `pathOperations`, (中文(简体) ), `appendProviderModifiers`, (中文(简体) ), `withStandardParams`
-   `providerBaseURL`, (中文(简体) ), `sourceWithBase`, (中文(简体) ), `sourcePath`, (中文(简体) ), `joinURLParts`
-   `cleanColor`, (中文(简体) ), `formatJpgValue`, (中文(简体) ), `defaultFitValue`
-   `createMapper`, (中文(简体) ), `createOperationsGenerator`
-   `appendQuery`, (中文(简体) ), `stableModifiers`, (中文(简体) ), `normalizeFormat`, (中文(简体) ), `mimeForFormat`

## 框架整合工具包

`@desource/image/kit` 包含框架软件包所使用的小助手 :

```ts
import {
  isResolvedImageConfig,
  mergeClassNames,
  normalizeCrossorigin,
  stripUndefined,
  styleWithPlaceholder
} from '@desource/image/kit';
```

子路径仅限于框架胶. 提供方 URL 逻辑留在主包; 渲染生命周期留在框架包中.

## 警卫

此软件包将验证字符串并生成 URL; 它不会获取远程字节 。 IPX服务器集成生活在框架包中,默认拒绝所有远程域.

对于公共优化端点,请保留 `domains`, (中文(简体) ), `remotePatterns`,供应商宽度列表,以及符合部署配置的质量列表。 使用狭义模式来避免变形滥用.

## 链接

-   [仓库](https://github.com/DeSource-Labs/image)
-   [角软件包](https://github.com/DeSource-Labs/image/tree/main/packages/angular)
-   [反应软件包](https://github.com/DeSource-Labs/image/tree/main/packages/react)
-   [Svelte 软件包](https://github.com/DeSource-Labs/image/tree/main/packages/svelte)
-   [安全政策](https://github.com/DeSource-Labs/image/blob/main/SECURITY.md)

## 许可证

麻省理工学院,2026年

## 常见问题

### @desource/image 是什么？

框架独立图像优化 具有响应输出,部署意识选择,预设,化名,IPX,以及数十个内置提供商模块\.

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

在项目目录运行 npm install @desource/image，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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