Gitea Action 构建缓存加速指南（实战七）

青萍叙事2025-07-26

📝 前言

这是 DevOps 专题的第十篇，回顾一下前几篇的内容：

基本概念介绍：《从阿里云效到自建DevOps平台：Gitea入门介绍》
快速部署 Gitea 实例：《使用 Docker 快速部署 Gitea 指南（实战一）》
部署 CI/CD 工具：《使用二进制部署 Gitea Runner 指南（实战二）》
部署镜像仓库：《离线部署 Harbor 企业级镜像仓库指南》
Gitea Action 入门：《Gitea Actions 工作流入门指南（实战三）》
Gitea Action 远程部署：《Gitea Action 远程部署指南（实战四）》
Gitea Action 定时与手动构建：《Gitea Action 定时构建和手动构建指南（实战五）》
Harbor 镜像代理配置：《Harbor 镜像代理仓库配置指南》
Gitea Action 构建多架构镜像：《Gitea Action 构建多架构镜像指南（实战六）》

这一篇我们继续介绍如何使用 Gitea Actions 来配置构建缓存，从而大幅提升构建性能，缩减构建时间。

🧭 背景介绍

随着 DevOps 与自托管 CI/CD 的普及，Gitea Action 作为 Gitea 的内建 CI 解决方案，越来越多被用于中小团队的日常开发与部署流程中。

在每次构建过程中，重复下载安装依赖包是最常见、最耗时的操作。

如何进一步提高构建效率是大家比较关注的问题。

本指南将围绕构建缓存的加速实践展开，帮助你最大化地利用本地资源、提升构建效率，打造更流畅的开发体验。

🔍 使用场景

主要适用于以下场景：

构建时间长、依赖复杂的项目（如 Node.js、Java、Python、Go）
依赖包重复下载安装（如 npm、pip、maven、go modules）
希望将依赖缓存至宿主机或远程缓存服务

📋 前提条件

在开始前，请确认以下环境准备已完成：

已部署 Gitea 1.21+，并开启 Actions 功能（默认开启，部署文章参看：《使用 Docker 快速部署 Gitea 指南（实战一）》）
Gitea Runner 已正确注册并运行（可参看文章：《使用二进制部署 Gitea Runner 指南（实战二）》）

🚀 详细步骤

1️⃣ 编写工作流文件

这里我们以一个前端的项目为例，该项目使用yarn作为包管理器。

创建.gitea/workflows/build.yaml文件，内容参考如下：

# 已隐藏部分配置，限于篇幅这里仅展示关键 action
jobs:
  build:
    runs-on: host
    outputs:  # 声明作业的输出变量
      datetime: ${{ steps.datetime.outputs.datetime }}
    steps:
    #.....省去拉取源码等其他配置....
      - name: Cache dependencies
        # 官方地址: actions/cache@v4
        uses: http://git.luhome.com/actions/cache@v4
        id: yarn-cache
        with:
          # 配置需要缓存的路径
          path: |
            ~/.cache/yarn
            .next/cache
            node_modules
          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-
		

       # 安装依赖 (如果缓存未命中，才会执行)
      - name: Install dependencies
        run: |
          yarn config set registry https://registry.npmmirror.com/
          yarn install
        if: steps.yarn-cache.outputs.cache-hit != 'true'
      
       # 这里将 yarn 命令进行拆分，不再将依赖安装和构建放到一起
      - name: static build
        run: |
          yarn build

配置说明：

cache action: 这次我们引入了一个新的action cache，这是官方提供的专门用于构建时存储和恢复缓存的。
path: 指定要缓存的文件或目录路径，我这里列的是NodeJS的常见路径，如果是其他语言需要换成别的，比如Java 就缓存~/.m2/repository。
key: 缓存的唯一键，这里我是通过生成yarn.lock的hash作为键的一部分，当yarn.lock 文件发生变更，如引入新的依赖时，缓存就失效。
restore-keys: 缓存模糊查找关键词，当 key 没有命中缓存时，系统会依次尝试用restore-keys中的前缀模糊匹配已有缓存。我这里直接写的是很大返回的一个路径，这样即使lock文件轻微改动也能复用部分缓存，避免完全从零开始。
steps.yarn-cache.outputs.cache-hit: 在安装依赖的步骤中我们新添加了一个**if判断**，这是由cache action提供的一个变量，当输出为true时则代表命中了缓存，我这里是判断不为true才执行这个步骤，也即是未命中缓存执行安装依赖。