# @effected/images 中文文档

规范地址：https://npmcn.com/package/%40effected/images/

版本：0\.10\.0
npm 元数据更新时间：2026-11-10T15:13:06.061Z
中文译文更新时间：2026-11-13T11:44:01.234Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effected/images
原文对照：https://npmcn.com/package/%40effected/images/?lang=original
项目主页：https://github.com/spencerbeggs/effected/tree/main/packages/images#readme
源码仓库：https://github.com/spencerbeggs/effected

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

- 包体积（解压后）：59.8 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.11\.0
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.0
- 首次发布：2026-10-09T17:44:38.655Z
- 最新版本发布：2026-11-10T15:13:03.713Z
- 近 30 天下载量：4145（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

图像事实(格式,MIME类型,维度)来自字节,和一个生成的图像缓存,用于Effect.

## 安装

```sh
npm install @effected/images
```

也可以使用：`pnpm add @effected/images`、`yarn add @effected/images`、`bun add @effected/images`

## README

# @ 受影响/图像

[![npm](https://img.shields.io/npm/v/@effected%2Fimages?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/images) [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT) [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/) [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)

来自字节的图像事实, 以及生成图像的缓存 . `ImageFacts` 从头直接读取 PNG 、 JPEG 、 GIF 、 WebP 或 AVIF 文件的格式、 MIME 类型和像素尺寸, 对于无法读取的图像字节, 则有一个键入失败. `ImageCache` 答案是“我是否已经从这些参数中生成了图像?” 所以一个建筑停止了重跑一个昂贵的渲染器,比如每跑一次的 Open Graph 牌生成器.

> **预`1.0.0`。 。 。 .** 此软件包是 `@effected/*` 在稳定基础上建造的工具包 效应v4(`effect` `~4.1.0`) 并仍在 `0.x` 发展。 稳定效果 制作一个工具箱 `1.0.0` 可能,不是自动的。 为了保持你的 `effect` 财务报告和审定财务报表 `@effect/*` 该工具包在线上构建和测试、安装 [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected)。 。 。 .
> 
> **稳定:不稳定.** 此软件包的 API 表面尚未考虑 完成并可能改变 `0.x` 释放 定一个确切的版本——甚至 标记软件包 _稳定_ 在此之前 `1.0.0` 可以引入突破性更改 和精确的针 变成一个类型检查错误 而不是一个 跑步时间惊喜。 完全政策: [释放策略](https://github.com/spencerbeggs/effected#release-strategy)。 。 。 .

## 安装

```bash
npm install @effected/images effect
```

```bash
pnpm add @effected/images effect
```

需要节点.js~~24.11.0. `effect` v4是唯一的对等依赖,也是任何种类的唯一依赖——格式阅读器是内部的.

全体 `@effected/*` 软件包仅为无害环境管理:只公布出口地图 `import` 条件,所以 `require()` 节点失败 `ERR_PACKAGE_PATH_NOT_EXPORTED`从ES模块导入.

## 图像事实

根入是纯:无IO,无服务. `ImageFacts.fromBytesResult` 是同步引擎,可以使用一个没有效果运行时间的脚本,以及 `ImageFacts.fromBytes` 改为: `Effect`。 。 。 .

```ts
import { ImageFacts } from "@effected/images";
import { Effect, Result } from "effect";

declare const bytes: Uint8Array;

// Synchronous: a Result, never a throw.
const result = ImageFacts.fromBytesResult(bytes);
if (Result.isSuccess(result)) {
  const { format, mimeType, width, height } = result.success; // "png", "image/png", 1200, 630
  const file = `card.${result.success.extension}`; // "card.png"; a JPEG is written ".jpg"
}

// Effect: fails with ImageParseError.
const facts = ImageFacts.fromBytes(bytes).pipe(
  Effect.catchTag("ImageParseError", (e) => Effect.logWarning(`not an image: ${e.reason}`)),
);
```

`mimeType` 是五种媒体类型之一(`image/png`, (中文(简体) ), `image/jpeg`, (中文(简体) ), `image/gif`, (中文(简体) ), `image/webp`, (中文(简体) ), `image/avif`),以及 `extension` 是常规文件扩展名 : `jpg` 页:1 `jpeg`,格式名称除外. `extension` 是从 `format`,所以它不是被编码的形式的一部分, 以及诸如 `{ ...facts }` 放下枪.

`ImageParseError.reason` 实值 `unrecognized` (无已知签字), `truncated` (一个公认的文件剪短)或 `malformed` (一个自相矛盾的标题). 读者从不投放任何输入,在读取前检查每个长度,并将JPEG和AVIF行走捆绑在分步预算上.

## 生成图像缓存

`@effected/images/cache` 在生成它们的参数产生的密钥下生成的缓存字节. `ImageCacheKey.fromParams` 通过您对参数进行编码 `Schema`串起它们 并用 `salt` ——你的生成器的身份,当它的模板改变,所以每个旧条目都错过时被撞倒.

```ts
import { ImageBackend, ImageCache, ImageCacheKey } from "@effected/images/cache";
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
import * as NodeServices from "@effect/platform-node/NodeServices";
import { Effect, Layer, Schema } from "effect";

const CardParams = Schema.Struct({ title: Schema.String, theme: Schema.String });
declare const renderCard: () => Effect.Effect<Uint8Array>; // your renderer

const CacheLive = ImageCache.layer.pipe(
  Layer.provide(ImageBackend.layerDirectory({ directory: ".cache/og" })),
);

const program = Effect.gen(function* () {
  const cache = yield* ImageCache;
  const key = yield* ImageCacheKey.fromParams(
    CardParams,
    { title: "Hello", theme: "dark" },
    { salt: "og-card-v3", namespace: "og" },
  );
  const { bytes, facts, hit } = yield* cache.getOrGenerate(
    key,
    renderCard, // () => Effect<Uint8Array, E, R> - runs only on a miss
    { accept: ["png"] },
  );
  return { bytes, width: facts.width, hit };
}).pipe(
  Effect.provide(CacheLive),
  Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layerDigest)),
);
```

`getOrGenerate` 返回字节,它们的 `ImageFacts` 以及它是否是一个 `hit`与 `accept`,结果为 `facts.format` 输入为可接受的格式,所以 `["png", "jpeg", "webp"]` 给 `"png" | "jpeg" | "webp"`没有它,每个格式。 不再解析的存储条目, 或格式在外的条目 `accept`,则被视为错失和覆写。 生成结果为空、无法解析或外部 `accept` 失败 `ImageGenerateError` 并永远保存。 后端失败表面为 `ImageBackendError`;生成器自身的出错通过未变.

### 保证返回的渲染器

当造物主返回约言时 `try` 财务报告和审定财务报表 `catch` 因此,它自己的错误到达了呼叫者:

```ts
import { Effect } from "effect";

declare const render: (info: { readonly title: string }) => Promise<Uint8Array>;
declare const info: { readonly title: string };

const generate = () => Effect.tryPromise({ try: () => render(info), catch: (cause) => cause });
```

一个论点 `Effect.tryPromise(() => render(info))` 将拒绝内容覆盖到 `UnknownError`,因此生成器本身的错误丢失.

### 关闭缓存

`ImageBackend.layerNone` 无存储 : `get` 总是怀念和 `set` 丢弃. 当缓存被禁用时提供它并保持不变 `getOrGenerate` 调用; 每次调用都会运行生成器并返回 `hit: false`。 。 。 .

```ts
import { ImageBackend } from "@effected/images/cache";

declare const cachingEnabled: boolean;
const backend = cachingEnabled ? ImageBackend.layerDirectory({ directory: ".cache/og" }) : ImageBackend.layerNone;
```

关键摘要使用核心 `Digest.Digest` (单位:千美元)`effect/crypto`),目录后端使用 `FileSystem` 财务报告和审定财务报表 `Path`在节点上, `NodeServices.layer` 从 `@effect/platform-node` 提供 `FileSystem` 财务报告和审定财务报表 `Path`,以及 `NodeCrypto.layerDigest` 提供 `Digest.Digest`· ; `Digest.layerWebCrypto` 从 `effect/crypto` 在WebCrypto的运行时间工作.

### 带上自己的店

`ImageBackend` 是一个端口,而不是依赖. `ImageBackend.layerFrom(key)` 适应任何服务 `get` 财务报告和审定财务报表 `set` 结构匹配——例如 `Cache` 从 `@effected/store`,两个包之间没有边缘:

```ts
import { Cache } from "@effected/store";
import { ImageBackend } from "@effected/images/cache";

const StoreBacked = ImageBackend.layerFrom(Cache); // provide Cache underneath
```

目录后端存储 `<directory>/<key>.<ext>` 通过临时文件和原子重命名。 它接受和无视 `tags`。 。 。 .

## 特征

-   `ImageFacts` ——存储在文件中的格式,MIME类型,文件扩展名和像素尺寸;同步 `fromBytesResult` 和效果 `fromBytes`。 。 。 .
-   `ImageExtension` 编号 : `ImageMimeType` ——推广和传媒类工会.
-   `ImageFormat` - 字面结合 `png | jpeg | gif | webp | avif`。 。 。 .
-   `ImageParseError` —— 分析失败 `reason` 一旦签字相符 `format`。 。 。 .
-   `ImageCacheKey` 编号 : `ImageCacheKeyError` ——来自已编码参数的内容处理键;故障原因 `encode`, (中文(简体) ), `non-json` 财务报告和审定财务报表 `digest`。 。 。 .
-   `ImageBackend` 编号 : `ImageBackendError` ——存储端口,目录后端,无存储后端和结构适配器;故障原因 `backend` 财务报告和审定财务报表 `unsupported-content-type`。 。 。 .
-   `ImageCache` 编号 : `ImageGenerateError` —— 说 `getOrGenerate` 带有可选 `accept` 缩小结果格式的格式列表.

SVG,BMP,ICO,TIFF,HEIC,JPEG XL,EXIF取向,图像转换和缓存取出都超出了范围.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40effected/images/LICENSE)

## 常见问题

### @effected/images 是什么？

图像事实\(格式,MIME类型,维度\)来自字节,和一个生成的图像缓存,用于Effect\.

### 如何安装 @effected/images？

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

### @effected/images 支持 TypeScript 吗？

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

### @effected/images 支持 ESM 还是 CommonJS？

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

### @effected/images 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @effected/images 可以商用吗？

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

### @effected/images 的下载量有多少？

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

### @effected/images 还在维护吗？

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