意味のあるバージョン付け package.json に記載された数字の意味とは何か

すべての JavaScript プロジェクトには package.jsonが存在します npm install some-library 多くの開発者が数百回も入力していますが、バージョン文字列について二度考えたことはありません。しかし、誰かに「実際に許容されるもの」—つまり、npm が無問題に取り込むバージョン—を尋ねると、多くの場合、無言の答えを返します。 ^1.2.3 これは単なるギャップではありません。誤解されたバージョン範囲が、新しいマシンで動作していたCIパイプラインを突然壊す原因になります。その数字の背後にある契約を理解することは、デバッグに数分で解決できる開発者と、数時間かけて解決する開発者を分ける、効率の高い低負荷の投資です。

MAJOR.MINOR.PATCH 契約 npm install 意味的バージョン（semver）は3つの数字のフォーマットです：

各位置は、変更に関する特定の約束を持っています：

— ブレイクチェンジ。大きなバージョンにアップグレードする場合、コードを更新する必要があるかもしれません。 MAJOR.MINOR.PATCH— 新しい機能、バックワード互換。既存のコードは正常に動作する必要があります。

• MAJOR — バグ修正のみ。アップグレードは安全で、API は変更されません。
• MINOR これが
• PATCH 契約

パッケージが公開する際に適用されます。大きなバージョンから に移行する場合、新しい機能を追加するだけで既存の動作を破壊しない必要があります。大きなバージョンに移行する場合、それは警告のサインです：アップグレード前に変更ログを確認してください。 実際には、メンテナーがマイナーなリリース中に破壊的な変更を誤って導入することがあります。semver は自発的に強制されません — それは慣例です。しかし、リスクを評価するためのフレームワークを提供し、すべての範囲演算子がその上に構築されています。 2.3.1 に 2.4.0 破壊的変更とは何か？ 3.0.0 消費者がコードを更新しなければならないようなすべての変更が破壊的変更です：

エクスポートされた関数、クラス、または定数の削除または名前変更

関数の署名の変更 — パラメータの削除、必須パラメータの追加、または返り値タイプの変更

呼び出しコードが正しく動作するように設計されていたが、その結果、現在の呼び出しコードが誤った動作を示すように変更された観測可能な振る舞いの変更

• 設定ファイルフォーマットを不互換な方法で変更
• 新しいオプションパラメータを追加？それはマイナーです。新しいエクスポートを追加？それはマイナーです。誰かが誤って機能として利用していたバグを修正？それは判断が必要ですが、慣例的にパッチです。迷った場合は、マイナーを上げて明確にドキュメント化してください。
• package.json におけるバージョン範囲演算子
• 任意の

を開くと、バージョン文字列のような

が見られます。これらは正確なピンではなく、

範囲 package.json であり、npm または yarn が依存関係ツリーを解決する際に許容されるバージョンを示します。 "^4.17.21" または "~1.0.4"キャレット ^ — 非常に適合するバージョン キャレットは、 を実行するときにデフォルトの演算子です。これは「左側の非ゼロ桁を変更しないバージョンを許容する」と意味します。実際には、安定パッケージの場合、同じマジョア、任意のマイナーまたはパッチが適用されます：

ゼロマジョアの振る舞いは意図されています。マジョアが

であるパッケージは「不安定API」としてマークされ、任意のマイナーが破壊的になる可能性があります。キャレットはそのシグナルを尊重し、より慎重になります。 npm installティルダ ~ — パッチレベルの更新のみ

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

ティルダはより慎重です。新しいパッチを許容しますが、マイナーのバージョンには触れません： 0.x.x 必要に応じて

を使用してください。バージョンの変更がsemverに従ってない場合、またはコードが特定のAPI表面に密接に結合されており、新しい機能リリースが微妙な振る舞い変更を伴う場合に、この選択肢が適しています。

比較演算子：>=,

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

任意の範囲を比較演算子を使って記述できます。2つの制約の間にスペースがある場合、AND が意味されます： ~ これらは特に

でよく見られます。あるライブラリが、たとえば <=, >

と宣言して、そのライブラリがどのホストバージョンと互換性を持つかを示します。

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

ワイルドカード：* と x peerDependenciesワイルドカード形式は主にドキュメントの読みやすさのために使われます。npm はそれらをキャレット/ティルダとゼロベースに等価と見なします： "react": ">=16.8.0 <19.0.0" — 任意のバージョン。これは生産環境で使用しないでください。

— 任意の 1.x.x（これは

と同じです

• * または "" — 任意の 1.2.x（これは
• 1.x または 1.x.x と同じです ^1.0.0)
• 1.2.x プレリリースバージョン ~1.2.0)

プレリリースバージョンは

のように見えます。それらは 1.0.0-alpha.1, 2.0.0-beta.3、 または 3.1.0-rc.1同じ数字を持つリリースよりも 低い と見なされます — 1.0.0-alpha.1 < 1.0.0.

特に、 範囲演算子はプレリリースを自動的に含めません。範囲 ^1.0.0 は、 1.1.0-beta.1を含めません、技術的には >=1.0.0 <2.0.0を満たしています。明示的に選択する必要があります：

npm install some-library@next
npm install some-library@2.0.0-beta.3

これは意図された安全性です。CI が依存関係のプレリリースを無意識に取り込むことはほとんどありません。プレリリースをテストする場合は、意図的に行うべきです。 -alpha ロックファイルはオプションではありません

npm があなたの

範囲を解決する際、その時点での最高互換バージョンを選択します ^1.2.3 今日と、あなたが を取得します。6ヶ月後に実行すると、あなたが。実行 npm install を取得する可能性があります。同じ 1.5.0、異なる依存関係ツリー、潜在的に異なる振る舞い。 1.9.2これがロックファイルが解決するものです。 package.json(npm) および

(yarn) は、すべての依存関係 — 関直および間接的なもの — に正確なバージョンを記録します。誰かがあなたのリポジトリをクローンし、 package-lock.json を実行すると、同じツリーが得られます。 yarn.lock ロックファイルをコミットしてください。常に。 npm ciロックファイルをコミットしないと：

異なる開発者は、依存関係のバージョンを異なるものとして実行することになります CI環境はローカル環境と無意識にずれてしまう

• 間接的な依存関係のアップデートが、コードの変更が見えないまま、プロダクション環境の振る舞いを変更する可能性があります
• 主な例外：公開されたライブラリ（アプリケーションではない）は、消費者が自ら依存関係ツリーを解決できるようにロックファイルをコミットしない慣例があります。アプリケーションを開発している場合は、ロックファイルをソースコントロールから除外する理由はありません。
• package.json における「latest」は常に間違いです git diff

まれに、この記述が見られます。

これは行わないでください。

は現在タグ付けされたバージョンにマップされます — マイナーがリリースを公開するたびに変化します。新しいマシンで package.json:

"dependencies": {
  "some-package": "latest"
}

を実行すると、テストしたバージョンとはまったく異なるマジョアバージョンを取得する可能性があります。 "latest" それは数週間間違ったまま、新しいマジョアリリースが公開されたときに突然破壊されます。さらに、これは latest を再現可能な仕様として無効にします — バージョンを確認するためにはnpmを手動でチェックする必要があります。実際のバージョンにピンを設定し、キャレットがその範囲内で安全なアップグレードを処理できるようにします。 npm install バージョンが範囲を満たしているかを確認する

バージョンが範囲を満たしているかわからない場合 — 特にゼロマジョアパッケージや不尋常な複合表現の場合 — iotools.cloud で package.json を使用すると、すぐに答えが得られます。範囲（

）と候補バージョンを入力し、制約が満たされているかどうかを確認できます。

これは、依存関係アップグレードのPRをレビューするとき、なぜ SemVer バージョン計算機および範囲テストツール が予期しないバージョンに解決されたかを調査するとき、またはライブラリを公開する前に範囲を確認するときに役立ちます。^1.2.3, ~0.5.0, >=2.0.0 <3.0.0演算子

解決される npm install 1.2.0 以上、上限なし peerDependencies 任意のバージョン（避ける）

速携帯用参考

任意の 1.2.x パッチ	例	正確
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	正確に 1.2.3
*	*	意味的バージョン：package.json に記載された数字の意味とは何か 2
x	1.2.x	意味的バージョン：package.json に記載された数字の意味とは何か 1
すべての package.json にはバージョン文字列がありますが、多くの開発者はキャレットを信頼して、それが許容する内容を知らずにいます。このガイドでは、MAJOR.MINOR.PATCH 契約と、^、~、>=、* が実際に許容するアップグレードについて説明します。	1.2.3	正確に 1.2.3

あなたも好きかもしれません