Vad är en lockfile?

Vad en lockfile registrerar

Ditt manifest, till exempel package.json eller pyproject.toml, listar paketen du är beroende av och de versionsintervall du accepterar. Pakethanteraren omvandlar intervallen till exakta versioner för hela trädet, inklusive transitiva beroenden, och skriver resultatet till lockfilen. npm:s dokumentation säger att package-lock.json beskriver ”the exact tree that was generated, such that subsequent installs are able to generate identical trees”.

En enskild post i package-lock.json ser ut så här:

"node_modules/raw-body": {
  "version": "3.0.0",
  "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz",
  "integrity": "sha512-...",
  "dependencies": {
    "bytes": "3.1.2",
    "http-errors": "2.0.0",
    "iconv-lite": "0.6.3",
    "unpipe": "1.0.0"
  }
}

• version är den exakta version som valts.
• resolved är varifrån den hämtades: en tarball-URL i ett register, eller en git-URL med en commit.
• integrity är en Subresource Integrity-hash av tarballen, så att en manipulerad nedladdning misslyckas.
• dependencies är paketets egna beroenden, och det är så trädet, eller beroendegrafen, fogas samman.

Lockfiler per pakethanterare

Pakethanterare	Lockfile	Installera utan att ändra den
npm	package-lock.json	npm ci
Yarn (Berry)	yarn.lock	yarn install --immutable
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile
uv	uv.lock	uv sync --locked
Poetry	poetry.lock	poetry install
Cargo	Cargo.lock	cargo build --locked
Bundler	Gemfile.lock	bundle config set frozen true
Go modules	go.mod-versioner och go.sum-kontrollsummor	Byggkommandon uppdaterar inte go.mod som standard

Med enbart pip är den vanliga ersättningen en requirements.txt med exakta versioner. Den låser det den listar, men allt den utelämnar löses på nytt vid varje installation.

Använd frysta installationer i CI

En lockfile hjälper bara om bygget installerar från den. En vanlig npm install kan uppdatera package-lock.json när den inte längre stämmer med package.json, så att bygget i det tysta löser ett nytt träd. npm ci är byggt för automatiserade miljöer:

• Det kräver en package-lock.json eller npm-shrinkwrap.json.
• Om lockfilen och package.json inte stämmer överens avslutas det med ett fel i stället för att uppdatera låsningen.
• Det tar först bort befintliga node_modules.
• Det skriver aldrig till package.json eller lockfilen.

De andra kommandona i tabellen ovan gör samma jobb för sina pakethanterare.

Applikationer och bibliotek

Checka in lockfilen för applikationer och allt du driftsätter. För bibliotek låser den bara din egen utveckling och CI: npm publicerar aldrig package-lock.json och ignorerar den överallt utom i rotprojektet. De applikationer som installerar ditt bibliotek löser själva upp dess beroenden, inom dina versionsintervall. Det enda undantaget i npm är npm-shrinkwrap.json, som publiceras och har företräde, och som de flesta bibliotek inte bör använda.

Varför en lockfile inte är en registrering av vad som levererades

En lockfile är planen för en pakethanterare i ett projekt. Bygget som producerade din release gjorde mer än att följa den planen:

• Det kanske inte använde den. En installation som inte är fryst, en saknad lockfile eller en andra lockfile i ett monorepo gör att trädet löstes på ett annat sätt än i filen du tittar på.
• Cachar. Paket som återställs från en CI-cache installeras utan att hämtas, och en cache som återställs med en partiell nyckel kan vara äldre än den aktuella lockfilen. Se vad GitHub Actions-cachen döljer.
• Byggverktyg. Setup-actions, kompilatorer, linters och kodgeneratorer kommer via andra kanaler, med egna beroendeträd.
• Nedladdningar och installationsskript. En curl i ett byggsteg eller ett pakets installationsskript hämtar kod som ingen lockfile listar.
• Basavbilder. Ett containerbygge hämtar avbilder och operativsystemspaket som finns utanför alla språks lockfiler.

Integritetshasharna hjälper inte mot något av detta. De bevisar att paketen i lockfilen inte har manipulerats; de säger ingenting om vad bygget hämtade utanför den. SCA-verktyg som gör om en lockfile till en SBOM ärver samma blinda fläckar.

Registrera bygget, behåll lockfilen

Fortsätt att checka in lockfiler och installera från dem med frysta installationer. De gör byggen repeterbara. För registreringen av vad en release innehåller registrerar CRACI själva bygget: en paketmedveten proxy på dess GitHub Actions-runners registrerar varje paket som varje jobb hämtar, inklusive paket som återställs från CI-cachar, och varje jobbs SBOM anger sin egen fullständighet. Den registreringen ger en mer komplett bild av de beroenden som används än en skanning av lockfilen. Se SBOM:er från bygget, eller boka en demo för att jämföra de två på ett av dina egna byggen.

Lockfiler: vanliga frågor

Vad är en lockfile?

En lockfile är en fil som en pakethanterare skriver för att registrera den exakta versionen av varje beroende som den löste, direkta och transitiva, tillsammans med varifrån det kom och en kontrollsumma. Senare installationer läser den för att återskapa samma träd i stället för att lösa versionsintervall på nytt.

Bör jag checka in min lockfile?

Ja, för applikationer och allt du driftsätter. Utan en incheckad lockfile löser varje ny installation upp versionsintervall på nytt och kan få med nya transitiva versioner. Checka in den och installera från den med en fryst installation som npm ci i CI.

Låser en lockfile transitiva beroenden?

Ja. Det är dess huvudsakliga uppgift. Manifestet listar bara dina direkta beroenden och deras tillåtna intervall; lockfilen registrerar den exakta version som valts för varje paket i trädet.

Gäller lockfiler för bibliotek som jag publicerar?

Inte för dina användare. npm, till exempel, publicerar aldrig package-lock.json och ignorerar den överallt utom i rotprojektet. De applikationer som installerar ditt bibliotek löser själva upp dess beroenden, inom de intervall som din package.json tillåter.

Vad gör integrity-fältet i package-lock.json?

Det innehåller en Subresource Integrity-hash, oftast sha512, av paketets tarball. npm kontrollerar det nedladdade paketet mot den, så en manipulerad tarball för en låst version går inte att installera. Den skyddar paketen i lockfilen, inte något som bygget hämtar utanför den.

Är en lockfile samma sak som en SBOM?

Nej. En lockfile är indata: planen som en pakethanterare följer för ett projekt. En SBOM är en förteckning över en release. SCA-verktyg gör ofta om en lockfile till en SBOM, vilket fungerar när bygget installerade exakt lockfilen och inget annat.