GitHub Action缓存已恢复但cache-hit输出为false，单分支异常求助

可能的原因 #

• 缓存键生成逻辑不一致：异常分支的缓存键包含了分支名、环境变量等动态参数，导致和已缓存的键不匹配，但缓存内容实际兼容，所以恢复后仍标记未命中。
• package-lock.json存在隐性差异：比如换行符（LF/CRLF）、注释、resolved字段的细微差别，导致hash计算结果不同，缓存键不匹配，但node_modules内容一致。
• CI平台缓存判断机制：部分CI平台的cache-hit仅基于缓存键完全匹配，即使内容恢复成功，只要键不匹配就返回false。
• 缓存恢复不完整：权限问题、缓存文件损坏等导致node_modules目录存在但部分文件缺失，CI系统判定未命中。

排查步骤 #

1. 对比缓存键生成逻辑：检查异常分支和正常分支的CI配置，确认缓存键的组成（比如是否包含hashFiles('package-lock.json')、分支名、环境变量），看异常分支是否有特殊参数导致键变化。
2. 检查package-lock.json差异：
   • 用git diff对比异常分支和正常分支的package-lock.json，排查显性差异。
   • 用cat -A package-lock.json查看隐藏字符（如换行符、空格），确认是否有隐性格式差异。
3. 查看CI缓存日志：在CI控制台找到缓存恢复的详细日志，确认是否有报错、文件缺失提示，或者是否完全恢复了node_modules目录。
4. 手动计算hash值：在异常分支本地执行CI平台的hash计算命令（比如GitHub Actions的hashFiles('package-lock.json')），和缓存键中的hash对比，看是否一致。

解决办法 #

1. 统一缓存键逻辑：
   • 如果需要跨分支共享缓存，移除缓存键中的分支名、环境变量等动态参数，仅用package-lock.json的hash值：

     key: npm-${hashFiles('package-lock.json')}
     

   • 如果需要分支隔离，确保分支名变量正确传入，避免因分支名格式问题导致键不匹配。
2. 修复package-lock.json隐性差异：
   • 统一git换行符设置：git config core.autocrlf false，然后重新生成package-lock.json：npm install --package-lock-only，提交后重新运行CI。
   • 直接复制正常分支的package-lock.json到异常分支，确保完全一致。
3. 绕开cache-hit判断：
   不依赖CI平台的cache-hit输出，直接检查node_modules目录是否存在来决定是否执行npm ci，比如GitHub Actions中：

   - name: Restore node_modules cache
     uses: actions/cache@v3
     with:
       path: node_modules
       key: npm-${hashFiles('package-lock.json')}
   
   - name: Install dependencies
     run: |
       if [ ! -d node_modules ]; then
         npm ci
       fi
   

4. 重新生成缓存：在异常分支手动触发一次完整的npm ci，重新生成缓存，后续运行即可命中。

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