# @actions/cache 中文文档

规范地址：https://npmcn.com/package/%40actions/cache/

版本：6\.3\.0
npm 元数据更新时间：2026-09-28T10:26:15.633Z
中文译文更新时间：2026-11-05T17:06:54.584Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：346 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2020-05-15T18:17:42.553Z
- 最新版本发布：2026-09-28T10:26:15.265Z
- 近 30 天下载量：1255837（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 14 个）

## 中文简介

动作缓存 lib

## 安装

```sh
npm install @actions/cache
```

也可以使用：`pnpm add @actions/cache`、`yarn add @actions/cache`、`bun add @actions/cache`

## README

# `@actions/cache`

> 缓存依赖和建立产出以改善工作流程执行时间所必需的功能.

见 ["抓好依托,加快工作流程"](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) 对于如何切入工作.

注意 GitHub 将删除超过7天没有访问过的缓存项 。 对可以存储的缓存数量没有限制,但寄存器中所有缓存的总大小仅限于10GB. 如果您超过此限制, GitHub 将会保存您的缓存, 但会开始驱逐缓存, 直到总大小小于 10 GB .

## 重要变化

缓存后端服务已经从地上重写,以提高性能和可靠性. 这个 [@ actions/ cache (英语)](https://github.com/actions/toolkit/tree/main/packages/cache) 现在软件包与新的缓存服务(v2)API集成.

新服务将逐步推出 **2025年2月1日 (中文(简体) )**遗产服务也将同日落出。 此发行的更改为 **完全向后兼容**。 。 。 .

**此软件包的上个版本都将贬值**我们建议升级到版本 `4.0.0` 尽快提前 **2025年2月1日 (中文(简体) ).**

如果您不升级, 所有工作流程都会使用已贬值的工作流程 [@ actions/ cache (英语)](https://github.com/actions/toolkit/tree/main/packages/cache) 软件包将失败 .

升级到推荐的版本,除了更新您的工作流程外,不应中断或要求修改您的工作流程 `package.json` 改为版本 `4.0.0`。 。 。 .

更多信息, 请查看更改和访问迁移指南 : [通知内容](https://github.com/actions/toolkit/discussions/1890)。 。 。 .

## 使用量

这个软件包被我们第一个政党缓存动作的v2+版本所使用. 您可以在缓存 Repo 中找到实例执行 [这里](https://github.com/actions/cache)。 。 。 .

#### 保存缓存

保存包含文件的缓存 `paths` 使用 `key` 提供。 如果安装了zstd,文件将使用z标准压缩算法进行压缩,否则使用gzip. 如果缓存被自动保存, 函数返回缓存 ID, 如果缓存上传失败, 则丢出错误 .

```js
const cache = require('@actions/cache');
const paths = [
    'node_modules',
    'packages/*/node_modules/'
]
const key = 'npm-foobar-d5ea0750'
const cacheId = await cache.saveCache(paths, key)
```

#### 恢复缓存

基于 `key` 财务报告和审定财务报表 `restoreKeys` 页:1 `paths` 提供。 函数返回缓存键用于缓存被击中, 如果未找到缓存则返回未定义 .

```js
const cache = require('@actions/cache');
const paths = [
    'node_modules',
    'packages/*/node_modules/'
]
const key = 'npm-foobar-d5ea0750'
const restoreKeys = [
    'npm-foobar-',
    'npm-'
]
const cacheKey = await cache.restoreCache(paths, key, restoreKeys)
```

##### 缓存段恢复超时

缓存在固定大小的多段内下载( 现在) `128MB` 失败快速, 以前 `1GB` (单位:千美元) `32-bit` 运行和 `2GB` (单位:千美元) `64-bit` 使用跑道)。 有时,一个段的下载会被卡住,导致工作流程永远被卡住并失败. 版本 `v3.0.4` 缓存包中引入了段下载超时。 片段下载超时将允许片段下载被中止,从而允许该任务进行缓存出错.

此超时的默认值为 10 分( 开始) `v3.2.1` 前60分钟的版本 `v.3.0.4` 财务报告和审定财务报表 `v3.2.0`,并且可以通过指定 [环境变量](https://docs.github.com/en/actions/learn-github-actions/environment-variables) 名称 `SEGMENT_DOWNLOAD_TIMEOUT_MINS` 分钟内有超时值.

## 常见问题

### @actions/cache 是什么？

动作缓存 lib

### 如何安装 @actions/cache？

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

### @actions/cache 支持 TypeScript 吗？

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

### @actions/cache 支持 ESM 还是 CommonJS？

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

### @actions/cache 可以商用吗？

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

### @actions/cache 的下载量有多少？

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

### @actions/cache 还在维护吗？

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