阿超 > GitHub Actions 缓存升级：从 v2 直接跳到 v4 的最佳实践

GitHub Actions 缓存升级：从 v2 直接跳到 v4 的最佳实践

2025-07-08

小技巧

文变染乎世情，兴废系乎时序。一一刘勰

随着 GitHub 官方宣布即将关闭 actions/cache v1 和 v2 的支持，越来越多的项目维护者开始将缓存插件升级到更高版本。与其先升级到 v3 再考虑 v4，为何不一步到位，直接用上最新版？本文结合实际案例，分享如何将 Actions 缓存插件直接从 v2 升级到 v4，并解读背后的技术优势与注意事项。

1. 为什么要升级到 v4？

  • 官方强制：2024 年底后所有使用 v1/v2 的 workflow 将直接报错，工作流无法继续执行。
  • v4 新特性与优势：
    • 支持更大的缓存（单个缓存最大 10GB，v2 仅 5GB）
    • 性能优化，缓存恢复更快
    • 更完善的安全策略和依赖校验
    • 支持自定义 save-always 等新参数，灵活性更好
    • 官方长期维护，bug 修复及时

2. 升级方法一览

假设你原来的 workflow 片段如下：

1
2
3
4
5
- name: Cache Maven packages
  uses: actions/cache@v2
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

升级到 v4 只需一行变更：

1
2
3
4
5
- name: Cache Maven packages
  uses: actions/cache@v4
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

其他参数完全兼容，原有用法无需调整。

3. 实战案例对比

升级前：

1
2
3
4
5
- name: Cache Maven packages
  uses: actions/cache@v2
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

升级后（v4）：

1
2
3
4
5
- name: Cache Maven packages
  uses: actions/cache@v4
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

进阶用法（v4 新增参数）：

1
2
3
4
5
6
7
8
- name: Cache Maven packages
  uses: actions/cache@v4
  with:
    path: ~/.m2
    key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
    restore-keys: |
      ${{ runner.os }}-m2-
    save-always: true

4. 常见问题与注意事项

  • 兼容性：绝大多数 v2 用法无需修改即可兼容 v4。

  • 缓存大小限制提升：单缓存 10GB，适合大型 monorepo 项目。

  • 出错提示：如果 workflow 仍然写的是 v2，GitHub 会直接报错并提示升级。

  • 多仓库批量升级：可用脚本一键替换，提升效率：

    1
    find .github/workflows -type f -name "*.yml" -exec sed -i 's/actions\/cache@v2/actions\/cache@v4/g' {} +

5. 总结

直接将缓存插件升级到 v4，是应对 GitHub Actions 平台升级的最优解。它不仅提升了缓存性能，也为持续集成工作流带来了更高的稳定性和安全性。建议所有项目都提前完成升级，避免因后续强制下线而导致 CI/CD 中断。

参考资料