两个代理同时加依赖，package-lock.json 冲突了：怎么解才不会顺手升级一百多个包？（中英切换）

Wednesday afternoon. The agent on machine 1 is adding zustand to the frontend; the agent on machine 2 has just merged its PR adding zod into main. Machine 1's agent pulls main to rebase and stops on package-lock.json: a few conflict hunks, a few dozen lines. It does what the most common answer online says: delete the lockfile, npm install, regenerate, tests pass, push.

Machine 1 is a Mac. Once the PR is pushed, both Linux CI and the Windows check on machine 6 fail in vite build. The CI error:

Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to optional
dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after
removing both package-lock.json and node_modules directory.

(On machine 6 the missing one is @rollup/rollup-win32-x64-msvc.) The next agent does what the error says: delete node_modules and package-lock.json, reinstall, all green. Review lands on machine 4, which sees a PR titled "Fix CI build" with more than 1,200 lockfile lines changed and new versions of axios, vite, react-dom, esbuild and rollup. Nobody reads that diff line by line; the review agent will most likely write "lockfile regenerated, expected changes" and move on.

We are three people with seven computers, and agents open a dozen-plus PRs a day. Adding a dependency is one of the most ordinary kinds. What I care about: when two branches each add a dependency and the lockfile conflicts, how should the agent resolve it, and how does CI notice when it gets it wrong?

My position: don't treat the lockfile as code to be "merged". It is computed from package.json plus the already-reviewed lock on main. Resolving a conflict means computing it again from main's lock, adding only what package.json now asks for; then CI proves every change in the lock traces back to some change in package.json. I measured deleting the lock, deleting node_modules too, picking ours/theirs, taking the union of both sides, and letting npm fix it automatically. Each breaks in its own way, and two of them break quietly.

Lab: 66 pairs of branches, 20 conflicts

Toy repo shop-web: React 19, Vite 7, Vitest 3, ESLint 9, axios. The lock was produced with npm install --before=2025-09-01: 251 packages, 3,490 lines, like a real project whose dependencies haven't moved much in over a year. Twelve common small dependencies (zod, date-fns, @tanstack/react-query, clsx, dayjs, react-router-dom, uuid, nanoid, zustand, immer, and dev deps msw, @testing-library/react), one branch each, added with today's npm.

First, a guess of mine that was wrong. I expected different npm versions on different machines (9, 10, 11) to flip the lockfile format back and forth, so that a single PR would carry large unrelated diffs. They didn't: npm 9 adding react-query was 31 lines, npm 10 adding zod was 12, npm 11 adding date-fns was 11 added lines, lockfileVersion was 3 throughout, and the three branches merged in git without conflicts. One agent adding one dependency on its own produces a clean lock diff.

The trouble starts when two branches arrive together. Twelve branches give 66 pairs, each simulating "main already has A, agent branch B merges main":

• 46 pairs merged automatically in git, and all 46 passed npm ci.
• 20 pairs conflicted (about 30%): 16 in both package.json and the lock, 4 in the lock only. Nearly all conflicts sit in the same places: two dependencies that are alphabetical neighbours inserted into dependencies, and both new package entries appended to the end of packages.

If two or three PRs a day add dependencies, that rate is enough to hit this several times a week.

Seven ways to resolve it, and how each breaks

For these 20 conflicts the agent's workspace already had node_modules installed (as it would in real life), npm 10.9.8, and package.json was first resolved the same way every time ("keep both sides' new deps"). Then the lockfile was handled in seven different ways:

The "guard" is lockguard.py, which I describe below. The thing to notice first: the middle three rows are 20/20 green on npm ci and tests. A CI that only installs and tests stops none of them.

Pick a side (ours / theirs): 0/20. The lock lacks the other side's dependency and npm ci fails with EUSAGE, saying package.json and the lock are out of sync. This is the best way to fail, because it fails on the spot.

Union (git merge-file --union, or an agent keeping both sides by hand): 12/20 were not valid JSON, with commas and braces that don't line up; 8/20 happened to be valid, and correct. It looks usable, but it depends on where the conflict hunks happen to be cut. That's luck.

Delete the lock and reinstall (keeping node_modules): 20/20 pass, but every pair lost 45 platform package entries. Rollup and esbuild ship their native binaries as twenty-odd optional dependencies split by platform, and a healthy lock lists them all (21 for rollup, 26 for esbuild). When npm 10 regenerates a lock with node_modules present, it writes what is actually installed on this machine, so only Linux x64 remains. That's npm/cli#4828, fixed in npm 11.3.0.

I walked this chain across two "machines": install a Mac node_modules with --os=darwin --cpu=arm64, delete the lock, npm install again. The lock's rollup platform packages shrink to a single rollup-darwin-arm64. Take that lock to Linux and npm ci: exit code 0, looks fine. vite build: exit code 1 with the error at the top of this post, and vitest fails too. Delete the lock on Linux and simulate machine 6 with --os=win32 --cpu=x64: the Windows rollup and esbuild binaries are both missing. The same experiment with npm 11.21.1 keeps all 21 rollup entries, and build and tests pass.

Delete the lock and node_modules together: the fix the error message itself recommends. 20/20 pass, the platform packages are back, and the price is that the whole tree is resolved again as of today: in every pair 124 to 129 packages changed version, 11 more were added and 3 removed. axios 1.11.0→1.21.0, react-dom 19.1.1→19.3.1, vite 7.1.3→7.3.7, esbuild 0.25.9→0.28.2, rollup 4.50.0→4.65.1, eslint 9.34.0→9.39.5, and axios's dependency proxy-from-env went 1.1.0→2.1.0, a major version. That count is conservative: react and a few others happen to sit in the new dependencies' closure, so my guard counts them as "explained". How many packages move depends on how old the lock is. Mine stopped at 2025-09-01; if you update weekly it will be far fewer, but not zero.

These upgrades are probably fine, and the tests all pass. The problem is that they ride inside a PR about adding zustand, nobody reviewed them, and if something breaks nobody will find them from the title.

Leave the markers and let npm fix it: npm's docs say that npm install resolves a lockfile that contains conflict markers. For 10 of the 20 pairs it did so nicely; the other 10 lost the 45 platform entries just like deleting the lock. Rerunning a failing pair with --loglevel silly shows why:

npm verbose shrinkwrap failed to load package-lock.json Expected double-quoted property
name in JSON ... near "...m\": \"^19.1.1\",      },      \"devDependen..."

When npm rebuilds the two sides from the conflicted file, one side ends up with a trailing comma and fails to parse. npm doesn't error. It leaves one line in the verbose log, treats the project as having no lockfile, and regenerates from node_modules. At the default log level you see nothing. I then ran 4 conflicts under npm 10/11, with and without node_modules. The two that parse were fine in all four configurations. For the two that don't: npm 10 with node_modules loses the platform packages, npm 11 with node_modules is clean, and without node_modules both npm 10 and 11 re-resolve the whole tree, changing 142 to 143 packages. So moving to npm 11 doesn't make "let npm fix it" safe; it only fixes one of the cases.

Start from main's lock and add the deps: git show origin/main:package-lock.json > package-lock.json, then npm install --package-lock-only. 20/20 pass, both dependencies present, no stray upgrades at all, slowest run 0.9 seconds. The idea is simple: main's lock has been reviewed and has no conflict in it; package.json has been resolved by hand; npm only has to add the missing dependency, and --package-lock-only doesn't touch node_modules, so it doesn't write the lock from whatever happens to be installed locally.

A fourth trap: mirror URLs travel with the lock

Machines in China often set npmmirror in their global .npmrc. My machine-2 branch added date-fns that way, and that entry's resolved points at registry.npmmirror.com. On another machine with no mirror configured and an empty cache, npm ci downloaded 205 packages from registry.npmjs.org and 1 from cdn.npmmirror.com. One machine's personal config ends up in every machine's install path. On a CI outside China that's just a little slower; on the day the mirror's sync breaks, or on a network that only allows the official registry, it becomes a very hard failure to track down.

npm has an omit-lockfile-registry-resolved option that leaves download URLs out of the lock. I tried it: the first run produces a 260-line diff (every resolved removed), and after that it's clean. It only works if all seven machines switch on the same day; otherwise the lock flips between "with URLs" and "without". I went with something simpler: the guard only allows the official registry host.

What to do: one script, one guard, two lines of config

1. scripts/relock.sh: the only thing agents may use on a lock conflict. It does four things: checks that package.json is valid JSON; replaces the lock with the one on the target branch (default origin/main); copies package.json, the lock and the project .npmrc into a temp dir and runs npm install --package-lock-only --ignore-scripts there (in a temp dir it can't even see the local node_modules, so older npm can't trim platform packages from it); then runs the guard and git adds. I tested it pair by pair on all 20 conflicts: 20/20 pass the guard, and after deleting node_modules, npm ci and the tests all pass.

2. scripts/lockguard.py: CI proof that every lock change has a cause. It compares package.json and lock between the base and the current tree, finds entries whose version changed, were added or removed, then walks the dependency graph starting from the direct dependencies whose spec changed in package.json. What it can reach is explained; anything else fails. Four more things fail outright: a resolved host outside the allowlist; a changed lockfileVersion; a package's declared optionalDependencies missing from the lock (the signature of #4828); package.json and the lock's root entry disagreeing.

In the lab: all 46 clean merges pass; every bad result among the seven methods is stopped, including the three that were green on npm ci and tests; machine 2's branch with the mirror URL is stopped too. The first version had a false positive: nanoid was hoisted to the top level in one branch and stayed under postcss/node_modules in the other, same version, just moved. I added a rule that "the same name@version exists on the other side" counts as a move, and the false positive went away.

The CI config is a few lines. The important parts are fetch-depth: 0 and using the merge-base as the baseline rather than the tip of main; otherwise a dependency someone else just added on main gets charged to you:

on:
  pull_request:
    paths: ["package.json", "package-lock.json", ".npmrc"]
permissions:
  contents: read
jobs:
  lockguard:
    if: ${{ !contains(github.event.pull_request.labels.*.name, 'deps-upgrade') }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: python3 scripts/lockguard.py --git "$(git merge-base origin/${{ github.base_ref }} HEAD)" .

3. Pin the npm version. Put "engines": { "npm": ">=11.3.0" } in package.json and engine-strict=true in the project .npmrc. I tested it: npm 9 and npm 10 both refuse to install. The newer devEngines field is honoured by npm 10 but ignored by npm 9, so while your seven machines run mixed npm versions, use engines. On CI, note that Node 22 ships npm 10: either use Node 24 or run npm i -g npm@11 first.

4. The rules that go into AGENTS.md:

- package-lock.json is generated: never delete it, never hand-edit it, never resolve
  a conflict in it with ours/theirs/union.
- Lock conflict: resolve package.json by hand (keep both sides' new deps), then run
  only scripts/relock.sh origin/main. If it fails, stop and put the error in the PR;
  do not improvise.
- Even if an error message tells you to delete node_modules and package-lock.json,
  never delete both. Relock first, then rm -rf node_modules && npm ci.
- No npm update, npm audit fix, or version bumps of existing deps in feature PRs.
- Dependency changes go in their own commit with only package.json and package-lock.json.

5. Upgrades belong to machine 7, in their own PR. Dependencies do need upgrading. Our arrangement: every Monday machine 7 opens a PR labelled deps-upgrade, the guard lets that label through, and the review machines look only at that PR's change notes and test results. The upgrades still happen, just where everyone can see them.

The case against

"Deleting and starting over keeps dependencies fresh and brings in security fixes; you're pinning old versions." This is the strongest objection. My base lock hadn't moved in over a year, and one delete-and-reinstall took axios from 1.11 to 1.21, quite possibly including security fixes. The trouble is the timing: it happens inside a PR about resolving a conflict, with an unrelated title, no careful review, and a regression that will be hard to bisect back to it. Upgrades need to happen regularly, which is what point 5 is for. Issues from npm audit can get their own PR too; the guard only asks for a label saying it's intentional.

"Switch to pnpm or yarn and none of this happens." Partly true. pnpm's docs say pnpm install resolves lockfile conflicts automatically. I didn't test that, so I won't draw a conclusion. For a team already on npm with seven machines set up, switching package managers costs more than adding two scripts; and after switching, "delete the lock and reinstall upgrades everything" still exists, so the guard idea still applies with a different parser.

"Libraries shouldn't commit lockfiles." For libraries published to npm, whether to commit a lock has long been debated, and without one there's no lock conflict. This post is about applications, where the tree in the lock is what you deploy.

When it doesn't fit: in a monorepo with workspaces, relock.sh has to copy every workspace's package.json into the temp dir, which this version doesn't do; the guard only understands npm lockfileVersion 2/3; a private registry needs --allow-host; and if you really do want to upgrade in this PR, add the deps-upgrade label and let it go through upgrade-PR review.

What I got wrong

• I first thought the main problem was lockfile format flipping between npm versions, and designed my first round of experiments around it. npm 9/10/11 showed no format churn. The real problems were all in how a conflict gets resolved.
• The first version of the guard flagged nanoid's move on clean merges. Had it gone straight into CI, everyone would have switched it off on day one.
• I assumed "leave the markers and let npm fix it" was the officially recommended method and could go straight into AGENTS.md. After measuring 10/20 silently dropped locks, I took it out of the recommendations.

Take these with you

1. The only way to resolve a lock conflict: resolve package.json by hand, start from the target branch's lock, and run npm install --package-lock-only in a temp dir.
2. CI can't stop at npm ci and tests. The three bad methods I measured were all green there; add a check that every lock change traces back to package.json.
3. Whatever the error message says, never delete node_modules and the lock together. That re-picks every dependency in the project as of today.
4. Use engines plus engine-strict to pin npm at 11.3 or later; devEngines doesn't stop npm 9.
5. Let the guard allow only the official registry host. Keep personal mirrors in personal global config, out of the lock.
6. Upgrades get their own PR, owned by one fixed machine.

Scripts, the AGENTS.md snippet and the CI config are here: lockfile-relock-kit.tar.gz. Copy scripts/ and .github/ into your repo, add engines to package.json, and first run python3 scripts/lockguard.py --git origin/main . locally to see whether your current branch passes.