📚 课程目录第4章文件级缓存键策略

文件级缓存键策略：锁定文件、项目文件、环境变量影响

CI/CD 流水线中，缓存一致性最直接的保障手段是 精确定义缓存键。文件级缓存键策略将锁定文件、项目描述文件及环境变量纳入键计算，确保当依赖、构建参数或运行环境发生任何实质性变化时，缓存自动失效并重建。本讲深入原理、给出实现流程与完整配置示例，并分析常见陷阱。

核心原理：依赖图谱与变更检测

缓存键本质是一个字符串哈希，用于标识缓存的目标内容。若键相同，则直接复用缓存；若不同，则视为新缓存。文件级缓存键策略的核心在于：

锁定文件（Lockfile）：如 package-lock.json、yarn.lock、requirements.txt（对 pip 而言其哈希作用等效）、Gemfile.lock 等。它们精确记录了每个依赖的版本、来源和校验值，锁定文件变化意味着依赖树发生变动。
项目文件（Project File）：如 package.json、setup.py、pom.xml、build.gradle。这些文件定义顶层依赖和构建配置，它们的变更可能不改变锁定文件（如添加一条注释），但调整了构建行为或依赖范围。
环境变量（Environment Variable）：如 CI=true、BUILD_TARGET=release、NODE_ENV=production、SSL 版本标志等。环境变量影响二进制兼容性、编译选项或运行时行为，即使代码未变，环境变量不同也应使用不同缓存。

三者的组合形成了缓存键的唯一性：hash(lockfile + projectfile + env_vars)。流水线中计算该哈希并与存储键比对，若不同则缓存失效。

实现流程与配置示例

以 GitHub Actions 与 npm 项目为例，实现精确文件级缓存键的典型步骤如下：

从流水线上下文中提取锁定文件（package-lock.json）、项目文件（package.json）以及选定的环境变量（如 NODE_ENV）。
计算这些内容的 SHA256 或 MD5 哈希，拼接成v1-{hash}格式的缓存键。
尝试通过该键加载缓存。若命中则跳过 npm ci；若未命中则安装依赖，并保存新缓存。

# .github/workflows/ci.yml 关键段
- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: node_modules
    key: v1-npm-
    {{
      hashFiles('package-lock.json') }}-{{
      hashFiles('package.json') }}-${{
      env.NODE_ENV }}

- name: Install dependencies
  if: steps.cache.outputs.cache-hit != 'true'
  run: npm ci

对于 Gradle（Java）项目，通常需要纳入 build.gradle、settings.gradle 和 Gradle 发行版缓存：

- name: Cache Gradle packages
  uses: actions/cache@v4
  with:
    path: ~/.gradle/caches
    key: v1-gradle-
    {{
      hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}-${{
      env.GRADLE_JDK_VERSION }}

  实现要点：环境变量必须明确选择与构建结果强关联的变量。例如 BUILD_NUMBER 通常不应纳入（因为它每次变化导致缓存永久失效），而 NODE_ENV、GCC_VERSION、CUDA_VERSION 等应纳入。

调试：验证缓存键与失效原因

在流水线日志中查看缓存键的实际值。GitHub Actions 输出的缓存日志示例：

Cache restored from key: v1-npm-6f2c3b1a1e-9a8c7d6e5- production
Cache location: ghcache/v1/...
Hit: true

若未命中，日志会显示 Miss: cache not found。此时可检查三个输入中哪个发生了变化。常见调试方法：

在本机计算 hashFiles('package-lock.json') 与流水线输出比对，确认锁定文件是否意外改动。
检查环境变量是否因为分支差异（如 DEBUG=true）而不同。
使用 actions/cache/restore 的 fail-on-cache-miss 参数让未命中时立即报错，方便定位。

常见错误与规避

错误场景	后果	解决方案
只使用项目文件，忽略锁定文件	锁定文件变更但项目文件未变时仍命中老旧缓存，导致依赖冲突	同时将锁定文件纳入哈希计算
将运行时变量（如 `GITHUB_RUN_ID`）加入键	每次运行缓存都不同，完全失去复用效果	只选择影响编译/依赖的变量
使用通配符 `hashFiles('**')` 包含无关文件	任何文件改动（含README、图片）都会导致缓存失效	精确限定依赖相关的文件列表
环境变量值含有空格或敏感字符	哈希计算不一致或泄露凭据	先使用 `jq` 等工具标准化变量值，再传入

性能与稳定性优化

采用 fallback 键：当精确键未命中时，使用一个泛化键（如只基于锁定文件）尝试部分恢复缓存。例如 restore-keys: v1-npm- 可以匹配历史缓存，加速依赖安装。
减少哈希计算次数：将多个文件哈希值合并后再整体哈希，而非拼接原始哈希字符串（避免超长键）。
锁定文件版本对齐：在 mono-repo 中使用 lockfileVersion: 2 等确保跨工作区一致性。
避免跨平台环境变量干扰：将操作系统名称（ubuntu-latest、windows-latest）加入缓存键前缀，否则同一键在不同平台下拿到的二进制缓存无效。

最佳实践：在流水线第一步打印出最终的缓存键字符串，用于人工审计。例如：echo "CACHE_KEY=v1-${{ hashFiles('package-lock.json') }}-${{ env.NODE_ENV }}"。这使得调试时能直接对比预期键与实际键。

完整部署示例（GitHub Actions + npm）

name: CI with Cache
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Compute cache key
        id: cache-key
        run: echo "key=v1-npm-$(sha256sum package-lock.json package.json | sha256sum)-${{ env.NODE_ENV }}" >> $GITHUB_OUTPUT

      - name: Restore cache
        id: cache
        uses: actions/cache/restore@v4
        with:
          path: node_modules
          key: ${{ steps.cache-key.outputs.key }}
          restore-keys: |
            v1-npm-

      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: npm ci

      - name: Save cache
        if: steps.cache.outputs.cache-hit != 'true'
        uses: actions/cache/save@v4
        with:
          path: node_modules
          key: ${{ steps.cache-key.outputs.key }}

      - name: Build
        run: npm run build

该流程中显式分离了 restore 与 save 步骤，便于调试。当缓存未命中时，npm ci 完成后将新缓存保存，后续运行即可复用。