# @actions/artifact 中文文档

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

版本：6\.3\.1
npm 元数据更新时间：2026-10-06T12:49:22.765Z
中文译文更新时间：2026-11-05T16:55:05.004Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：333 kB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：14 个
- 首次发布：2020-02-20T19:02:52.277Z
- 最新版本发布：2026-10-06T12:49:22.344Z
- 近 30 天下载量：3832498（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 11 个）

## 中文简介

文物活动

## 安装

```sh
npm install @actions/artifact
```

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

## README

# `@actions/artifact`

在方案上与 [动作艺术](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts)。 。 。 .

这是核心库 授权 [`@actions/upload-artifact`](https://github.com/actions/upload-artifact) 财务报告和审定财务报表 [`@actions/download-artifact`](https://github.com/actions/download-artifact) 行动.

-   [`@actions/artifact`](https://npmcn.com/package/%40actions/artifact/#readme-actionsartifact)
    -   [v2 - 什么是新东西](https://npmcn.com/package/%40actions/artifact/#readme-v2---whats-new)
        -   [改进](https://npmcn.com/package/%40actions/artifact/#readme-improvements)
        -   [中断更改](https://npmcn.com/package/%40actions/artifact/#readme-breaking-changes)
    -   [快速启动](https://npmcn.com/package/%40actions/artifact/#readme-quick-start)
    -   [实例](https://npmcn.com/package/%40actions/artifact/#readme-examples)
        -   [上传和下载](https://npmcn.com/package/%40actions/artifact/#readme-upload-and-download)
        -   [删除艺术](https://npmcn.com/package/%40actions/artifact/#readme-delete-an-artifact)
        -   [从其他工作流程下载运行或重置](https://npmcn.com/package/%40actions/artifact/#readme-downloading-from-other-workflow-runs-or-repos)
        -   [加快大型上传](https://npmcn.com/package/%40actions/artifact/#readme-speeding-up-large-uploads)
    -   [额外资源](https://npmcn.com/package/%40actions/artifact/#readme-additional-resources)

## v2 - 什么是新东西

> \[大 @actions/artifact v2+,上传-artifact@v4+,下载-artifact@v4+目前尚未在GHES上支持. 此软件包的上一个版本可见于 [此标签](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) 财务报告和审定财务报表 [时间](https://www.npmjs.com/package/@actions/artifact/v/1.1.2)。 。 。 .

释放 `@actions/artifact@v2` (包括 `upload-artifact@v4` 财务报告和审定财务报表 `download-artifact@v4`)是Artifacts后端架构的重大变化. 他们有许多表现和行为上的改进.

### 改进

1.  所有上传和下载操作都更快,在最坏的情况下,下载时间可达80%快,上传时间可达96%快.
2.  一旦上传,就会返回人工识别码,并立即在用户界面中提供人工识别码 [(原始内容存档于2013-10-12) (英语). REST API](https://docs.github.com/en/rest/actions/artifacts). 在此之前,您必须等待运行完成后才能获得身份证或使用任何API.
3.  艺术现在可以从UI下载并删除 _在此之前_ 整个工作流程完成.
4.  艺术作品的内容一起上传到 _不可改变_ 存档 。 以后的工作不能改变她们。 这两个因素都有助于减少意外地腐蚀Artifact文件的可能性. (Digest/Intigrity hash 即将出现在API!)
5.  这个图书馆(和 `actions/download-artifact`)现在支持下载Artiffacts from _其他项目_ 存储和运行,如果有 `GITHUB_TOKEN` 足够 `actions:read` 提供了权限.

### 中断更改

1.  自营跑道所需防火墙规则.
    
    如果你在防火墙后面使用自备跑道,你一定可以打开 [动作终点](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github)。如果无法使用通配符规则设置防火墙,请参见 GitHub [元终点](https://api.github.com/meta) 对于特定的终点.
    
    譬如说.
    
    ```bash
    curl https://api.github.com/meta | jq .domains.actions
    ```
    
2.  上传到同一名称的"艺术"多次.
    
    由于这个新版本中Artifacts是如何被创建的,因此已经无法再上传到同名的Artifact上多次. 您必须把上传内容分割成多个不同名称的艺术作品, 或者只上传一次 .
    
3.  限制个人工作的人工活性.
    
    工作流程运行中的每一项工作现在都有10件文物的限制.
    

## 快速启动

安装软件包 :

```bash
npm i @actions/artifact
```

导入模块 :

```js
// ES6 module
import {DefaultArtifactClient} from '@actions/artifact'

// CommonJS
const {DefaultArtifactClient} = require('@actions/artifact')
```

然后即时:

```js
const artifact = new DefaultArtifactClient()
```

iQQ 类、界面、功能和更多类的完整列表见 [生成的文件](https://npmcn.com/package/%40actions/artifact/docs/generated/README.md)。 。 。 .

## 实例

### 上传和下载

最基本的情况是将一个或多个文件上传到Artifact,然后下载Artifact. 下载基于Artifact ID,可以在响应中获取 `uploadArtifact`, (中文(简体) ), `getArtifact`, (中文(简体) ), `listArtifacts` 或通过 [(原始内容存档于2013-10-12) (英语). REST API](https://docs.github.com/en/rest/actions/artifacts)。 。 。 .

```js
const {id, size} = await artifact.uploadArtifact(
  // name of the artifact
  'my-artifact',
  // files to include (supports absolute and relative paths)
  ['/absolute/path/file1.txt', './relative/file2.txt'],
  {
    // optional: how long to retain the artifact
    // if unspecified, defaults to repository/org retention settings (the limit of this value)
    retentionDays: 10
  }
)

console.log(`Created artifact with id: ${id} (bytes: ${size}`)

const {downloadPath} = await artifact.downloadArtifact(id, {
  // optional: download destination path. otherwise defaults to $GITHUB_WORKSPACE
  path: '/tmp/dst/path',
})

console.log(`Downloaded artifact ${id} to: ${downloadPath}`)
```

### 删除艺术

要删除一件文物,只需要名字.

```js
const {id} = await artifact.deleteArtifact(
  // name of the artifact
  'my-artifact'
)

console.log(`Deleted Artifact ID '${id}'`)
```

它也支持从其他 repos/ runs 中删除选项, 给一个 github 令牌 `actions:write` 提供了目标寄存器上的权限.

```js
const findBy = {
  // must have actions:write permission on target repository
  token: process.env['GITHUB_TOKEN'],
  workflowRunId: 123,
  repositoryOwner: 'actions',
  repositoryName: 'toolkit'
}


const {id} = await artifact.deleteArtifact(
  // name of the artifact
  'my-artifact',
  // options to find by other repo/owner
  { findBy }
)

console.log(`Deleted Artifact ID '${id}' from ${findBy.repositoryOwner}/ ${findBy.repositoryName}`)
```

### 从其他工作流程下载运行或重置

从其他工作流程运行甚至其他寄存器中下载Artiffacts可能是有用的. 默认情况下,权限被范围化,因此只能在当前工作流程运行范围内下载Artiffacts. 要提升此方案的权限, 您必须指定 `options.findBy` 改为 `downloadArtifact`。 。 。 .

```ts
const findBy = {
  // must have actions:read permission on target repository
  token: process.env['GITHUB_TOKEN'],
  workflowRunId: 123,
  repositoryOwner: 'actions',
  repositoryName: 'toolkit'
}

await artifact.downloadArtifact(1337, {
  findBy
})

// can also be used in other methods

await artifact.getArtifact('my-artifact', {
  findBy
})

await artifact.listArtifacts({
  findBy
})
```

### 加快大型上传

如果您有需要上传的大文件(或压缩不完善的文件类型),您可能从改变Artifact归档的压缩级别中受益. 注:这是文物上传时间和所储存数据大小之间的取舍.

```ts
await artifact.uploadArtifact('my-massive-artifact', ['big_file.bin'], {
  // The level of compression for Zlib to be applied to the artifact archive.
  // - 0: No compression
  // - 1: Best speed
  // - 6: Default compression (same as GNU Gzip)
  // - 9: Best compression
  compressionLevel: 0
})
```

## 额外资源

-   [释放](https://npmcn.com/package/%40actions/artifact/RELEASES.md)
-   [贡献指南](https://npmcn.com/package/%40actions/artifact/CONTRIBUTIONS.md)
-   [经常被问到的问题](https://npmcn.com/package/%40actions/artifact/docs/faq.md)

## 常见问题

### @actions/artifact 是什么？

文物活动

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

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

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

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

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

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

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

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

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

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

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

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