Docker构建时yarn install返回非零代码1的调试方法及远程包校验和不匹配是否为故障原因的咨询

Let's break down how to debug this issue, starting with verifying if that checksum mismatch is indeed the culprit, then walking through actionable steps to fix it.

First: Confirm the Checksum Mismatch is the Root Cause #

The error "The remote archive doesn't match the expected checksum" absolutely can cause yarn install to fail with a non-zero exit code. When Yarn downloads a package, it compares the file's checksum against the one listed in your lockfile (yarn.lock). If they don't match, Yarn aborts to prevent potentially malicious or corrupted packages from being installed.

Since your local build works, the issue is likely specific to the Jenkins environment or the network path it uses to download packages. Here's how to debug and resolve this:

Step 1: Capture the Full Yarn Error Log #

The truncated log you shared only tells us the install failed, but we need the complete output to see exactly which package is failing the checksum check. Modify your Dockerfile to enable verbose logging:

# Replace your existing yarn install line with:
RUN yarn install --verbose

This will print detailed logs including the problematic package and checksum mismatch details, which is critical for targeting the fix.

Step 2: Clear Caches (Docker and Jenkins) #

Corrupted caches in either the Docker build context or Jenkins agent are a common culprit for checksum issues.

Clean Docker's Yarn Cache #

Update your Dockerfile to clean the cache thoroughly before installing dependencies:

RUN yarn cache clean --all  # Clears all cached packages
RUN yarn install --verbose

Clear Jenkins Agent's Cache #

If your Jenkins agent reuses a workspace or has a persistent Yarn cache, delete it before the build. Add a shell step in Jenkins before the Docker build:

rm -rf ~/.yarn/cache
rm -rf ./node_modules  # If the workspace has leftover modules

Note: Only delete yarn.lock if you're sure it's outdated—first confirm your local lockfile matches the one in version control.

Step 3: Fix Network/Registry Inconsistencies #

Jenkins might be using a proxy, corporate network, or different registry that serves corrupted or outdated package archives.

• Compare registries: Run yarn config get registry locally, then add this to your Dockerfile's build stage to check Jenkins's registry:

  RUN yarn config get registry
  

  If they differ, set the registry explicitly to match your local setup:

  RUN yarn config set registry https://registry.yarnpkg.com/
  

• Ensure Jenkins has unobstructed access to the registry—corporate proxies sometimes modify package files, breaking checksums.

Step 4: Lock Yarn Version for Consistency #

Your Dockerfile uses yarn set version latest, which means each build could pull a different Yarn version. If your local Yarn version differs from Jenkins's, this can lead to checksum or resolution mismatches.

• Run yarn --version locally to get your working version, then pin it in the Dockerfile:

  # Replace these lines:
  # RUN yarn set version berry
  # RUN yarn set version latest
  # With your local version (e.g., 4.0.2):
  RUN yarn set version 4.0.2
  

Step 5: Verify Lockfile Consistency #

Make sure the yarn.lock file in your Git repo matches the one you use locally. Outdated lockfiles (from forgotten commits) often cause checksum mismatches:

• Run diff yarn.lock <(git show HEAD:yarn.lock) locally to confirm your local lockfile matches the repo's version.
• If there are differences, commit the updated lockfile to Git and trigger a new Jenkins build.

Step 6: Recreate the Lockfile (Last Resort) #

If the lockfile is corrupted or has inconsistent checksums, recreate it locally and commit it:

1. Delete your local lockfile and modules:

   rm -rf yarn.lock node_modules
   

2. Run yarn install locally to generate a fresh lockfile.
3. Commit the new lockfile to Git and try the Jenkins build again.

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