依存関係のバージョン

セマンティックバージョニング

Yarn にあるパッケージは、 “semver” としても知られるセマンティックバージョニングの規則に従います。 レジストリから新しいパッケージをインストールした場合、そのパッケージは package.json ファイルに sember のバージョンの範囲で追加されます。

パッケージのバージョンは、major.minor.patch と3つのパートに分解され、たとえば 3.14.10.42.02.7.18 といった形式で表されます。 バージョンの各パートは、それぞれ次のような異なるタイミングでインクリメントされます。

  • major バージョンがインクリメントされるのは、パッケージの API に破壊的な変更を加えた時や、互換性のない変更を行った時です。
  • minor バージョンがインクリメントされるのは、後方互換性を維持したまま、新しい機能を追加した時です。
  • patch バージョンがインクリメントされるのは、後方互換性を維持したまま、バグを修正した時です。

注意: 時にリリース前やベータ版(例えば 2.0.0-beta.3)などをマークするために、 semver フォーマットへの「ラベル付け」または「拡張」が行われることもあります。

開発者がお互いに「互換性」がある2つの semver について話している場合は、後方互換性のある変更(minor および patch)を参照しています。

バージョンの範囲

依存関係を指定したい場合、そのパッケージ名と バージョン範囲 を下記のいずれかのように、 package.json で指定します:

{
  "dependencies": {
    "package-1": ">=2.0.0 <3.1.4",
    "package-2": "^0.4.2",
    "package-3": "~2.7.1"
  }
}

バージョンとは別の文字の集まりがあることに気づくでしょう。 これらの文字、 >=<^ そして ~演算子であり、バージョン範囲を指定するためのものです。

バージョン範囲の目的は、依存関係のどのバージョンがあなたのコードと動作するのかを指定することです。

比較演算子

バージョン範囲は各々比較演算子により構成されます。これらの比較演算子はバージョンが後に続く単なる演算子です。以下に基本的な演算子の一部を示します:

比較演算子 説明
<2.0.0 2.0.0 未満の任意のバージョン
<=3.1.4 3.1.4 以下の任意のバージョン
>0.4.2 0.4.2 を超える任意のバージョン
>=2.7.1 2.7.1 以上の任意のバージョン
=4.6.6 バージョン 4.6.6 のみ

注意: 演算子が指定されない場合、 = がバージョン範囲として推定されます。そのため、= は実際には省略可能です。

比較演算子の交差

比較演算子は、空白スペースと組み合わせて比較演算子のセットを作ることができます。 これを利用して、比較演算子の共通部分を作ることができます。 たとえば、比較演算子のセットとして >=2.0.0 <3.1.4 と書けば、2.0.0 以上かつ 3.1.4 未満のバージョン」という意味になります。

比較演算子の結合

バージョンの全範囲を指定するために、複数の比較演算子のセットを || で繋いで結合させることができます。 結合したものの片方の条件が満たされれば、バージョン範囲全体が満たされたことになります。 たとえば、バージョン範囲として <2.0.0 || >3.1.4 と書けば、*「 2.0.0 未満または 3.1.4 以上のバージョン」という意味になります。</p>

リリース前のタグ

バージョンには、プリリリースタグ (例: 3.1.4-beta.2) を加えることもできます。 比較演算子にプリリリースタグが含まれる場合、同じ major.minor.patch のバージョンを持つバージョンにだけマッチします。

たとえば、範囲に >=3.1.4-beta.2 と指定した場合、3.1.4-beta.23.1.4-beta.12 にはマッチしますが、 3.1.5-beta.1 には、たとえ数字の上ではバージョン 3.1.4-beta.2 と「以上」 (>=) であっても、マッチしません

プリリリースのバージョンには、意図せず破壊的な変更が含まれてしまうことがよくあります。そのため、通常は指定したバージョン以外のプリリリースのバージョンにはマッチさせたくないはずです。この動作は、そのような場合に役に立ちます。

高度なバージョンの範囲

ハイフンによる範囲の表現

ハイフンを使って範囲を表すと (例: 2.0.0 - 3.1.4)、両端を含む範囲を指定することができます。バージョンの一部が省略されている場合 (例: 0.42)、省略された部分は 0 で埋められます。

バージョン範囲 展開されたバージョンの範囲
2.0.0 - 3.1.4 >=2.0.0 <=3.1.4
0.4 - 2 >=0.4.0 <=2.0.0
Xによる範囲の表現

Xx または *を使用すると、バージョンの一部または全部を、明示的に指定するのを避けられます。

バージョン範囲 展開されたバージョンの範囲
* >=0.0.0 (任意のバージョン)
2.x >=2.0.0 <3.0.0 (メジャーバージョンが一致)
3.1.x >=3.1.0 <3.2.0 (メジャーおよびマイナーバージョンが一致)

バージョンの一部が省略されている場合、x 範囲であると推定されます。

バージョン範囲 展開されたバージョンの範囲
`` (empty string) * もしくは >=0.0.0
2 2.x.x もしくは >=2.0.0 <3.0.0
3.1 3.1.x もしくは >=3.1.0 <3.2.0
チルダによる範囲の表現

~ を用いてマイナーバージョンまでを指定すると、patch バージョンの変更を許容します。メジャーバージョンと ~ のみの表記は minor バージョンの変更を許容します。

バージョン範囲 展開されたバージョンの範囲
~3.1.4 >=3.1.4 <3.2.0
~3.1 3.1.x もしくは >=3.1.0 <3.2.0
~3 3.x or >=3.0.0 <4.0.0

注意: チルダとリリース前のバージョンによる表記は同じバージョンのリリース前のものにのみ一致します。 例えばバージョン範囲 ~3.1.4-beta.23.1.4-beta.4 に一致しますが、3.1.5-beta.2 には一致しません。これは major.minor.patch のバージョンが異なるためです。

キャレットによる範囲の表現

最初のゼロでない桁、3.1.43 もしくは 0.4.24 などが変わらない、バージョンの変更を許容します。

バージョン範囲 展開されたバージョンの範囲
^3.1.4 >=3.1.4 <4.0.0
^0.4.2 >=0.4.2 <0.5.0
^0.0.2 >=0.0.2 <0.0.3

注意: デフォルトでは yarn add [package-name] を実行した場合、キャレットによる範囲が使用されます。

バージョンの一部が省略された場合、足りない部分はゼロで埋められます。しかし、その値が変更になることも許容します。

バージョン範囲 展開されたバージョンの範囲
^0.0.x >=0.0.0 <0.1.0
^0.0 >=0.0.0 <0.1.0
^0.x >=0.0.0 <1.0.0
^0 >=0.0.0 <1.0.0

追加資料

  • このバージョン番号を管理するシステムの動作の完全な仕様については、node-semver の READMEを参照してください。
  • npm semver calculator を使用して実際のパッケージで、このバージョン番号の管理システムを試してください。