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。 。 。 .

安装

npm install @desource/image

快开始

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,每个配置的预设都有一个快捷键.

它会产生什么

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

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。 。 。 .

配置

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一次检测部署环境并选择其图像后端:

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

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

源验证

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

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

无效的源策略 :

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

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

响应输出

支助 sizes 窗体:

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

对象语法也被接受 :

{
  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

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

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

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

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.

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 包含框架软件包所使用的小助手 :

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

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

警卫

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

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

链接

• 仓库
• 角软件包
• 反应软件包
• Svelte 软件包
• 安全政策

许可证

麻省理工学院,2026年