GitHub Actions 制品管理 #

制品(Artifacts)允许你在工作流中存储和共享数据。本节详细介绍制品的上传、下载和管理。

制品概述 #

什么是制品？ #

制品是工作流产生的文件：

  • 构建产物
  • 测试报告
  • 日志文件
  • 任何需要保存的文件

制品特点 #

  • 跨作业共享
  • 工作流结束后可下载
  • 支持加密存储
  • 自动清理过期制品

制品限制 #

限制项 值
单个制品大小 无限制
总制品大小 仓库限制
保留时间 默认90天

上传制品 #

基本用法 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: dist/

完整参数 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    name: my-artifact           # 制品名称
    path: dist/                 # 文件路径
    retention-days: 5           # 保留天数
    compression-level: 6        # 压缩级别
    if-no-files-found: warn     # 无文件时的行为
    overwrite: false            # 是否覆盖

多文件上传 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: |
      dist/
      build/
      report.html

使用通配符 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    name: logs
    path: |
      **/*.log
      **/*.txt

下载制品 #

在同一工作流中下载 #

yaml 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: ./downloaded

下载所有制品 #

yaml 
- uses: actions/download-artifact@v4
  with:
    path: artifacts

下载特定制品 #

yaml 
- uses: actions/download-artifact@v4
  with:
    name: my-artifact
    path: ./downloaded
    pattern: '*.zip'

从其他工作流下载 #

yaml 
- uses: actions/download-artifact@v4
  with:
    name: my-artifact
    github-token: ${{ secrets.GITHUB_TOKEN }}
    repository: owner/repo
    run-id: ${{ github.event.workflow_run.id }}

实际应用示例 #

构建产物 #

yaml 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build
          path: ./dist
      
      - name: Deploy
        run: ./deploy.sh

测试报告 #

yaml 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --reporter junit --reporter-options output=junit.xml
      
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-report
          path: junit.xml

覆盖率报告 #

yaml 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --coverage
      
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

多平台构建 #

yaml 
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      
      - uses: actions/upload-artifact@v4
        with:
          name: build-${{ matrix.os }}
          path: dist/

  package:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: builds
      
      - name: List builds
        run: ls -la builds/

日志收集 #

yaml 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      
      - name: Run tests
        run: npm test 2>&1 | tee test.log
        continue-on-error: true
      
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: logs
          path: test.log

制品管理 #

查看制品 #

在GitHub网页上：

  1. 进入工作流运行页面
  2. 滚动到 “Artifacts” 部分
  3. 点击下载

使用GitHub CLI #

bash 
# 列出制品
gh run view <run-id> --json artifacts

# 下载制品
gh run download <run-id> -n <artifact-name>

删除制品 #

yaml 
- name: Delete artifact
  uses: geekyeggo/delete-artifact@v4
  with:
    name: my-artifact

制品示例 #

完整CI/CD流水线 #

yaml 
name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  test:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --coverage
      
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build
          path: ./dist
      
      - name: Deploy
        run: ./deploy.sh

最佳实践 #

1. 使用有意义的名称 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    name: build-${{ github.sha }}

2. 设置合理的保留时间 #

yaml 
- uses: actions/upload-artifact@v4
  with:
    retention-days: 7  # 临时制品

3. 条件上传 #

yaml 
- uses: actions/upload-artifact@v4
  if: always()  # 即使失败也上传

4. 压缩大文件 #

yaml 
- name: Compress
  run: tar -czf build.tar.gz dist/

- uses: actions/upload-artifact@v4
  with:
    name: build
    path: build.tar.gz

5. 清理旧制品 #

yaml 
- name: Delete old artifacts
  uses: c-hive/gha-remove-artifacts@v1
  with:
    age: '7 days'

下一步学习 #

小结 #

  • 制品用于存储和共享文件
  • 使用upload-artifact上传
  • 使用download-artifact下载
  • 支持跨作业共享
  • 设置合理的保留时间
  • 使用有意义的名称
最后更新：2026-03-28