# @desource/image-react 中文文档

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

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

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

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

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

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

## 中文简介

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

## 安装

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

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

## README

# 来源图像  
React and Next.js 优化图像

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

[![npm version](https://img.shields.io/npm/v/@desource/image-react?color=blue&logo=react)](https://www.npmjs.com/package/@desource/image-react) [![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-react` 为常见情况提供组件,为应用程序自有标记提供钩子,为 `next/image`,以及 Vite 和 Next.js App 路由器的服务器助手。 每一个API 使或供应本地 `<img>` 财务报告和审定财务报表 `<picture>` 标记.

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

## 反应为什么是源代码图像?

React没有内置图像优化层. Next.js对于Next-Online应用有强大的图像管道. DeSource Image增加了部署意识提供者选择,内置提供者模块,本地IPX,以及也可以在Next.js之外工作的图像规则.

-   **已建成快速产品迭代.** 改变JSX中的图像质量,格式,收成,或响应大小. 源文件和文件名保持不变.
-   **一个源而不是导出变体.** 从一个合适的图像开始,生成每个屏幕所需的宽度和格式.
-   **部署意识提供者选择.** 离开 `provider` 打开 `auto`. DeSource Image可探测Vercel,Netlify,或AWS 放大并用于本地环境或其他环境.
-   **Vite和Next.js使用相同的图像模型.** 保留相同的输入,预设,化名,以及跨应用程序的提供者.
-   **原生框架 API.** 使用 `DsImage` 财务报告和审定财务报表 `DsPicture`,或将钩子结果传播到设计系统拥有的元素上。 产出仍属本地 `<img>` 财务报告和审定财务报表 `<picture>` 标记.
-   **数十个内置供应商模块.** 导入一个提供者子路径, 使用完整的注册, 或注册一个输入的自定义提供者 .
-   **内建局部优化器.** Vite Middreware和一款Next.js App Router路由处理器服务于IPX的变换,没有单独的图像服务.
-   **`next/image` 现保留.** `createNextImageLoader()` 在DeSource Image 拥有供应商 URL 时, 允许 Next 自己渲染 .

### 如何比较

| 选项 | 最适合 | 如何选择优化 | 选择来源图像时 |
| --- | --- | --- | --- |
| 反应 `<img>` | 应用程序拥有标记和 URL 时的本地浏览器图像 | 没有选择优化器 。 浏览器请求 `src` 不变;部署到Vercel、Netlify或Amplify不会重写. | 您想要控制组件代码中的响应大小、格式和质量, 而不是导出变体或维护 `srcset` 财务报告和审定财务报表 `<picture>` 标记。 您还需要占位符, 预装, 以及一个跟踪部署的优化器 . |
| [`next/image`](https://nextjs.org/docs/app/api-reference/components/image) | 使用 Next.js 图像管道的下限应用程序 | Next.js默认优化器. Vercel、Netlify和AWS 放大集成 `next/image` 与他们的托管管道。 对于其他图像服务,Next.js提供自定义装入器API而非提供商目录. | 您想要更广泛的内置提供者支持而不替换组件, 或提供者政策, 预设, 化名, 源规则必须在框架、 主机和图像服务之间保持稳定 . |
| [无图片反应](https://unpic.pics/img/react/) | 在可识别的 CDN 或 CMS URL 上已托管的跨框架响应图像 | 检测每个提供者 `src` URL (中文(简体) ). 本地或未知来源需要倒置或明示提供者;部署本身不是选择信号. | Vercel, Netlify, 或 AWS Amplify 应为每个源选择优化器, 包括相对路径, 您还需要预设, 化名, 源规则, `<picture>`,或服务器适配器. |

对于下一个应用程序, `next/image` 仍为好人选. DeSource Image是更强的选择,当主机本地工作流程必须延伸到Next.js以外,或者当提供者政策,预设,化名,源规则必须在框架,主机和图像服务之间保持稳定.

## 安装

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

安装 `ipx` 只有在应用程序服务于本地时 `/_ipx` 转换本身:

```sh
npm install ipx
```

`ipx`, (中文(简体) ), `vite`,以及 `next` 是可选的同龄人。 由Vercel,Netlify,Cloudinary,Imgix,Sanity等主机提供商或ImageKit不需要本地优化器.

## 快开始

```tsx
import { DsImage, DsPicture } from '@desource/image-react';

export function Gallery() {
  return (
    <>
      <DsImage
        src="/img/hero.jpg"
        alt="Mountain lake at sunrise"
        width={1600}
        height={1000}
        sizes="100vw md:760px"
        format="webp"
        quality={76}
        placeholder
        preload={{ fetchPriority: 'high' }}
        className="hero"
      />

      <DsPicture
        src="/img/card.jpg"
        alt="Cabin under the stars"
        width={960}
        height={640}
        formats={['avif', 'webp']}
        fallbackFormat="jpg"
        imgAttrs={{ className: 'card-image' }}
      />
    </>
  );
}
```

这两个组成部分都具有原生要素. `DsImage` 转发 `<img>`· ; `DsPicture` 转发 `<picture>`。 。 。 .

## 配置一次

```tsx
import { DsImageProvider } from '@desource/image-react';
import { cloudinaryProvider } from '@desource/image/providers/cloudinary';

export function App() {
  return (
    <DsImageProvider
      config={{
        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' }
        }
      }}
    >
      <Gallery />
    </DsImageProvider>
  );
}
```

配置是可选的 。 在没有明确提供者的情况下,共享运行时间从构建环境检测出Vercel,Netlify,或AWS Amplify,并倒回IPX.

## Dsimage 组件

```tsx
import { DsImage } from '@desource/image-react';

export function Hero() {
  return (
    <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' }}
      className="hero"
      onLoad={() => console.log('loaded')}
    />
  );
}
```

`alt` 需要时间。 反应-内生道具,例如: `className`, (中文(简体) ), `style`, (中文(简体) ), `crossOrigin`, (中文(简体) ), `fetchPriority`, (中文(简体) ), `referrerPolicy`, (中文(简体) ), `onLoad`,以及 `onError` 被支持。 小写 `fetchpriority` 财务报告和审定财务报表 `crossorigin` 在跨框架共享选项时也接受别名.

## DsPicture 组件

```tsx
import { DsPicture } from '@desource/image-react';

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

该部分使本地 `<picture>` 命令 `<source>` 元素和倒置 `<img>`。逗号分离 `format="avif,webp"`数组 `format`,则 `legacyFormat` 支持别名.

## 本地标记的钩子

当设计-系统组件或应用程序模板必须拥有最后的 DOM 时使用钩:

```tsx
import { useDsImageProps, useDsPictureProps } from '@desource/image-react';

function NativeImage() {
  const img = useDsImageProps({
    src: '/img/card.jpg',
    alt: 'A coastal village',
    width: 720,
    height: 480,
    placeholder: true,
    className: 'card-image'
  });

  return <img {...img} />;
}

function NativePicture() {
  const picture = useDsPictureProps({
    src: '/img/card.jpg',
    alt: 'A coastal village at sunset',
    width: 720,
    height: 480,
    formats: ['avif', 'webp'],
    fallbackFormat: 'jpg',
    imgAttrs: { className: 'card-image' }
  });

  return (
    <picture {...picture.pictureProps}>
      {picture.sources.map((source) => (
        <source key={`${source.type}:${source.srcSet}`} {...source} />
      ))}
      <img {...picture.imgProps} />
    </picture>
  );
}
```

钩子处理占位符预加载/解码状态,加载/误入转发,并用引用计数处理头前加载链接.

## 自定义渲染

使用 `custom` 当生成的图像道具应在自定义标记内提供时:

```tsx
import { DsImage } from '@desource/image-react';

export function Figure() {
  return (
    <DsImage src="/img/hero.jpg" alt="Mountain lake" width={1200} placeholder custom>
      {({ imgProps, src, isLoaded }) => (
        <figure data-src={src} data-loaded={isLoaded}>
          <img {...imgProps} />
          <figcaption>Mountain lake</figcaption>
        </figure>
      )}
    </DsImage>
  );
}
```

## 可调用助手

```tsx
import { useDsImage } from '@desource/image-react';

function Avatar({ src }: { src: string }) {
  const image = useDsImage();
  return <img src={image(src, { width: 96, height: 96, fit: 'cover' })} alt="" />;
}
```

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

## 下一个.js

### 直接使用脱源图像组件

主包条目是一个客户端条目,因为占位符和头部预装使用浏览器生命周期API.

```tsx
'use client';

import { DsImage } from '@desource/image-react';

export function ProductImage() {
  return <DsImage src="/products/chair.jpg" alt="Oak chair" width={1200} height={900} format="webp" />;
}
```

对于主机提供者,按常态配置提供者. 对于本地IPX URL,需要添加一个 App Router 路由处理器.

### 使用源代码图像 `next/image`

```ts
// ds-loader.ts
import { createNextImageLoader } from '@desource/image-react/next';

export const dsLoader = createNextImageLoader({
  provider: 'vercel'
});
```

```tsx
import NextImage from 'next/image';
import { dsLoader } from './ds-loader';

export function Hero() {
  return <NextImage loader={dsLoader} src="/img/hero.jpg" alt="Hero" width={1200} height={800} />;
}
```

这样吧 `next/image` 在DeSource Image拥有提供商 URL 规则的同时,保持其渲染行为.

### 应用路由器 IPX 路由

```ts
// app/_ipx/[...path]/route.ts
import { createNextImageRouteHandler } from '@desource/image-react/next';

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

远程优化默认被拒绝 。 添加可信赖 `domains`,或设置 `allowAllDomains: true` 仅供有意公开优化者使用.

## Vite 开发优化器

```ts
// vite.config.ts
import { dsImage } from '@desource/image-react/vite';
import { defineConfig } from 'vite';

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

插件服务 `/_ipx` 在 Vite 开发和预览期间。 它还将一个定型供应商烤成客户端,SSR捆绑则使用同一种供应商进行水分处理.

## 供应商和预设

从核心包注册内置或自定义提供者 :

```tsx
import { DsImageProvider } from '@desource/image-react';
import { imagekitProvider } from '@desource/image/providers/imagekit';

export function App() {
  return (
    <DsImageProvider
      config={{
        provider: 'imagekit',
        providers: {
          imagekit: imagekitProvider({ baseURL: 'https://ik.imagekit.io/demo' })
        },
        presets: {
          card: { width: 960, height: 640, sizes: '100vw md:480px', format: 'webp' }
        }
      }}
    >
      <DsImage preset="card" src="/products/chair.jpg" alt="Oak chair" />
    </DsImageProvider>
  );
}
```

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

## 链接

-   [仓库](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)
-   [Svelte 软件包](https://github.com/DeSource-Labs/image/tree/main/packages/svelte)
-   [Next.js 图像优化文件](https://nextjs.org/docs/app/getting-started/images)
-   [安全政策](https://github.com/DeSource-Labs/image/blob/main/SECURITY.md)

## 许可证

麻省理工学院,2026年

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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

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

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