Hva er en lockfile?

Hva en lockfile registrerer

Manifestet ditt, for eksempel package.json eller pyproject.toml, lister opp pakkene du er avhengig av og versjonsområdene du godtar. Pakkebehandleren gjør disse områdene om til nøyaktige versjoner for hele treet, inkludert transitive avhengigheter, og skriver resultatet til lockfilen. Dokumentasjonen til npm beskriver package-lock.json som en beskrivelse av "the exact tree that was generated, such that subsequent installs are able to generate identical trees".

En enkelt oppføring i package-lock.json ser slik ut:

"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 er den nøyaktige versjonen som ble valgt.
• resolved er hvor den ble hentet fra: en tarball-URL i et register, eller en git-URL med en commit.
• integrity er en Subresource Integrity-hash av tarballen, så en manipulert nedlasting feiler.
• dependencies er pakkens egne avhengigheter, og det er slik treet, eller avhengighetsgrafen, settes sammen.

Lockfiler per pakkebehandler

Pakkebehandler	Lockfile	Installer uten å endre 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-versjoner og go.sum-sjekksummer	Byggekommandoer oppdaterer ikke go.mod som standard

Med pip alene er den vanlige erstatningen en requirements.txt med nøyaktige versjoner. Den fester det den lister opp, men alt den utelater, løses på nytt ved hver installasjon.

Bruk frosne installasjoner i CI

En lockfile hjelper bare hvis bygget installerer fra den. En vanlig npm install kan oppdatere package-lock.json når den ikke lenger stemmer med package.json, så bygget løser i det stille opp et nytt tre. npm ci er laget for automatiserte miljøer:

• Den krever en package-lock.json eller npm-shrinkwrap.json.
• Hvis lockfilen og package.json ikke stemmer overens, avslutter den med en feil i stedet for å oppdatere låsen.
• Den fjerner først en eventuell eksisterende node_modules.
• Den skriver aldri til package.json eller lockfilen.

De andre kommandoene i tabellen over gjør samme jobb for sine pakkebehandlere.

Applikasjoner og biblioteker

Commit lockfilen for applikasjoner og alt du ruller ut. For biblioteker låser den bare din egen utvikling og CI: npm publiserer aldri package-lock.json og ignorerer den overalt unntatt i rotprosjektet. Applikasjonene som installerer biblioteket ditt, løser avhengighetene selv, innenfor versjonsområdene dine. Det ene unntaket i npm er npm-shrinkwrap.json, som publiseres og har forrang, og som de fleste biblioteker ikke bør bruke.

Hvorfor en lockfile ikke viser hva som ble levert

En lockfile er planen for én pakkebehandler i ett prosjekt. Bygget som produserte utgivelsen din, gjorde mer enn å følge den planen:

• Det har kanskje ikke brukt den. En installasjon som ikke er frosset, en manglende lockfile eller en ekstra lockfile i et monorepo betyr at treet ble løst annerledes enn filen du ser på.
• Cacher. Pakker gjenopprettet fra en CI-cache installeres uten å bli hentet, og en cache gjenopprettet med en delvis nøkkel kan være eldre enn den gjeldende lockfilen. Se hva GitHub Actions-cachen skjuler.
• Byggeverktøy. Setup-actions, kompilatorer, lintere og kodegeneratorer kommer inn gjennom andre kanaler, med sine egne avhengighetstrær.
• Nedlastinger og installasjonsskript. En curl i et byggesteg eller installasjonsskriptet til en pakke henter kode ingen lockfile lister opp.
• Base-images. Et containerbygg henter images og operativsystempakker som ligger utenfor alle språkenes lockfiler.

Integritetshashene hjelper ikke med noe av dette. De beviser at pakkene i lockfilen ikke er manipulert; de sier ingenting om hva bygget hentet utenfor den. SCA-verktøy som gjør en lockfile om til en SBOM, arver de samme blindsonene.

Registrer bygget, behold lockfilen

Fortsett å committe lockfiler og installere fra dem med frosne installasjoner. De gjør bygg repeterbare. For oversikten over hva en utgivelse inneholder, registrerer CRACI selve bygget: en pakkebevisst proxy på GitHub Actions-runnerne registrerer hver pakke hver jobb henter, inkludert pakker gjenopprettet fra CI-cacher, og hver jobbs SBOM angir sin egen fullstendighet. Den registreringen gir et mer fullstendig bilde av avhengighetene som er i bruk, enn en skanning av lockfilen. Se SBOM-er fra bygget, eller book en demo for å sammenligne de to på et av dine egne bygg.

Lockfiler: ofte stilte spørsmål

Hva er en lockfile?

En lockfile er en fil en pakkebehandler skriver for å registrere den nøyaktige versjonen av hver avhengighet den løste, direkte og transitive, sammen med hvor den kom fra og en sjekksum. Senere installasjoner leser den for å gjenskape det samme treet i stedet for å løse versjonsområder på nytt.

Bør jeg committe lockfilen min?

Ja, for applikasjoner og alt du ruller ut. Uten en committet lockfile løser hver nye installasjon opp versjonsområder på nytt og kan plukke opp nye transitive versjoner. Commit den og installer fra den med en frosset installasjon som npm ci i CI.

Fester en lockfile transitive avhengigheter?

Ja. Det er hovedjobben dens. Manifestet lister bare opp de direkte avhengighetene dine og områdene de kan ligge i; lockfilen registrerer den nøyaktige versjonen som ble valgt for hver pakke i treet.

Gjelder lockfiler for biblioteker jeg publiserer?

Ikke for brukerne dine. npm, for eksempel, publiserer aldri package-lock.json og ignorerer den overalt unntatt i rotprosjektet. Applikasjonene som installerer biblioteket ditt, løser avhengighetene selv, innenfor områdene package.json-filen din tillater.

Hva gjør integrity-feltet i package-lock.json?

Det inneholder en Subresource Integrity-hash, vanligvis sha512, av pakkens tarball. npm sjekker den nedlastede pakken mot den, så en manipulert tarball for en låst versjon lar seg ikke installere. Den beskytter pakkene i lockfilen, ikke noe bygget henter utenfor den.

Er en lockfile det samme som en SBOM?

Nei. En lockfile er inndata: planen en pakkebehandler følger for ett prosjekt. En SBOM er en oversikt over en utgivelse. SCA-verktøy gjør ofte en lockfile om til en SBOM, og det fungerer når bygget installerte nøyaktig lockfilen og ingenting annet.