package-lock.json

development beginner

依存パッケージの正確なバージョン、取得元、整合性情報を記録するnpmのロックファイル。

概要（サマリー）

package-lock.json（パッケージ・ロック・ジェイソン）は、Node.jsを用いた開発において、プロジェクトに必要な外部ライブラリ（パッケージ）の「正確なバージョン」や取得元、整合性情報を記録するためのnpmのロックファイルである。

npm を使って外部パッケージをインストールした際に、自動的に生成または更新される。これにより、別のPCやサーバーで同じコードを動かす際に、「バージョンがずれて動かない」というトラブルを減らす役割を持っている。

詳細解説

package-lock.jsonとは何か

JavaScriptやNode.jsの開発では、多数の便利な外部ライブラリをプロジェクトに組み込んで使用する。このライブラリ間の複雑な依存関係と、それぞれの正確なバージョンを1枚の地図のように詳細に記録したファイルが、package-lock.jsonである。

このファイルがあるおかげで、チームの誰がどの端末で開発環境を再構築しても、同じ依存関係の構成を再現しやすくなり、予期せぬ不具合を防ぎやすくなる。特にCIや本番ビルドでは、npm install よりも npm ci を使うことで、package-lock.jsonに記録された内容に基づく再現性の高いインストールができる。

package.jsonとの違い

初心者が最も混乱しやすいのが、package.json と package-lock.json の違いである。

package.json: プロジェクトの基本設定や、必要なパッケージの大まかなバージョン範囲（例: ^1.2.0 など）を指定する「指示書」。人間が手動で編集することがある。
package-lock.json: 実際にインストールされたすべてのパッケージの正確なバージョン（例: 1.2.5）や取得先URL、整合性チェック用のハッシュ値などを記録した「実行結果の証明書」。人間は直接編集せず、npmが自動管理する。

なぜこのファイルが必要なのか

仮に package.json だけしかない場合、パッケージのバージョン指定に ^（キャレット）が付いていると、別の人がインストールした際に、自動的にその範囲内で最新のマイナーバージョン（例: 1.2.9）が導入されることがある。

もしその最新バージョンに致命的なランタイムエラー（バグ）が含まれていた場合、「自分のPCでは動くのに、他のメンバーのPCや本番のWebサーバーでは動かない」という現象が起きてしまう。package-lock.jsonは、全員が同じ依存関係の構成を再現しやすくするために存在する。

Gitでの競合（コンフリクト）と対処法

チーム開発において、複数人が別々に新しいパッケージを追加してGitへ送信（プッシュ）すると、この package-lock.json でコンフリクト（競合）が発生することがよくある。

このファイルは人間が手で直すのが困難なほど巨大で複雑なため、競合が発生した場合は以下の手順で解決するのが安全である。

package.json の競合箇所を手動で修正して保存する。
ターミナルで npm install を再実行する。
npmが package.json に基づいて package-lock.json を自動で再計算・更新し、競合が解決する。

コード・ファイル例

以下は、package.json と package-lock.json の内部的な記述の違いを簡略化した比較例である。

package.json の表記（大まかな指定）

{
  "dependencies": {
    "my-library": "^1.2.0"
  }
}

この指定では、1.2.0 以上、2.0.0 未満の範囲で最新のパッケージが許可される。

package-lock.json の表記（完全に固定された状態）

{
  "packages": {
    "node_modules/my-library": {
      "version": "1.2.5",
      "resolved": "https://registry.npmjs.org/my-library/-/my-library-1.2.5.tgz",
      "integrity": "sha512-abc..."
    }
  }
}

このように、実際にインストールされた 1.2.5 という正確なバージョンと、その整合性を担保するハッシュ（integrity）が厳密に記録される。

AIコーディングとの関係

AIに「依存関係のエラーを解決してほしい」と依頼する際、AIに package.json だけでなく、パッケージの依存関係の競合状況を見せるために、package-lock.json のエラーメッセージや、関連するライブラリのバージョン情報を一緒に渡すと、より精度の高い解決策を提示してくれる。

例えば、npm install でエラーが出たときは、以下のようにAIに質問するとよい。

npm install を実行したところ、以下の依存関係エラーが発生しました。
package.json には "A": "^2.0.0" と書いてありますが、package-lock.json には古い "B" への依存関係が残っているようです。
この競合を解消して正しくインストールを完了するための手順を教えてください。

[エラーメッセージをここに貼り付ける]

AIは package-lock.json の構造を理解しているため、古い不要なパッケージのキャッシュを消すコマンドや、競合を強制解決する手順を詳しく教えてくれる。

よくある勘違い

package-lock.jsonは手動で書き換えてもいい？

原則として避けるべきである。このファイルには整合性チェック情報（ハッシュ値）や複雑な依存ツリーが記述されており、手動で書き換えると整合性が崩れ、インストール時にエラーが発生する原因になる。変更したい場合は、必ず npm install [パッケージ名] などのnpmコマンド経由で行う。

package-lock.jsonはGit管理に含めない方がいい？

「自動生成されるファイルだから .gitignore に入れてGitの管理から外すべきでは？」と思われがちだが、これは間違いである。チーム全員や本番環境で同一のライブラリ構成を再現することがこのファイルの目的であるため、必ずGitの管理下に置き、コミットして共有する必要がある。

yarnやpnpmを使っている場合はどうなる？

npm以外のパッケージマネージャーを使用している場合は、別のロックファイルが生成される。例えば yarn なら yarn.lock、pnpm なら pnpm-lock.yaml が生成され、目的は package-lock.json とよく似ている。ただし書式や解決アルゴリズムは異なるため、これらがプロジェクト内で混在しないよう統一することが望ましい。

まとめ

package-lock.jsonは、実際に解決されたパッケージの正確なバージョン、取得元、整合性情報を記録するファイルである。
大まかな指定を行う package.json とは異なり、開発メンバー間で全く同じ環境を保証するために存在する。
人間が直接編集することはせず、npm コマンドを通じて自動で生成・更新させる。
チームでの同一環境再現のため、必ずGitで管理し共有する。

情報ソース

npm Documentation: package-lock.json

より詳しくAIに聞いてみよう

package.json と package-lock.json の違いを、中学生にもわかるような身近な例え話で説明してください。
package-lock.json が原因で Git でコンフリクト（競合）が起きてしまいました。具体的な解決コマンドの流れを教えてください。
package-lock.json を Git にコミットするメリットと、もしコミットしなかった場合に発生する問題を詳しく教えてください。
node_modules フォルダを削除して npm install を再実行したとき、package-lock.json はどのように変化しますか？
yarn.lock や pnpm-lock.yaml が package-lock.json と同じディレクトリに混在しているのですが、どのように対処すればよいですか？