Tidak suka iklan? Pergi Bebas Iklan Hari ini 

Pemrograman Semantik Sistem Penomoran yang Digunakan oleh npm install Anda

Diperbarui pada 4 Juni 2026

Tiga angka dari Semver adalah sebuah kontrak. MAJOR mengganti, MINOR menambahkan, dan PATCH memperbaiki — dan ketika build Anda gagal setelah npm install, sembilan dari sepuluh kasus itu disebabkan oleh seseorang yang mengabaikan kontrak tersebut. Berikut cara sistem penomoran bekerja, apa yang sebenarnya dilakukan oleh ^ dan ~ dalam package.json, serta mengapa menyimpan file lock adalah hal yang tak bisa diperdebatkan.

Pemrograman Semantik: Sistem Penomoran yang Digunakan oleh npm install Anda 1

IKLAN · HAPUS?

Build Anda gagal. Beberapa hari lalu masih berjalan dengan baik. npm install Pada hari Senin, terjadi pembaruan react-query@5 dan sekarang setengah dari hook Anda hilang. Anda menghadapi tumpukan error yang sebelumnya tidak ada, dan di suatu tempat, daftar perubahan kini mengumpul debu.

Ini adalah cerita tentang semver. Secara khusus, ini kesalahan Anda.

Apa arti tiga angka tersebut secara aktual

MAJOR.MINOR.PATCH — itu saja. Tiga slot, tiga aturan:

TAMBAL (1.2.3 → 1.2.4): Perbaikan bug. Tidak ada perubahan pada kode Anda. Anda hanya mendapatkan perilaku yang lebih stabil.
MINOR (1.2.3 → 1.3.0): Fitur baru ditambahkan, kompatibel ke belakang. Anda tidak perlu menggunakannya, tetapi fitur tersebut tersedia.
MAJOR (1.2.3 → 2.0.0): Sesuatu yang rusak. Sebuah fungsi diubah nama, dihapus, atau mengubah tanda. API lama hilang atau berfungsi secara berbeda.

Kata kunci dalam ketiga kasus tersebut adalah kompatibel ke belakang. MINOR dan PATCH adalah janji: “kami tidak merusak apa pun yang sudah Anda gunakan.” MAJOR adalah peringatan: “kami melakukannya.”

Ketika pemeliharaan meningkatkan MAJOR dan Anda tidak menyadari karena Anda membatasi ^1.0.0 dalam package.json dan file lockfile sudah usang — itu adalah kesalahan Anda. Spesifikasi bekerja persis seperti yang dirancang.

Kontrak sosial semver

Semver adalah konvensi, bukan hukum. Paket dapat mengklaim mengikuti semver dan kemudian merilis versi MINOR dengan perubahan yang merusak. Ketika hal ini terjadi, itu adalah ketidakjujuran dari pemelihara. Namun ketika paket secara benar meningkatkan MAJOR untuk menandai perubahan, dan Anda mengambilnya secara langsung — Anda sendiri yang merusak build Anda.

Itu sebabnya ada daftar perubahan. Sebuah CHANGELOG.md entri yang menyatakan “Dihapus fitur yang sudah tidak lagi digunakan v1Api — gunakan v2Api sebagai pengganti” adalah pemelihara yang memenuhi kewajibannya. Tidak membaca itu adalah Anda yang mengabaikannya. Daftar perubahan adalah bacaan selama dua menit. Sesi perbaikan yang dihindari olehnya tidak bisa dibayangkan.

^ vs ~ — mekanisme aktual

Dalam package.json, ^ (caret) dan ~ (tilde) menentukan rentang versi. Mereka terlihat mirip namun berperilaku sangat berbeda.

Caret (^): Memungkinkan apa pun yang tidak meningkatkan MAJOR. Ini adalah default npm saat Anda menjalankan npm install some-package.

^1.2.3 yang menyelesaikan >=1.2.3 <2.0.0
^0.2.3 yang menyelesaikan >=0.2.3 <0.3.0 — kasus khusus: 0.x menganggap MINOR sebagai perubahan yang merusak
^0.0.3 yang menyelesaikan >=0.0.3 <0.0.4 — 0.0.x mengunci secara tepat, tanpa ruang untuk berubah

Tilde (~): Memungkinkan pembaruan PATCH saja, dalam rentang MINOR yang ditentukan.

~1.2.3 yang menyelesaikan >=1.2.3 <1.3.0
~1.2 yang menyelesaikan >=1.2.0 <1.3.0 — sama seperti ~1.2.0
~1 yang menyelesaikan >=1.0.0 <2.0.0 — setara dengan ^1.0.0 pada titik ini

Contoh rentang versi

Jangkauan	Apa yang diizinkan	Pemetaan eksak
`1.2.3`	Tepat versi ini	Hanya 1.2.3
`^1.2.3`	Setiap MINOR/PATCH ≥ 1.2.3	1.2.4, 1.3.0, 1.99.0 — TIDAK 2.0.0
`^0.2.3`	PATCH hanya dalam 0.2.x	0.2.4, 0.2.99 — TIDAK 0.3.0
`~1.2.3`	PATCH hanya dalam 1.2.x	1.2.4, 1.2.99 — TIDAK 1.3.0
`~1.2`	Setiap patch dari 1.2.x	1.2.0, 1.2.1, 1.2.99
`>=1.2.3 <2.0.0`	Rentang eksplisit	Hasil yang sama seperti ^1.2.3
`1.2.x`	Setiap patch dari 1.2	1.2.0, 1.2.1, 1.2.99
`*`	Semua versi yang mungkin	Apa pun yang diinstal oleh npm hari ini

Itu * Rentang ini adalah strategi penomoran “percayalah pada saya bro”. Anda tidak membatasi versi apa pun. Jika sebuah library merilis API yang sepenuhnya diubah, Anda akan menerimanya pada instalasi berikutnya v9.0.0 dengan cache bersih. Gunakan hanya pada aplikasi tingkat atas yang tidak digunakan oleh paket lain — dan bahkan dalam kasus itu, hanya jika konsistensi benar-benar tidak penting bagi Anda (tidak). npm install dengan cache yang bersih. Gunakan hanya pada aplikasi tingkat atas yang tidak bergantung pada paket lain — dan bahkan dalam kasus itu, hanya jika keterulangan benar-benar tidak penting bagi Anda (hal ini benar).

Identifikasi versi pra-rilis

Sebelum rilis stabil, pengembang memberi label versi pra-rilis:

1.0.0-alpha.1 — awal, tidak stabil, API kemungkinan masih berubah
1.0.0-beta.2 — lengkap fitur, masih dalam pengujian, harapkan beberapa kekurangan
1.0.0-rc.1 — kandidat rilis, siap untuk produksi kecuali ada hal yang muncul dalam pengujian akhir

Versi pra-rilis diurutkan di bawah versi stabil: 1.0.0-alpha.1 < 1.0.0. Dan secara kritis, ^1.0.0 akan bukan menginstal 2.0.0-beta.1 — versi pra-rilis hanya cocok jika Anda secara eksplisit menentukan dalam rentang Anda. Ini adalah perilaku yang mencegah Anda secara tidak sengaja memilih versi alpha saat Anda seharusnya mengikuti rilis stabil.

Jika Anda mengonsumsi paket yang hanya memiliki versi pra-rilis, tetapkan string versi penuh: "some-package": "1.0.0-beta.2". Jangan gunakan ^ atau ~ dengan versi pra-rilis kecuali Anda tahu bahwa pemelihara mengelolanya dengan hati-hati — kebanyakan tidak.

Memeriksa rentang sebelum Anda mengonfirmasi

Sebelum membatasi rentang versi dalam package.json, penting untuk memastikan apa yang benar-benar Anda setujui untuk diinstal. Alat Kalkulator Versi Semver mengambil rentang versi dan daftar versi kandidat serta menunjukkan versi mana yang cocok — berguna ketika Anda tidak yakin apakah ~2.3 mencakup versi tertentu yang Anda butuhkan, atau ketika Anda meninjau PR dan rentang terlihat tidak sesuai.

Tiga mode kegagalan

Sebagian besar kegagalan build terkait semver mengikuti salah satu dari tiga pola:

^ + peningkatan MAJOR + file lockfile dihapus: Anda membatasi ^1.0.0, pemelihara merilis 2.0.0, file lockfile dihapus atau tidak pernah disimpan, CI menginstal 2.0.0. Solusi: simpan file lockfile Anda. Setiap proyek. Tidak ada pengecualian.
* dalam library yang Anda publikasikan: Anda adalah penulis library yang menggunakan * untuk ketergantungan. Setiap pengguna turunan dari paket Anda mewarisi wildcard Anda. Anda telah membuat grafik ketergantungan mereka menjadi masalah Anda. Solusi: gunakan rentang eksplisit dalam apa pun yang Anda publikasikan ke npm.
Pra-rilis tanpa file lockfile: Rentang yang longgar mengambil 1.0.0-alpha.3, API berubah dari alpha.1, tidak ada yang berfungsi. Solusi: batasi pra-rilis secara eksplisit dan — katakan ini bersama saya — simpan file lockfile.

Baca daftar perubahan

Ketika versi MAJOR dikeluarkan untuk apa pun dalam pohon ketergantungan Anda, habiskan dua menit untuk membaca daftar perubahan. Pemelihara menulisnya agar Anda tidak perlu menebak kegagalan dari tumpukan error pada pukul 3 pagi.

Jika sebuah library merilis perubahan yang merusak di bawah peningkatan MINOR tanpa daftar perubahan — itu adalah ketidakjujuran. Buka isu. Sampaikan secara publik. Namun jika peningkatan MAJOR jelas ada, panduan migrasi rinci, dan Anda mengambilnya tanpa memeriksa: alat telah melakukan persis apa yang Anda perintahkan. Kontrak ditulis dalam tiga angka. Anda hanya tidak membacanya.