Mikä on lukitustiedosto (lockfile)?

Mitä lukitustiedosto tallentaa

Manifestisi, kuten package.json tai pyproject.toml, luettelee paketit, joista olet riippuvainen, ja hyväksymäsi versiovälit. Paketinhallinta muuttaa välit tarkoiksi versioiksi koko puulle, transitiiviset riippuvuudet mukaan lukien, ja kirjoittaa tuloksen lukitustiedostoon. npm:n dokumentaation mukaan package-lock.json kuvaa "the exact tree that was generated, such that subsequent installs are able to generate identical trees".

Yksittäinen merkintä package-lock.json-tiedostossa näyttää tältä:

"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 on valittu tarkka versio.
• resolved kertoo, mistä paketti haettiin: rekisterin tarball-URL tai git-URL ja commit.
• integrity on tarballin Subresource Integrity -tiiviste, joten peukaloitu lataus epäonnistuu.
• dependencies ovat paketin omat riippuvuudet, ja niiden avulla puu eli riippuvuusgraafi kootaan yhteen.

Lukitustiedostot paketinhallinnoittain

Paketinhallinta	Lukitustiedosto	Asennus muuttamatta sitä
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-versiot ja go.sum-tarkistussummat	Build-komennot eivät oletuksena päivitä go.mod-tiedostoa

Pelkällä pipillä yleinen korvike on requirements.txt, jossa on tarkat versiot. Se lukitsee luettelemansa paketit, mutta kaikki, mitä siitä puuttuu, ratkaistaan uudelleen jokaisessa asennuksessa.

Käytä CI:ssä lukittuja asennuksia

Lukitustiedostosta on hyötyä vain, jos buildi asentaa siitä. Tavallinen npm install voi päivittää package-lock.json-tiedoston, kun se ei enää vastaa package.json-tiedostoa, jolloin buildi ratkaisee hiljaa uuden puun. npm ci on tehty automatisoituihin ympäristöihin:

• Se vaatii package-lock.json- tai npm-shrinkwrap.json-tiedoston.
• Jos lukitustiedosto ja package.json eivät täsmää, se päättyy virheeseen eikä päivitä lukitusta.
• Se poistaa ensin mahdollisen olemassa olevan node_modules-hakemiston.
• Se ei koskaan kirjoita package.json-tiedostoon eikä lukitustiedostoon.

Yllä olevan taulukon muut komennot tekevät saman omalle paketinhallinnalleen.

Sovellukset ja kirjastot

Commitoi lukitustiedosto sovelluksille ja kaikelle, mitä otat käyttöön. Kirjastoissa se lukitsee vain oman kehityksesi ja CI:si: npm ei koskaan julkaise package-lock.json-tiedostoa ja ohittaa sen kaikkialla paitsi juuriprojektissa. Kirjastoasi asentavat sovellukset ratkaisevat sen riippuvuudet itse versiovälien puitteissa. npm:n ainoa poikkeus on npm-shrinkwrap.json, joka julkaistaan ja menee etusijalle, eikä useimpien kirjastojen pitäisi käyttää sitä.

Miksi lukitustiedosto ei ole tallenne siitä, mitä toimitettiin

Lukitustiedosto on yhden paketinhallinnan suunnitelma yhdessä projektissa. Julkaisusi tuottanut buildi teki muutakin kuin noudatti tätä suunnitelmaa:

• Se ei ehkä käyttänyt sitä. Lukitsematon asennus, puuttuva lukitustiedosto tai monorepon toinen lukitustiedosto tarkoittaa, että puu ratkaistiin eri tavalla kuin katsomassasi tiedostossa.
• Välimuistit. CI-välimuistista palautetut paketit asennetaan hakematta niitä, ja osittaisella avaimella palautettu välimuisti voi olla nykyistä lukitustiedostoa vanhempi. Katso mitä GitHub Actionsin välimuisti piilottaa.
• Build-työkalut. Setup-actionit, kääntäjät, linterit ja koodigeneraattorit tulevat muita reittejä omine riippuvuuspuineen.
• Lataukset ja asennusskriptit. Build-vaiheen curl tai paketin asennusskripti hakee koodia, jota mikään lukitustiedosto ei luettele: piilotettu riippuvuus.
• Peruskuvat. Konttibuildi hakee levykuvia ja käyttöjärjestelmän paketteja, jotka ovat kaikkien kielikohtaisten lukitustiedostojen ulkopuolella.

Integrity-tiivisteet eivät auta tässä. Ne todistavat, ettei lukitustiedoston paketteja ole peukaloitu, mutta eivät kerro mitään siitä, mitä buildi haki sen ulkopuolelta. SCA-työkalut, jotka muuttavat lukitustiedoston SBOM:ksi, perivät samat katvealueet.

Tallenna buildi, pidä lukitustiedosto

Commitoi lukitustiedostot jatkossakin ja asenna niistä lukituilla asennuksilla. Ne tekevät buildeista toistettavia, vaikka eivät yksinään tee niistä uudelleentuotettavaa buildia. Julkaisun sisällön tallenteeksi CRACI tallentaa itse buildin: paketit tunnistava välityspalvelin sen GitHub Actions -runnereilla tallentaa jokaisen paketin, jonka kukin jobi hakee, myös CI-välimuisteista palautetut paketit, ja jokaisen jobin SBOM ilmoittaa oman kattavuutensa. Tallenne antaa kattavamman kuvan käytössä olevista riippuvuuksista kuin lukitustiedoston skannaus. Katso buildin aikana tallennetut SBOM:t tai varaa demo ja vertaa näitä kahta yhdessä omista buildeistasi.

Lukitustiedostot: usein kysytyt kysymykset

Mikä on lukitustiedosto?

Lukitustiedosto on paketinhallinnan kirjoittama tiedosto, joka tallentaa tarkan version jokaisesta sen ratkaisemasta riippuvuudesta, sekä suorista että transitiivisista, sekä paketin lähteen ja tarkistussumman. Myöhemmät asennukset lukevat sen tuottaakseen saman puun sen sijaan, että ratkaisisivat versiovälit uudelleen.

Pitäisikö lukitustiedosto commitoida?

Kyllä, sovellusten ja kaiken käyttöön otettavan osalta. Ilman commitoitua lukitustiedostoa jokainen uusi asennus ratkaisee versiovälit uudelleen ja voi poimia uusia transitiivisia versioita. Commitoi se ja asenna siitä CI:ssä lukitulla asennuksella, kuten npm ci.

Lukitseeko lukitustiedosto transitiiviset riippuvuudet?

Kyllä. Se on sen päätehtävä. Manifesti luettelee vain suorat riippuvuutesi ja niiden sallitut versiovälit; lukitustiedosto tallentaa tarkan valitun version jokaiselle puun paketille.

Koskevatko lukitustiedostot julkaisemiani kirjastoja?

Eivät käyttäjiesi kohdalla. Esimerkiksi npm ei koskaan julkaise package-lock.json-tiedostoa ja ohittaa sen kaikkialla paitsi juuriprojektissa. Kirjastoasi asentavat sovellukset ratkaisevat sen riippuvuudet itse package.json-tiedostosi sallimien versiovälien puitteissa.

Mitä package-lock.json-tiedoston integrity-kenttä tekee?

Siinä on paketin tarballin Subresource Integrity -tiiviste, yleensä sha512. npm tarkistaa ladatun paketin sitä vasten, joten lukitun version peukaloidun tarballin asennus epäonnistuu. Se suojaa lukitustiedoston paketteja, ei mitään, mitä buildi hakee sen ulkopuolelta.

Onko lukitustiedosto sama asia kuin SBOM?

Ei. Lukitustiedosto on syöte: suunnitelma, jota paketinhallinta noudattaa yhdessä projektissa. SBOM on julkaisun inventaario. SCA-työkalut muuttavat usein lukitustiedoston SBOM:ksi, mikä toimii, kun buildi asensi täsmälleen lukitustiedoston sisällön eikä mitään muuta.