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

随着 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 中断。


参考资料