GitHub Actions 依赖缓存 #

缓存可以显著加速工作流执行，减少依赖下载时间。本节详细介绍如何使用缓存机制。

缓存概述 #

什么是缓存？ #

缓存是存储和复用依赖项的机制：

存储依赖文件
跨工作流复用
减少下载时间
加速构建过程

缓存限制 #

限制项	值
单个缓存大小	10GB
总缓存大小	10GB
缓存保留时间	7天（默认）

使用actions/cache #

基本用法 #

yaml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

参数说明 #

参数	描述
`path`	缓存路径
`key`	缓存键（唯一标识）
`restore-keys`	备用键列表
`upload-chunk-size`	上传块大小

缓存键策略 #

基于依赖文件 #

yaml

key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

基于分支 #

yaml

key: ${{ runner.os }}-npm-${{ github.ref }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  ${{ runner.os }}-npm-${{ github.ref }}-
  ${{ runner.os }}-npm-

基于日期 #

yaml

key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}-${{ github.run_id }}
restore-keys: |
  ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}-
  ${{ runner.os }}-npm-

语言特定缓存 #

Node.js #

yaml

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

# 或手动配置
- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Python #

yaml

- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: 'pip'

# 或手动配置
- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/pip
      ~/.local/lib/python*/site-packages
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

Go #

yaml

- uses: actions/setup-go@v5
  with:
    go-version: '1.21'
    cache: true

# 或手动配置
- uses: actions/cache@v4
  with:
    path: |
      ~/go/pkg/mod
      ~/.cache/go-build
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

Java/Maven #

yaml

- uses: actions/cache@v4
  with:
    path: ~/.m2/repository
    key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

Java/Gradle #

yaml

- uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

Rust #

yaml

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

PHP/Composer #

yaml

- uses: actions/cache@v4
  with:
    path: |
      ~/.composer/cache
      vendor
    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}

Ruby/Bundler #

yaml

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.2'
    bundler-cache: true

# 或手动配置
- uses: actions/cache@v4
  with:
    path: |
      vendor/bundle
      ~/.bundle
    key: ${{ runner.os }}-bundler-${{ hashFiles('**/Gemfile.lock') }}

多路径缓存 #

yaml

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ~/.cache
      node_modules
    key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}

缓存恢复 #

检查缓存命中 #

yaml

- uses: actions/cache@v4
  id: cache
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

- name: Check cache hit
  run: |
    if [ "${{ steps.cache.outputs.cache-hit }}" == "true" ]; then
      echo "Cache hit!"
    else
      echo "Cache miss!"
    fi

使用restore-keys #

yaml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ github.ref }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-${{ github.ref }}-
      ${{ runner.os }}-npm-

缓存管理 #

查看缓存 #

bash

gh cache list

删除缓存 #

bash

gh cache delete <cache-key>

清理旧缓存 #

yaml

- name: Clean up old caches
  run: |
    gh cache delete --all
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

缓存示例 #

完整CI工作流 #

yaml

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Cache node modules
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-modules-
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Test
        run: npm test

多语言项目 #

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Cache Node.js
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      
      - name: Cache Python
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - run: npm ci
      - run: pip install -r requirements.txt

矩阵构建缓存 #

yaml

jobs:
  test:
    strategy:
      matrix:
        node: [16, 18, 20]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'
      
      - run: npm ci
      - run: npm test

最佳实践 #

1. 使用语言特定的缓存 #

yaml

# 推荐
- uses: actions/setup-node@v4
  with:
    cache: 'npm'

2. 使用hashFiles生成键 #

yaml

key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

3. 设置restore-keys #

yaml

restore-keys: |
  ${{ runner.os }}-npm-

4. 避免缓存过大 #

yaml

# 只缓存必要文件
path: ~/.npm

5. 定期清理缓存 #

bash

gh cache delete --all

下一步学习 #

制品管理 - 学习制品上传下载
工作流产物 - 了解作业间通信
实战案例 - 查看完整示例

小结 #

缓存加速依赖安装
使用hashFiles生成唯一键
设置restore-keys提高命中率
语言特定的setup动作内置缓存
注意缓存大小限制
定期清理旧缓存