Node.js, Package, dan Ekosistemnya · 3/7

package.json, semver, dan lockfile

Kenapa `^1.2.3` bisa merusak build-mu jam 3 pagi, dan bagaimana lockfile mencegahnya.

Baca 25 menit

Setelah pelajaran ini kamu bisa

Menjelaskan setiap field di package.json yang umum
Membaca rentang semver dan menyebutkan tepat versi mana yang diizinkannya
Menjelaskan apa yang dicegah oleh lockfile
Menjelaskan dua aturan khusus caret untuk versi 0.x

package.json adalah kartu identitas sebuah proyek: namanya, apa yang dibutuhkannya, dan perintah apa yang disediakannya. Setiap proyek JavaScript punya satu.

json

{
  "name": "fullstack-learning-path",
  "version": "0.1.0",
  "private": true,              // refuse to publish this to npm by accident
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest run"
  },
  "dependencies": {
    "next": "16.3.0",           // exact: only this version
    "react": "19.2.8",
    "lucide-react": "^1.31.0"   // caret: this or any compatible later one
  },
  "devDependencies": {
    "typescript": "^5",
    "vitest": "^4.1.10"
  },
  "packageManager": "bun@1.3.14",   // which tool, and which version
  "trustedDependencies": ["sharp"]  // install scripts allowed to run
}

Ini versi ringkas dari file milik proyek ini sendiri. "private": true layak kamu tiru untuk apa pun yang tidak dimaksudkan untuk npm.

Semver

Semver — semantic versioning — adalah janji yang dibuat oleh nomor versi. MAJOR.MINOR.PATCH, dan setiap bagiannya punya arti tertentu.

Bagian	Dinaikkan saat	Haruskah ia merusakmu?
MAJOR — `2`.0.0	Ada yang sengaja dirusak	Ya, siapkan pekerjaan
MINOR — 1.`3`.0	Ada fitur ditambahkan, tidak ada yang dibuang	Tidak
PATCH — 1.2.`4`	Sebuah bug diperbaiki	Tidak

Awalan di depan sebuah versi memberitahu package manager seberapa besar kebebasannya.

Rentang	Mengizinkan	Artinya
`1.2.3`	tepat 1.2.3	Tanpa kebebasan. Reproduksibilitas maksimum.
`^1.2.3`	>= 1.2.3 dan < 2.0.0	Patch dan fitur, tanpa perubahan yang merusak
`~1.2.3`	>= 1.2.3 dan < 1.3.0	Hanya patch
`>=1.2.3`	apa pun yang lebih baru, selamanya	Berbahaya — mengizinkan versi major
`*` atau `latest`	apa pun	Jangan pernah lakukan ini

Coba sendiri

Pencocok caret dan tilde yang berfungsi. Membuatnya adalah cara tercepat memastikan kamu memahami aturannya dengan benar.

function parse(version) {
  return version.split(".").map(Number);
}

// Is `version` lower than `limit`?
function isBelow(version, limit) {
  for (let i = 0; i < 3; i++) {
    if (version[i] < limit[i]) return true;
    if (version[i] > limit[i]) return false;
  }
  return false;                     // equal is not below
}

function satisfies(version, range) {
  const prefix = range[0] === "^" || range[0] === "~" ? range[0] : "";
  const [major, minor, patch] = parse(prefix ? range.slice(1) : range);
  const v = parse(version);

if (!prefix) return version === range.slice(0);   // exact match

// Must be at least the stated version.
  if (isBelow(v, [major, minor, patch])) return false;

if (prefix === "~") return isBelow(v, [major, minor + 1, 0]);

// Caret: the upper bound depends on the leftmost NON-ZERO part.
  if (major > 0) return isBelow(v, [major + 1, 0, 0]);
  if (minor > 0) return isBelow(v, [0, minor + 1, 0]);
  return isBelow(v, [0, 0, patch + 1]);
}

const cases = [
  ["^1.2.3", "1.2.3"], ["^1.2.3", "1.9.9"], ["^1.2.3", "2.0.0"],
  ["^0.2.3", "0.2.9"], ["^0.2.3", "0.3.0"],
  ["^0.0.3", "0.0.3"], ["^0.0.3", "0.0.4"],
  ["~1.2.3", "1.2.9"], ["~1.2.3", "1.3.0"],
];
for (const [range, version] of cases) {
  console.log(range.padEnd(8), version.padEnd(7), satisfies(version, range));
}

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Lockfile

package.json menyebut ^1.2.3, dan itu sebuah rentang. Lockfile — bun.lock, package-lock.json, pnpm-lock.yaml — mencatat satu versi tepat yang benar-benar ter-install, untuk setiap package termasuk yang transitif.

Inilah yang mencegah "di komputer saya jalan". Tanpa lockfile, kamu meng-install 1.2.3 di bulan Maret dan rekanmu meng-install 1.9.0 di bulan Juni — keduanya memenuhi ^1.2.3, dan salah satunya punya regresi.

Commit lockfile-nya. Selalu. Ia adalah reproduksibilitas build-mu.
Jangan mengeditnya manual. Ubah package.json lalu jalankan install.
Wajar kalau muncul di diff. Diff lockfile yang besar di PR yang cuma menambah satu package itu normal.
Di CI, install tepat dari lockfile. npm ci melakukannya; padanan bun-nya bun install --frozen-lockfile, dan ia gagal alih-alih diam-diam memperbarui.

Tugas praktik

Di proyek ini, temukan lucide-react di package.json dan catat rentangnya. Lalu jalankan cat node_modules/lucide-react/package.json | grep '"version"' untuk melihat versi tepat yang ter-install. Dengan runner di atas, pastikan versi yang ter-install memenuhi rentang yang dideklarasikan. Terakhir, jalankan wc -l bun.lock untuk melihat seberapa detail isi lockfile-nya.

Hasil yang diharapkan

Versi yang ter-install memenuhi rentangnya, dan lockfile-nya ribuan baris.

Cek pemahaman

package.json-mu menyebut ^0.2.3. Apakah bun update akan meng-install 0.3.0?

Ya — caret mengizinkan versi apa pun di bawah 1.0.0Tidak — di bawah 1.0.0 caret hanya mengizinkan kenaikan patch, jadi 0.2.9 boleh tapi 0.3.0 tidakHanya kalau lockfile-nya dihapus lebih dulu

Pilih jawaban dulu