cacache

中文文档

21.0.1发布于 2026/06/10ISCCommonJS构建来源已验证近 30 天下载 1.5亿

快速,容错,跨平台,基于磁盘,数据不可知,内容可处理缓存.

文档目录6 节

安装
目录
示例
特征
捐款
API 密码

缓存

cacache 是一个用于管理 Node.js 库本地密钥和内容地址缓存。真的很快,真的很擅长货币,它永远不会给你损坏的数据,即使缓存文件腐败或操纵.

关于支持文件用户和组设置的系统, cacache 将符合 uid 财务报告和审定财务报表 gid 缓存所在文件夹的值,甚至当运行为 root。。。 .

它被写成无本地缓存, 但可以同样容易被自己使用.

安装

$ npm install --save cacache

const cacache = require('cacache')
const fs = require('fs')

const cachePath = '/tmp/my-toy-cache'
const key = 'my-unique-key-1234'

// Cache it! Use `cachePath` as the root of the content cache
cacache.put(cachePath, key, '10293801983029384').then(integrity => {
  console.log(`Saved content to ${cachePath}.`)
})

const destination = '/tmp/mytar.tgz'

// Copy the contents out of the cache and into their destination!
// But this time, use stream instead!
cacache.get.stream(
  cachePath, key
).pipe(
  fs.createWriteStream(destination)
).on('finish', () => {
  console.log('done extracting!')
})

// The same thing, but skip the key index.
cacache.get.byDigest(cachePath, integrityHash).then(data => {
  fs.writeFile(destination, data, err => {
    console.log('tarball data fetched based on its sha512sum and written out!')
  })
})

特征

按密钥或内容地址提取(shasum等)
分资源网络标准支持
多随机支持 - 安全主机 sha1, sha512等, 在一个缓存中
自动内容分解
过失容忍(贪污罪、部分写作、过程种族等)
读写的一致性保障(全面数据核实)
无锁高通量缓存访问
流动支助
承诺支持
快速 -- -- 次毫升读取和写出包括校验
任意元数据存储
垃圾收集和其他离线核查
彻底测试覆盖率
里面可能有个开花的过滤器不错吧

捐款

Cacache团队热情欢迎捐款和项目参与!. 如果你想出力,你们可以做很多事! 如果你愿意的话请不要犹豫或问我们问题如果事情还不清楚.

预计该项目的所有参与者和维护者将遵循行为守则,只是一般是优于对方.

请参看更改日志还有项目历史细节.

黑客快乐!

API 密码

`> cacache.ls(cache) -> Promise<Object>`

将缓存中当前所有条目的信息列为单个大对象。每个对象中的条目将由唯一的索引密钥键来键入,并对应 get.info 对象作为值.

示例

cacache.ls(cachePath).then(console.log)
// Output
{
  'my-thing': {
    key: 'my-thing',
    integrity: 'sha512-BaSe64/EnCoDED+HAsh=='
    path: '.testcache/content/deadbeef', // joined with `cachePath`
    time: 12345698490,
    size: 4023948,
    metadata: {
      name: 'blah',
      version: '1.2.3',
      description: 'this was once a package but now it is my-thing'
    }
  },
  'other-thing': {
    key: 'other-thing',
    integrity: 'sha1-ANothER+hasH=',
    path: '.testcache/content/bada55',
    time: 11992309289,
    size: 111112
  }
}

`> cacache.ls.stream(cache) -> Readable`

将缓存中当前所有条目的信息列为单个大对象.

这工作就像 ls时,除 get.info 条目是返回为 'data' 返回流中的事件.

示例

cacache.ls.stream(cachePath).on('data', console.log)
// Output
{
  key: 'my-thing',
  integrity: 'sha512-BaSe64HaSh',
  path: '.testcache/content/deadbeef', // joined with `cachePath`
  time: 12345698490,
  size: 13423,
  metadata: {
    name: 'blah',
    version: '1.2.3',
    description: 'this was once a package but now it is my-thing'
  }
}

{
  key: 'other-thing',
  integrity: 'whirlpool-WoWSoMuchSupport',
  path: '.testcache/content/bada55',
  time: 11992309289,
  size: 498023984029
}

{
  ...
}

`> cacache.get(cache, key, [opts]) -> Promise({data, metadata, integrity})`

以缓存数据、摘要和元数据返回对象 key编辑 data 此对象的属性将是 a Buffer 实例可能有些数据对你很重要我敢肯定,你知道什么来对付它! 卡卡切只是不会在乎.

integrity 是一个次级资源诚信绳子。也就是说,可以用来验证的字符串 data,这看起来像 <hash-algorithm>-<base64-integrity-hash>。。。 .

如果没有识别的内容 key,或者如果本地存储的数据确实存在不通过有效性校验和, 承诺将被拒绝.

一个子功能, get.byDigest 可能用于相同的行为, 但检查除外将完全绕过指数, 这个版本函数仅限返回时 data 自己,没有包装.

见: 选项

说明

此函数在返回内存之前将整个缓存条目装入内存。若为您正在处理非常大的数据, 考虑使用 get.stream 换句话说.

示例

// Look up by key
cache.get(cachePath, 'my-thing').then(console.log)
// Output:
{
  metadata: {
    thingName: 'my'
  },
  integrity: 'sha512-BaSe64HaSh',
  data: Buffer#<deadbeef>,
  size: 9320
}

// Look up by digest
cache.get.byDigest(cachePath, 'sha512-BaSe64HaSh').then(console.log)
// Output:
Buffer#<deadbeef>

`> cacache.get.stream(cache, key, [opts]) -> Readable`

回返a 可读流线以 key。。。 .

如果没有识别的内容 key,或者如果本地存储的数据确实存在无法通过有效性校验和, 错误将被释放 .

metadata 财务报告和审定财务报表 integrity 如果您需要收集更多关于缓存条目的数据.

一个子功能, get.stream.byDigest 可能被用于相同的行为, 完全绕过索引。这个版本不发送 metadata 财务报告和审定财务报表 integrity 完全没有.

见: 选项

示例

// Look up by key
cache.get.stream(
  cachePath, 'my-thing'
).on('metadata', metadata => {
  console.log('metadata:', metadata)
}).on('integrity', integrity => {
  console.log('integrity:', integrity)
}).pipe(
  fs.createWriteStream('./x.tgz')
)
// Outputs:
metadata: { ... }
integrity: 'sha512-SoMeDIGest+64=='

// Look up by digest
cache.get.stream.byDigest(
  cachePath, 'sha512-SoMeDIGest+64=='
).pipe(
  fs.createWriteStream('./x.tgz')
)

`> cacache.get.info(cache, key) -> Promise`

抬头看 key 在缓存索引中,如果一个存在.

字段

key - 钥匙,入口被放在下面匹配 key 参数.
integrity - 说吧分资源对于本条目所指的内容.
path - 内容存储、加入的文件系统路径 cache 参数.
time - 时间戳是先加的.
metadata - 与条目/内容有关的用户指定元数据.

示例

cacache.get.info(cachePath, 'my-thing').then(console.log)

// Output
{
  key: 'my-thing',
  integrity: 'sha256-MUSTVERIFY+ALL/THINGS=='
  path: '.testcache/content/deadbeef',
  time: 12345698490,
  size: 849234,
  metadata: {
    name: 'blah',
    version: '1.2.3',
    description: 'this was once a package but now it is my-thing'
  }
}

`> cacache.get.hasContent(cache, integrity) -> Promise`

看起来像一个分资源在缓存。如果内容已存在此选项 integrity,它将返回一个对象,带有特定的单一完整性散列发现于 sri 键,并查找内容大小为 size。如果没有关于这种完整性的内容,它将返回 false。。。 .

示例

cacache.get.hasContent(cachePath, 'sha256-MUSTVERIFY+ALL/THINGS==').then(console.log)

// Output
{
  sri: {
    source: 'sha256-MUSTVERIFY+ALL/THINGS==',
    algorithm: 'sha256',
    digest: 'MUSTVERIFY+ALL/THINGS==',
    options: []
  },
  size: 9001
}

cacache.get.hasContent(cachePath, 'sha521-NOT+IN/CACHE==').then(console.log)

// Output
false

选项

`opts.integrity`

如果存在,插入内容的预计算摘要. 如果这个选项已提供,且与插入后摘要不符,插入失败带有 EINTEGRITY 错误.

`opts.memoize`

默认: 无效

如果明确真实,cacache会从内存中读取并记忆到批量读取的数据. 若为 false,cacache将从磁盘数据读取。默认读取器功能从内存缓存读取.

`opts.size`

如果提供,将核查数据流,以检查是否有足够的数据通过。如果数据比预期多或少,插入就会失败带有 EBADSIZE 错误.

`> cacache.put(cache, key, data, [opts]) -> Promise`

将传递给它的数据插入到缓存中。回归的诺言以文摘(根据 opts.algorithms在缓存条目已成功写入 .

见: 选项

示例

fetch(
  'https://registry.npmjs.org/cacache/-/cacache-1.0.0.tgz'
).then(data => {
  return cacache.put(cachePath, 'registry.npmjs.org|[email protected]', data)
}).then(integrity => {
  console.log('integrity hash is', integrity)
})

`> cacache.put.stream(cache, key, [opts]) -> Writable`

回返a 可写流线插入时输入到缓存中的数据。输出 a integrity 附带摘要的事件成功时写入内容.

见: 选项

示例

request.get(
  'https://registry.npmjs.org/cacache/-/cacache-1.0.0.tgz'
).pipe(
  cacache.put.stream(
    cachePath, 'registry.npmjs.org|[email protected]'
  ).on('integrity', d => console.log(`integrity digest is ${d}`))
)

选项

`opts.metadata`

将任意元数据附加在插入的密钥上 .

`opts.size`

如果提供,将核查数据流,以检查是否有足够的数据通过。如果数据比预期多或少,插入就会失败带有 EBADSIZE 错误.

`opts.integrity`

如果存在,插入内容的预计算摘要. 如果这个选项已提供,且与插入后摘要不符,插入失败带有 EINTEGRITY 错误.

algorithms 如果存在此选项,则无效.

`opts.integrityEmitter`

仅流出 如果存在,则使用所提供的事件发射器作为源诚实和大小这允许使用完整性的情况已计算在缓存之外重用该数据算它第二次.

发射者必须同时发射 'integrity' 财务报告和审定财务报表 'size' 事件.

注:如果提供了这一选项,则必须证明您收到正确的选项忠诚重视自己并释放 'error' 如果出现不匹配,则出现事件. ssri 诚信流当你们达到应有的境界的时候,你们要达到这个目的.

`opts.algorithms`

默认 : ['sha512']

计算时使用的哈兴算法分资源完整性摘要对于插入的数据。可以使用列表中的任何算法 crypto.getHashes() 或者说 'omakase'编号 :'お任せします' 在每次插入时选择随机散列算法。你个也可以使用任何动画 'modnar' 用于此特性.

目前只支持一次一个算法(即数组长度为没错 1) (中文(简体) ). 如果 opts.integrity 已存在.

`opts.memoize`

默认: 无效

如果提供, cacache 将提醒给定的缓存插入内存, 绕过未来缓存中对该密钥或摘要的任何文件系统检查。没什么除非此选项明确属实,否则将写入内存.

若为 opts.memoize 是对象或对象 Map- 喜欢(即,一个物体与 get 财务报告和审定财务报表 set 而不是全球记忆缓存.

从磁盘上读取数据可强制通过 memoize: false 改为读取器的功能,但他们的默认是从内存读取.

`opts.tmpPrefix`

默认: 无效

在缓存 tmp dir 内的临时目录名称上附加的前缀 .

`> cacache.rm.all(cache) -> Promise`

清除整个缓存。主要通过吹走缓存目录本身.

示例

cacache.rm.all(cachePath).then(() => {
  console.log('THE APOCALYPSE IS UPON US 😱')
})

`> cacache.rm.entry(cache, key, [opts]) -> Promise`

别名: cacache.rm

删除索引条目 key如果由内容地址直接请求(get.stream.byDigest) (中文(简体) ).

默认情况下,此选项附加到索引中的新条目,其完整性为: null。。。 . 若为 opts.removeFully 设置为 true 那么索引文件本身将是实际删除,而不是附加 null。。。 .

删除内容本身(其他条目可能仍然使用),使用 rm.content。或者,为了安全地清除任何未使用的内容,使用 verify。。。 .

示例

cacache.rm.entry(cachePath, 'my-thing').then(() => {
  console.log('I did not like it anyway')
})

`> cacache.rm.content(cache, integrity) -> Promise`

删除识别的内容 integrity。任何与之相关的索引条目在内容重新添加到缓存中之前无法再次使用同样的文摘.

示例

cacache.rm.content(cachePath, 'sha512-SoMeDIGest/IN+BaSE64==').then(() => {
  console.log('data for my-thing is gone!')
})

`> cacache.index.compact(cache, key, matchFn, [opts]) -> Promise`

用途 matchFn,它必须是接受两个条目的同步函数返回布尔表示两个条目是否匹配,以便为给定的缓存复制所有条目 key。。。 .

若为 opts.validateEntry 提供后,它将与参数只是单个索引条目。函数必须返回布尔, 返回时 true 该条目被视为有效,并将保留在索引中, 返回时 false 该条目将从索引中删除.

若为 opts.validateEntry 然而,没有提供指数中的每一个条目复制并保存到第一次 null 实现完整性, 删除全部在 null。。。 .

被删减的条目列表同时被写入索引,以取代已存在的内容,并在“承诺”中返回.

`> cacache.index.insert(cache, key, integrity, opts) -> Promise`

为给定的缓存写入索引条目 key 不写内容.

假设您正在使用这种方法, 您已经存储了内容以其他方式,你只想在内容中添加一个新的索引。这个 metadata 财务报告和审定财务报表 size 属性读取自 opts 并用作索引条目的一部分.

A 向新添加的条目返回承诺解析.

`> cacache.clearMemoized()`

完全重置内存条目缓存 .

`> tmp.mkdir(cache, opts) -> Promise<Path>`

返回缓存内唯一的临时目录 tmp 目录。这个目录将使用与所有其他东西相同的安全用户指派 .

一旦目录完成,所有文件都是用户的责任在其中给予适当的 gid编号 :uid 要匹配的所有权设置其余的缓存。如果不行的话,你可以叫cacache帮你做电话 tmp.fix(),它将修正所有 tmp 目录权限.

如果您想要自动清理此目录, 请使用 tmp.withTmp()

见: 选项

示例

cacache.tmp.mkdir(cache).then(dir => {
  fs.writeFile(path.join(dir, 'blablabla'), Buffer#<1234>, ...)
})

`> tmp.fix(cache) -> Promise`

设置 uid 财务报告和审定财务报表 gid tmp 中所有文件和文件夹的属性匹配缓存的文件夹 .

手动写入文件后使用此功能 tmp.mkdir 或者说 tmp.withTmp。。。 .

示例

cacache.tmp.mkdir(cache).then(dir => {
  writeFile(path.join(dir, 'file'), someData).then(() => {
    // make sure we didn't just put a root-owned file in the cache
    cacache.tmp.fix().then(() => {
      // all uids and gids match now
    })
  })
})

`> tmp.withTmp(cache, opts, cb) -> Promise`

创建一个临时目录 tmp.mkdir() 和电话 cb 带着它返回值时将删除已创建的临时目录联合国 cb() 解析后, tmp 目录将自动被删除承诺完成.

在管理 tmp dir 权限时, 也适用同样的警告目录.

见: 选项

示例

cacache.tmp.withTmp(cache, dir => {
  return fs.writeFile(path.join(dir, 'blablabla'), 'blabla contents', { encoding: 'utf8' })
}).then(() => {
  // `dir` no longer exists
})

选项

`opts.tmpPrefix`

默认: 无效

在缓存 tmp dir 内的临时目录名称上附加的前缀 .

分资源廉正文摘

对于内容的校验和地址,cacache使用字符串跟踪次级资源诚信谱。。。 . 即,任何时间cacache期望一个 integrity 参数或选项,它应采用格式 <hashAlgorithm>-<base64-hash>。。。 .

与当前规格的一个偏差是cacache会支持任意散列由基础节点.js进程支持的算法. 你用得着 crypto.getHashes() 看看你能用到哪个.

制作摘要

如果您有已有的内容 shasum , 它们一般被格式化为六进制字符串(即:sha1会看起来像: 5f5513f8822fdbe5145af33b64d8d970dcf95c6e) (中文(简体) ). 为了兼容 cacache,你需要把这个转换成相当的子资源完整性绳子。例如,相应的散列将是: sha1-X1UT+IIv2+UUWvM7ZNjZcNz5XG4=。。。 .

如果您想要为已有数据创建完整字符串, 您可以用这样的东西:

const crypto = require('crypto')
const hashAlgorithm = 'sha512'
const data = 'foobarbaz'

const integrity = (
  hashAlgorithm +
  '-' +
  crypto.createHash(hashAlgorithm).update(data).digest('base64')
)

您还可以使用 ssri 拥有一套更丰富的功能环绕SRI字符串,包括生成、解析和从现有六进制字符串 .

`> cacache.verify(cache, opts) -> Promise`

检查并修正您的缓存 :

清理已损坏或无效的索引条目.
自定义条目过滤选项 .
垃圾收集索引未引用的任何内容条目.
检查所有内容条目的完整性并删除无效内容.
修复缓存所有权 .
删除 tmp 缓存中的目录及其全部内容.

完成后,它会返回一个有各种数据记录的物体程序,包括重新封存的数量、有效条目的数量、数量已删除的条目等.

选项

`opts.concurrency`

默认: 20

在清理时同时读取文件的数量 .

`opts.filter`

接收格式化条目。归假取去. 注:在同一条目中,可能不止一次被称作.

`opts.log`

自定义日志函数 :

  log: { silly () {} }
  log.silly('verify', 'verifying cache at', cache)

示例

echo somegarbage >> $CACHEPATH/content/deadbeef

cacache.verify(cachePath).then(stats => {
  // deadbeef collected, because of invalid checksum.
  console.log('cache is much nicer now! stats:', stats)
})

`> cacache.verify.lastRun(cache) -> Promise`

回返a Date 代表最后一次 cacache.verify 运行在 cache。。。 .

示例

cacache.verify(cachePath).then(() => {
  cacache.verify.lastRun(cachePath).then(lastTime => {
    console.log('cacache.verify was last called on' + lastTime)
  })
})

版本与发布记录

cacache 共发布 110 个版本，首次发布于 2016/11/18；过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`21.0.1`latest	2026/06/10	4 个月前
`21.0.0`	2026/05/19	5 个月前
`20.0.4`	2026/03/19	7 个月前
`20.0.3`	2025/11/22	11 个月前
`20.0.2`	2025/11/18	11 个月前
`20.0.1`	2025/08/19	1.2 年前

其他发布通道：legacy → 12.0.4。

关于 cacache 的常见问题

cacache 是什么？

快速,容错,跨平台,基于磁盘,数据不可知,内容可处理缓存.

如何安装 cacache？

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

cacache 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cacache 是否存在。

cacache 支持 ESM 还是 CommonJS？

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

cacache 需要什么版本的 Node.js？

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

cacache 可以商用吗？

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

cacache 的下载量有多少？

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

cacache 还在维护吗？

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

npm install cacache

pnpmpnpm add cacache
yarnyarn add cacache
bunbun add cacache

在你的项目目录中运行此命令。

近 30 天下载

145,894,923

约 1.5亿次日均 4,863,164 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，今天更新

最新版本21.0.1发布于 4 个月前

开源许可ISC宽松许可

包体积64.9 kB18 个文件 · 解压后

运行依赖10 个

模块格式CommonJS

TypeScript未声明类型可查找 @types/cacache

Node.js^22.22.2 || ^24.15.0 || >=26.0.0

发布版本110 个近 12 个月 5 个

首次发布2016/11/189 年前

元数据更新2026/09/10

每一个软件包背后，
都有分享与创造的人。