`package-lock.json` în Node.js

npm și pachete npm 5 (lockfileVersion 3 implicit: npm 9)

Fișierul în care npm notează versiunea exactă a fiecărui pachet instalat, ca toată lumea să primească același node_modules.

Sintaxă

package-lock.json   # generat de npm install, pus în Git

Ce face `package-lock.json`

package.json spune ce intervale accepți (^2.1.3), iar package-lock.json spune ce s-a instalat exact: versiunea fiecărui pachet, inclusiv a dependențelor indirecte, adresa de descărcare (resolved) și suma de control (integrity). Îl generează și îl actualizează npm install, npm update și npm uninstall; nu îl editezi de mână.

Fișierul se pune în Git. Așa colegii, serverul CI și serverul de producție instalează aceleași versiuni, chiar dacă între timp au apărut versiuni noi în interval. npm ci instalează strict după el.

Formatul actual este "lockfileVersion": 3 (implicit din npm 9): pachetele stau sub cheia "packages", cu calea din node_modules drept cheie. La un conflict de merge în acest fișier, rezolvă conflictul din package.json și rulează npm install: npm reface lock-ul.

Exemple

Exemplul 1: Începutul unui package-lock.json

Cheia "" este proiectul tău, cu intervalele din package.json. Urmează fiecare pachet instalat, cu versiunea lui exactă.

head -24 package-lock.json

Ieșire în terminal

{
  "name": "magazin",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "magazin",
      "version": "1.0.0",
      "license": "ISC",
      "dependencies": {
        "dayjs": "1.11.10",
        "ms": "^2.1.3"
      },
      "devDependencies": {
        "prettier": "^3.3.0"
      }
    },
    "node_modules/dayjs": {
      "version": "1.11.10",
      "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.10.tgz",
      "integrity": "sha512-vjAczensTgRcqDERK0SR2XMwsF/tSvnvlv6VcF2GIhg6Sx4yOIt/irsr1RDJsKiIyBzJDpCoXiWWq28MqH2cnQ==",
      "license": "MIT"
    },

Exemplul 2: Citești lock-ul cu Node.js

Lock-ul este JSON obișnuit. Exemplul scrie un lock mic și listează pachetele cu versiunea exactă; într-un proiect real îl citești direct cu readFile.

import { readFile, writeFile } from "node:fs/promises";

await writeFile("package-lock.json", JSON.stringify({
  name: "magazin",
  lockfileVersion: 3,
  packages: {
    "": { dependencies: { ms: "^2.1.3" }, devDependencies: { prettier: "^3.3.0" } },
    "node_modules/ms": { version: "2.1.3" },
    "node_modules/prettier": { version: "3.9.10", dev: true },
  },
}, null, 2));

const lock = JSON.parse(await readFile("package-lock.json", "utf8"));
console.log("lockfileVersion:", lock.lockfileVersion);
for (const [cale, info] of Object.entries(lock.packages)) {
  if (cale === "") continue;
  const nume = cale.replace("node_modules/", "");
  console.log(`${nume}@${info.version}${info.dev ? " (dev)" : ""}`);
}

Rezultat

lockfileVersion: 3
ms@2.1.3
prettier@3.9.10 (dev)

Greșeli frecvente

Pui package-lock.json în .gitignore: fiecare instalare poate aduce alte versiuni, iar npm ci nu mai funcționează.
Ștergi lock-ul ca să „repari” ceva: toate pachetele sar la cele mai noi versiuni din interval, deodată. Actualizează țintit cu npm update pachet.
Amesteci managerii de pachete: pnpm-lock.yaml sau yarn.lock lângă package-lock.json duc la instalări diferite. Păstrează un singur lock.

Comenzi înrudite

npm ci: Instalare curată și exactă după package-lock.json, pentru servere de build, CI și producție.
npm install: Instalează pachete din registrul npm în node_modules și le trece în package.json și package-lock.json.
Versiuni semver (^, ~, >=): Cum citește npm versiunile MAJOR.MINOR.PATCH și intervalele ^, ~, >=, x din package.json.
package.json: Fișierul de configurare al unui proiect Node.js: nume, versiune, tipul modulelor, scripturi, dependențe și versiunea Node cerută.
pnpm și yarn (comparație cu npm): Comenzile npm și echivalentele lor în pnpm și Yarn, plus ce trebuie să știi despre Corepack în Node.js 25+.

Ce face package-lock.json