# @exa-ai/cache-manager 中文文档

规范地址：https://npmcn.com/package/%40exa-ai/cache-manager/

版本：5\.5\.1-clone
npm 元数据更新时间：2025-08-01T01:58:41.966Z
中文译文更新时间：2026-11-14T02:58:52.892Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40exa-ai/cache-manager
原文对照：https://npmcn.com/package/%40exa-ai/cache-manager/?lang=original
项目主页：https://github.com/exa-labs/cacheable#readme
源码仓库：https://github.com/exa-labs/cacheable

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

- 包体积（解压后）：28 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-08-01T01:58:41.121Z
- 最新版本发布：2025-08-01T01:58:41.655Z
- 近 30 天下载量：10997（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

Node.js 缓存模块

## 安装

```sh
npm install @exa-ai/cache-manager
```

也可以使用：`pnpm add @exa-ai/cache-manager`、`yarn add @exa-ai/cache-manager`、`bun add @exa-ai/cache-manager`

## README

# 缓存管理器

[![codecov](https://codecov.io/gh/jaredwray/cache-manager/graph/badge.svg?token=lWZ9OBQ7GM)](https://codecov.io/gh/jaredwray/cache-manager) [![tests](https://github.com/jaredwray/cache-manager/actions/workflows/test.yml/badge.svg)](https://github.com/jaredwray/cache-manager/actions/workflows/test.yml) [![license](https://img.shields.io/github/license/jaredwray/cache-manager)](https://github.com/jaredwray/cache-manager/blob/main/LICENSE) [![npm](https://img.shields.io/npm/dm/cache-manager)](https://npmjs.com/package/cache-manager) ![npm](https://img.shields.io/npm/v/cache-manager)

# 灵活节点JS缓存模块

一个用于节点的缓存模块,可以轻松地将函数包入缓存,分级缓存,以及一个一致的接口.

## 目录

-   [特征](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-features)
-   [安装](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-installation)
-   [用法实例](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-usage-examples)
    -   [单行存储](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-single-store)
    -   [多层](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-multi-store)
    -   [快取管理器选项](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-cache-manager-options)
    -   [在背景中刷新缓存密钥](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-refresh-cache-keys-in-background)
    -   [处理错误](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-error-handling)
    -   [存储引擎](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-store-engines)
-   [贡献](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-contribute)
-   [许可证](https://npmcn.com/package/%40exa-ai/cache-manager/#readme-license)

## 特征

-   使用打字符并兼容 [无害环境管理](https://nodejs.org/docs/latest-v14.x/api/esm.html)
-   以缓存方式将任何函数包裹起来的简单方法 .
-   分层缓存 — 数据存储在每个缓存中并从最高处获取 . 优先缓存.
-   使用您想要的任何缓存, 只要它有相同的 API .
-   100%的测试覆盖率 [测试](https://github.com/vitest-dev/vitest)。 。 。 .

## 安装

```
pnpm install cache-manager
```

## 用法实例

### 单行存储

```typescript
import { caching } from 'cache-manager';

const memoryCache = await caching('memory', {
  max: 100,
  ttl: 10 * 1000 /*milliseconds*/,
});

const ttl = 5 * 1000; /*milliseconds*/
await memoryCache.set('foo', 'bar', ttl);

console.log(await memoryCache.get('foo'));
// >> "bar"

await memoryCache.del('foo');

console.log(await memoryCache.get('foo'));
// >> undefined

const getUser = (id: string) => new Promise.resolve({ id: id, name: 'Bob' });

const userId = 123;
const key = 'user_' + userId;

console.log(await memoryCache.wrap(key, () => getUser(userId), ttl));
// >> { id: 123, name: 'Bob' }
```

见单元测试 [`test/caching.test.ts`](https://npmcn.com/package/%40exa-ai/cache-manager/test/caching.test.ts) 更多信息.

#### 用 mset( ) 和 mget( ) 设置/ 获得数个密钥的例子

```typescript
await memoryCache.store.mset(
  [
    ['foo', 'bar'],
    ['foo2', 'bar2'],
  ],
  ttl,
);

console.log(await memoryCache.store.mget('foo', 'foo2'));
// >> ['bar', 'bar2']

// Delete keys with mdel() passing arguments...
await memoryCache.store.mdel('foo', 'foo2');
```

#### [示例快捷应用使用](https://npmcn.com/package/%40exa-ai/cache-manager/examples/express/src/index.mts)

#### 自定义存储

可以通过创建与内置内存商店相同的API来使用自定义商店.

-   [自定义存储缓存示例](https://npmcn.com/package/%40exa-ai/cache-manager/src/stores/memory.ts)
-   [示例自定义存储重取](https://github.com/jaredwray/cache-manager/packages/cache-manager-redis-yet)
-   [示例自定义存储ioredis](https://github.com/jaredwray/cache-manager/packages/cache-manager-ioredis-yet)

#### 同步创建单个缓存存储

作为 `caching()` 需要async功能来解决一些存储,这不适合用于默认函数/构造参数等.

如果您需要同步创建缓存店, 您可以使用 `createCache()`数字 :

```typescript
import { createCache, memoryStore } from 'node-cache-manager';

// Create memory cache synchronously
const memoryCache = createCache(memoryStore(), {
  max: 100,
  ttl: 10 * 1000 /*milliseconds*/,
});

// Default parameter in function
function myService(cache = createCache(memoryStore())) {}

// Default parameter in class constructor
const DEFAULT_CACHE = createCache(memoryStore(), { ttl: 60 * 1000 });
// ...
class MyService {
  constructor(private cache = DEFAULT_CACHE) {}
}
```

### 多层

```typescript
import { multiCaching } from 'cache-manager';

const multiCache = multiCaching([memoryCache, someOtherCache]);
const userId2 = 456;
const key2 = 'user_' + userId;
const ttl = 5;

// Sets in all caches.
await multiCache.set('foo2', 'bar2', ttl);

// Fetches from highest priority cache that has the key.
console.log(await multiCache.get('foo2'));
// >> "bar2"

// Delete from all caches
await multiCache.del('foo2');

// Sets multiple keys in all caches.
// You can pass as many key, value tuples as you want
await multiCache.mset(
  [
    ['foo', 'bar'],
    ['foo2', 'bar2'],
  ],
  ttl
);

// mget() fetches from highest priority cache.
// If the first cache does not return all the keys,
// the next cache is fetched with the keys that were not found.
// This is done recursively until either:
// - all have been found
// - all caches has been fetched
console.log(await multiCache.mget('key', 'key2'));
// >> ['bar', 'bar2']

// Delete keys with mdel() passing arguments...
await multiCache.mdel('foo', 'foo2');
```

见单元测试 [`test/multi-caching.test.ts`](https://npmcn.com/package/%40exa-ai/cache-manager/test/multi-caching.test.ts) 更多信息.

### 快取管理器选项

这个 `caching` 财务报告和审定财务报表 `multiCaching` 函数接受一个选项对象作为第二个参数。 有以下备选方案:

-   最大: 可存储在缓存中的项目的最大数量 。 如果缓存已满, 使用最少的项目会被删除 .
-   ttl:活在毫秒的时间. 这是物品在被移除前可以在缓存中的最大时间.
-   shouldClone BeforeSet:如果是真实的,则在缓存中设置之前将克隆该值。 这是设定为 `true` 默认.

```typescript
import { caching } from 'cache-manager';

const memoryCache = await caching('memory', {
  max: 100,
  ttl: 10 * 1000 /*milliseconds*/,
  shouldCloneBeforeSet: false, // this is set true by default (optional)
});
```

### 在背景中刷新缓存密钥

两者 `caching` 财务报告和审定财务报表 `multicaching` 模块支持在背景中刷新过期缓存密钥的机制 `wrap` 函数.  
方法是增加一个 `refreshThreshold` 属性,同时创建缓存存储或将其传递到 `wrap` 函数.

若为 `refreshThreshold` 设置,在从缓存中获取一个值后,将检查 TTL .  
如果剩余的TTL小于 `refreshThreshold`系统将同步更新值,  
遵循与标准取取取相同的规则. 在此期间,该系统会还原旧值直到到期.

注:

-   在多切切时,将检查刷新的商店是先找到钥匙的商店(最优先).
-   如果阈值低而工人的功能缓慢,则键会过期而遇到更新值的赛跑条件.
-   背景刷新机制目前不支持向 `wrap` 函数.
-   若无 `ttl` 为密钥设置,刷新机制将不会被触发。 对Redis来说 `ttl` 默认设置为 -1.

例如,将刷新门槛传递到 `caching` 像这样:

```typescript
const memoryCache = await caching('memory', {
  max: 100,
  ttl: 10 * 1000 /*milliseconds*/,
  refreshThreshold: 3 * 1000 /*milliseconds*/,
  
  /* optional, but if not set, background refresh error will be an unhandled
   * promise rejection, which might crash your node process */
  onBackgroundRefreshError: (error) => { /* log or otherwise handle error */ }
});
```

当从 Redis 从 TTL 小于 3sec 的值取出时, 值会在背景中更新 .

## 处理错误

缓存管理器现在不会默认丢出错误 。 相反,所有错误都会通过 `error` 活动。 以下是如何使用它的例子:

```javascript
const memoryCache = await caching('memory', {
  max: 100,
  ttl: 10 * 1000 /*milliseconds*/,
});
memoryCache.on('error', (error) => {
  console.error('Cache error:', error);
});
```

## 存储引擎

### 正式更新为上一个版本

-   [节点- cache- 管理器- redis- yet](https://github.com/jaredwray/cache-manager/packages/cache-manager-redis-yet) (用户数) [节点( redis)](https://github.com/NodeRedis/node_redis)(中文(简体) )
    
-   [节点-cache-manager-ioredis - yet( 节点- cache- manager- ioredis - 有)](https://github.com/jaredwray/cache-manager/packages/cache-manager-ioredis-yet) (用户数) [雄风](https://github.com/luin/ioredis)(中文(简体) )
    

### 第三方

-   [节点控制器](https://github.com/dial-once/node-cache-manager-redis) (用户数) [索尔 - 重新组合](https://github.com/joshuah/sol-redis-pool)(中文(简体) )
    
-   [节点- cache- 管理器- redis- store](https://github.com/dabroek/node-cache-manager-redis-store) (用户数) [节点( redis)](https://github.com/NodeRedis/node_redis)(中文(简体) )
    
-   [节点-cache-manager-ioredis](https://github.com/Tirke/node-cache-manager-ioredis) (用户数) [雄风](https://github.com/luin/ioredis)(中文(简体) )
    
-   [节点- cache- 管理器- mongodb](https://github.com/v4l3r10/node-cache-manager-mongodb)
    
-   [节点- cache- 管理- mongose](https://github.com/disjunction/node-cache-manager-mongoose)
    
-   [节点控制- 管理- fs- 二进制](https://github.com/sheershoff/node-cache-manager-fs-binary)
    
-   [节点控制器管理器](https://github.com/rolandstarke/node-cache-manager-fs-hash)
    
-   [节点-cache-manager-hazelcast (节点-cache-manager-hazelcast) 节点-经理-hazelcast 节点-经理-hazelcast](https://github.com/marudor/node-cache-manager-hazelcast)
    
-   [节点- cache- 管理器- memcomed- store](https://github.com/theogravity/node-cache-manager-memcached-store)
    
-   [节点- cache- 管理器- memomery- store](https://github.com/theogravity/node-cache-manager-memory-store)
    
-   [节点控制库](https://github.com/davidepellegatta/node-cache-manager-couchbase)
    
-   [节点- cache- 管理器- sqlite](https://github.com/maxpert/node-cache-manager-sqlite)
    
-   [@resolid/cache-manager-sqlite (英语)](https://github.com/huijiewei/cache-manager-sqlite) (用户数) [较好的sqlite3](https://github.com/WiseLibs/better-sqlite3)(中文(简体) )
    

## 贡献

如果你愿意为该项目捐款,请在这里阅读如何捐款 [捐款额](https://npmcn.com/package/%40exa-ai/cache-manager/CONTRIBUTING.md)。 。 。 .

## 许可证

缓存管理器根据 [麻省理工学院许可证](https://npmcn.com/package/%40exa-ai/cache-manager/LICENSE)。 。 。 .

## 常见问题

### @exa-ai/cache-manager 是什么？

Node\.js 缓存模块

### 如何安装 @exa-ai/cache-manager？

在项目目录运行 npm install @exa-ai/cache-manager，或使用 pnpm add / yarn add / bun add。

### @exa-ai/cache-manager 支持 TypeScript 吗？

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

### @exa-ai/cache-manager 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @exa-ai/cache-manager 可以商用吗？

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

### @exa-ai/cache-manager 的下载量有多少？

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

### @exa-ai/cache-manager 还在维护吗？

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