GitHub Actions中npm ci执行失败，报错package.json与锁文件不同步

我配置了GitHub Actions在合并Pull Request前执行代码检查（比如cspell），但依赖安装步骤用npm ci时失败，报错如下：

npm ERR! code EUSAGE
npm ERR!
npm ERR! npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with npm install before continuing.

这个问题只在GitHub Actions里出现，本地相同Ubuntu系统、Node.js（20.12.0）及npm版本环境下完全正常。我已经试过以下操作，但都没用：

rm -rf node_modules
rm -rf packages/*/node_modules
npm cache clean --force
rm package-lock.json
npm install

失败的Job配置如下：

lint:
    runs-on: ubuntu-latest

    steps:
      # Get checkout
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      # Install Node js
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20.12.0'
          cache: 'npm'

      # Install Dependencies
      - name: Install dependencies
        run: |
          npm ci

      # Run Linting
      - name: Run lint check
        run: |
          npm run check:lint

可能的原因及解决方法 #

1. PR分支与主分支的lock文件不同步 #

如果你的PR分支基于旧的主分支提交，之后主分支的package-lock.json已经更新，但PR分支没同步，GitHub Actions拉取的代码里就会出现package.json和lock文件不匹配的情况。
解决步骤：

# 切换到主分支拉取最新代码
git checkout main
git pull
# 切回PR分支合并主分支
git checkout 你的PR分支名
git merge main
# 重新生成同步的lock文件
npm install
# 提交更新后的lock文件
git add package-lock.json
git commit -m "同步package-lock.json与主分支"
git push

2. GitHub Actions缓存干扰 #

actions/setup-node的cache: 'npm'可能缓存了旧的依赖或lock文件残留，导致npm ci校验不通过。
解决：临时禁用缓存测试，修改Job配置：

- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '20.12.0'
    # 注释掉缓存配置
    # cache: 'npm'

如果禁用后正常，说明缓存有问题。可以选择一直禁用缓存，或者去仓库的Settings -> Actions -> Cache里删除对应的npm缓存。

3. Monorepo子包lock文件不一致（如果是多包项目） #

如果是monorepo结构，子package的lock文件可能和根目录的不同步，npm ci会校验所有层级的lock文件。
解决步骤：

# 根目录执行，确保所有子包lock文件同步
npm install --workspaces
# 提交子包的lock文件更新
git add packages/*/package-lock.json
git commit -m "同步子包lock文件"
git push

4. npm版本细微差异 #

虽然本地和Actions都用Node.js 20.12.0，但自带的npm版本可能有细微差别（Node.js 20.12.0默认npm 10.5.0）。
解决：在Job中强制指定npm版本，和本地保持一致：

- name: Use Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '20.12.0'
    cache: 'npm'
    npm-version: '10.5.0'  # 替换成你本地的npm版本

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