极速Angular CI：自托管Runner上的本地持久化node_modules缓存

核心思路 #

放弃GitLab CI的压缩式缓存，直接利用Runner主机本地磁盘存储node_modules，通过package-lock.json的哈希值作为唯一标识：

• 哈希未变时，直接在项目目录创建软链接指向已缓存的node_modules，跳过所有安装/解压操作
• 哈希变更时，执行一次npm ci，然后将新的node_modules存入缓存目录，后续任务直接复用

1. Runner 配置（config.toml） #

使用shell执行器（必须，因为要直接操作主机本地磁盘），并确保Runner用户有缓存目录的读写权限：

步骤1：修改config.toml #

找到你的Runner配置段（[[runners]]），确保以下配置：

[[runners]]
  name = "Your Runner Name"
  url = "https://your-gitlab-instance.com/"
  token = "your-runner-token"
  executor = "shell"
  # 可选：指定构建目录，确保路径无特殊字符
  builds_dir = "/var/gitlab-runner/builds"
  cache_dir = "/var/gitlab-runner/cache"

步骤2：创建全局缓存目录 #

在Runner主机上创建用于存储node_modules的目录，并授权给gitlab-runner用户：

sudo mkdir -p /var/gitlab-runner/node_modules_cache
sudo chown -R gitlab-runner:gitlab-runner /var/gitlab-runner/node_modules_cache

2. CI Pipeline 配置（.gitlab-ci.yml） #

通过哈希判断缓存是否存在，实现软链接复用或重新安装缓存：

stages:
  - prepare
  - build
  - test

# 通用的prepare阶段：处理node_modules缓存
prepare_node_modules:
  stage: prepare
  script:
    # 计算package-lock.json的SHA256哈希，取前16位作为缓存目录名
    - LOCK_HASH=$(sha256sum package-lock.json | cut -d' ' -f1 | head -c16)
    - CACHE_DIR="/var/gitlab-runner/node_modules_cache/${CI_PROJECT_PATH_SLUG}-${LOCK_HASH}"
    
    # 如果缓存目录存在，直接创建软链接
    - if [ -d "$CACHE_DIR" ]; then
        rm -rf node_modules;
        ln -s "$CACHE_DIR" node_modules;
        echo "✅ 复用缓存的node_modules（哈希：$LOCK_HASH）";
      else
        # 缓存不存在，执行npm ci并保存到缓存目录
        echo "🔧 无匹配缓存，执行npm ci...";
        npm ci;
        mkdir -p "$(dirname "$CACHE_DIR")";
        mv node_modules "$CACHE_DIR";
        ln -s "$CACHE_DIR" node_modules;
        echo "✅ 新缓存已保存（哈希：$LOCK_HASH）";
      fi
  # 持久化软链接到后续阶段
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

# 示例build阶段
build_project:
  stage: build
  needs: ["prepare_node_modules"]
  script:
    - npm run build

# 示例test阶段
test_project:
  stage: test
  needs: ["prepare_node_modules"]
  script:
    - npm run test

关键细节说明 #

• 哈希计算：用sha256sum取前16位，既保证唯一性又避免目录名过长；如果是Windows Runner，可替换为Get-FileHash package-lock.json -Algorithm SHA256 | Select-Object -ExpandProperty Hash | Select-Object -First 16
• npm ci vs npm install：优先用npm ci，它严格按照package-lock.json安装，避免版本不一致，且速度更快
• 软链接优势：创建软链接几乎是瞬时操作，完全跳过压缩/下载/解压步骤
• 缓存目录命名：加入CI_PROJECT_PATH_SLUG（GitLab内置变量，项目路径的短标识），避免不同项目的缓存冲突
• 权限问题：确保gitlab-runner用户对/var/gitlab-runner/node_modules_cache有读写权限，否则无法创建目录和软链接

内容的提问来源于stack exchange，提问作者FanLife