GitHub Actions无法命中npm缓存问题求助

一、npm ci 缓存不命中的核心问题 #

你当前缓存的是~/.npm（npm全局缓存目录），但npm ci的行为是严格按照package-lock.json直接安装依赖到项目的node_modules目录，并不会通过复用~/.npm来跳过安装步骤——这就是为什么缓存键存在却始终提示未命中，且每次都要重新执行npm ci的原因。

修正配置： #

将缓存路径改为项目的node_modules目录，保留基于package-lock.json的哈希键：

- name: Cache node modules
  id: cache-npm-modules
  uses: actions/cache@v2
  env:
    cache-name: cache-node-modules
  with:
    path: ${{ github.workspace }}/node_modules
    key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('package-lock.json') }}

- if: ${{ steps.cache-npm-modules.outputs.cache-hit != 'true' }}
  run: npm ci

额外验证点： #

• 确认缓存条目的runner.os与当前一致：跨操作系统（如Windows→Linux）的缓存无法互通。
• 检查package-lock.json是否被意外修改：若有步骤自动更新lock文件，会导致哈希值变化，缓存键直接失效。

二、npm run prod 缓存反复生成不复用的问题 #

你用public/**/*的哈希作为缓存键，逻辑完全倒置：npm run prod是生成静态资源到public目录，每次构建后public内容必然变化，哈希值随之改变，导致每次都生成新缓存，永远无法复用。

正确逻辑应该是：基于构建依赖文件的哈希生成缓存键（比如源码、构建配置），缓存构建输出的public目录。

修正配置示例： #

假设构建依赖src目录源码和webpack.mix.js配置，配置如下：

- name: Cache production assets
  id: cache-prod-assets
  uses: actions/cache@v2
  env:
    cache-name: cache-prod-assets
  with:
    path: public
    key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('src/**/*', 'webpack.mix.js', 'package-lock.json') }}

- if: ${{ steps.cache-prod-assets.outputs.cache-hit != 'true' }}
  run: npm run prod

三、通用注意事项 #

1. 建议升级actions/cache到v3版本，兼容性与稳定性更好。
2. 用${{ github.workspace }}作为项目根目录绝对路径，避免相对路径带来的歧义。
3. 到仓库的「Actions→管理缓存」页面，核对缓存条目的键名、路径是否与当前配置完全匹配。

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