npm ci nie działa na CI: package-lock niezgodny z package.json
CRM dla firm · Kacper Bernecki
Polecenie npm ci jest celowo bardziej rygorystyczne niż npm install. W pipeline produkcyjnym wymaga spójnego package.json i package-lock.json i nie naprawia ich w locie. Dlatego projekt może działać lokalnie, lecz nie budować się w CI.
Jak rozpoznać przyczynę
Otwórz pierwszy błąd npm ci w logach CI i zapisz jego dokładną treść. Rozróżnij brak pakietu w lockfile od konfliktu peerDependencies oraz od błędu wersji Node lub npm.
Porównaj package.json i package-lock.json w commicie wybranym do budowy. Pamiętaj, że lokalne node_modules może zawierać pozostałości pakietów, których nie ma w plikach zależności.
Rozwiązanie krok po kroku
1. Zacznij od upewnienia się, że pracujesz na właściwej gałęzi i nie masz niezapisanych zmian. Sprawdź git status oraz różnice w package.json i package-lock.json.
2. Uruchom npm install w kontrolowanym środowisku z kompatybilną wersją Node i npm, aby odtworzyć poprawny plik package-lock.json. Nie usuwa on automatycznie przyczyny konfliktu niezgodnych wersji.
3. Uruchom czystą instalację npm ci, najlepiej w osobnym katalogu roboczym lub po bezpiecznym usunięciu lokalnych zależności. Nie wykonuj destrukcyjnego czyszczenia w katalogu z niezapisanym kodem.
4. Jeśli problem dotyczy peer dependencies, zidentyfikuj konkretne pakiety i dopasuj ich wersje. Flaga legacy-peer-deps może maskować konflikt i powinna być świadomą, spójną decyzją, a nie pierwszą reakcją.
5. Zapisz i wypchnij zgodny lockfile razem z package.json, następnie ponów CI. Sprawdź, czy pipeline używa tej samej głównej wersji Node co środowisko lokalne.
Jak sprawdzić, czy problem zniknął
Przebieg npm ci powinien zakończyć się bez błędu, a po nim powinny przejść typecheck, testy i produkcyjny build. Sama poprawna instalacja nie gwarantuje poprawności aplikacji.
Na nowej gałęzi albo czystym klonie uruchom tę samą sekwencję komend co CI, aby upewnić się, że wynik nie zależy od przypadkowej zawartości node_modules.
Czego nie robić
Nie dopisuj node_modules do repozytorium i nie usuwaj package-lock.json tylko po to, by wyłączyć konflikt. Stracisz odtwarzalność instalacji.