GitHub Actions缓存恢复成功但cache-hit为false问题排查

两个配置错误直接导致缓存逻辑不生效：

• 对cache-hit返回值的规则理解错误
  actions/cache@v3的cache-hit输出，仅在缓存完全精确匹配key字段配置的完整键值时才会返回true。如果是通过restore-keys前缀模糊匹配恢复的缓存，哪怕日志打印Cache restored successfully，该字段值依然为false。
  你日志里显示恢复的key是Linux-npm-...带省略后缀，说明实际命中的是前缀匹配的历史缓存，没有匹配上和当前package-lock.json哈希绑定的精确key，所以if判断条件始终成立，每次都会触发安装步骤。
• 缓存路径配置不全
  你当前只缓存了~/.npm这个npm全局下载缓存目录，但npm ci命令执行时默认会先清空项目本地的node_modules目录，再重新写入依赖文件。哪怕全局缓存命中，npm ci依然要执行解压、写入本地文件的流程，根本无法实现跳过安装的效果。

根据你的场景二选一即可：

方案一：缓存node_modules实现安装步骤跳过（单项目推荐，速度最快） #

缓存范围同时覆盖全局npm缓存和项目本地node_modules目录，精确命中缓存时直接跳过安装步骤：

- name: Cache npm dependency
  uses: actions/cache@v3
  id: npm-cache
  with:
    path: |
      ~/.npm
      node_modules
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

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

注意：判断cache-hit时给true加单引号做字符串比较，避免YAML布尔类型解析差异导致判断失效。

方案二：仅缓存全局npm缓存（monorepo多包项目推荐） #

如果是多包仓库，直接缓存全局npm目录即可，不需要加跳过安装的判断。npm ci执行时会优先从全局缓存读取依赖包，不需要走公网下载，速度同样会比无缓存场景快70%以上：

- name: Cache npm dependency
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- name: Install Dependency
  run: npm ci

• 部分npm版本的全局缓存路径不在默认的~/.npm，可以在安装前执行npm config get cache打印实际路径，避免路径写错导致缓存失效。
• 模糊匹配到旧缓存时，不要给npm ci加强制离线参数，npm会自动拉取和当前lockfile不一致的差异包，不会出现依赖版本错误。

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