開発基礎 Study Note：パッケージマネージャーとロックファイル（壊れない開発環境の作り方）

GitHubからアプリのコードを取得したのに、そのままでは動かない。AIが「依存関係をインストールします」と言って、しばらくターミナルに文字が流れる。説明書には、npmやpnpmという見慣れない名前がある。

こうした場面で働いているのが、パッケージマネージャーです。アプリが必要とする部品を取りそろえ、その部品が必要とする別の部品や、バージョンの条件も扱います。

前回は、パッケージ・モジュール・依存関係を説明しました。今回は「必要な部品が分かった後、どうやって用意するか」を見ていきます。JavaScriptやTypeScriptのWebアプリを例に、npmを中心として、pnpm・Yarnとの関係、基本操作、導入が止まったときの確認まで整理します。コマンドやファイルの記載は説明用の例です。

1. パッケージマネージャーは、部品の導入と管理をする道具

アプリで外部のパッケージを使うには、必要なものを実行環境に用意します。ただし、欲しい部品のファイルを1つダウンロードすれば終わり、とは限りません。

前回の例では、アプリがパッケージAを使い、そのAが別のパッケージBを必要としていました。AとBのバージョンにも条件があれば、それに合う組み合わせを取りそろえる必要があります。

この作業を助けるのが、パッケージマネージャーです。部品の追加・更新・削除や、依存関係の導入を行います。たとえばnpmのinstallは、指定したパッケージと、それが必要とするパッケージを導入します。npm公式：npm install

料理でいえば、必要な材料の一覧を見て、仕入れを手配する係に近いイメージです。材料そのものがパッケージで、それを取りそろえる道具がパッケージマネージャーです。

「部品」と「部品を管理する道具」を分けて考えると、AIの説明も読みやすくなります。

2. npm・pnpm・Yarnは、同じ役割を担う別の道具

JavaScriptの開発では、npm・pnpm・Yarnという名前を見かけます。いずれも、パッケージや依存関係を管理するための道具です。

ただし、内部の保存方法、設定、コマンド、ロックファイルの形式などは異なります。

pnpmの保存方式は、複数のプロジェクトで同じ部品を使う場合にも再利用しやすい仕組みです。Yarnには、通常のnode_modulesへの配置以外の方法もあります。「どの道具でも、内部まで全部同じ」とは考えないようにしましょう。pnpm公式：仕組みと目的、pnpm公式：install、Yarn公式：Introduction、Yarn公式：install

また、npmという名前は、手元で使うコマンドだけでなく、パッケージを公開・配布するサービスの話にも出てきます。部品を配布する保管場所を「レジストリ」と呼び、そこから必要なものを取得します。道具と保管場所は、役割が違います。npm公式：npmについて

この記事で覚えたいのは、3つの道具を全部使えるようになることではありません。そのプロジェクトで決められた道具を使うことです。

READMEの手順、package.jsonのpackageManager欄、ロックファイルなどが手がかりになります。複数種類のロックファイルがある場合は、READMEや公開時の設定と照らし合わせ、使う道具を確認します。npm公式：package.json

AIがいつもnpmを使うとしても、対象がpnpmのプロジェクトなら、既存の手順に合わせて進めるよう伝えましょう。

3. 注文書・明細・届いた部品を分けて考える

前回出てきた3つのファイル・フォルダーを、道具の側から見直します。ここからは、一般的なnpmの構成を例にします。

たとえば、注文書には「この範囲のバージョンを使う」と書いてあり、明細には「今回、このバージョンを取りそろえた」と記録されます。欲しい条件と、具体的に選ばれた構成を分けて残しているわけです。

ロックファイルは、別の環境でも同じ依存関係を取りそろえることを助けます。アプリのプロジェクトでは、通常、ソースコードと一緒にGitで管理します。npm公式：package-lock.json

一方、一般的なnpmの構成では、node_modulesを丸ごとGitHubに置く代わりに、記録を使って必要な場所で部品を取りそろえます。そのため、コードを取得した直後は、部品の実体がまだ用意されていないことがあります。

ただし、ロックファイルがあれば、どのパソコンでも必ず同じように動くという意味ではありません。Node.jsのバージョン、OS、設定値なども関係します。ロックファイルは、依存関係の再現を助けるものと捉えましょう。

4. 既存のアプリを動かすために部品を取りそろえる

ここでは、GitHubから取得したnpmのプロジェクトに、package.jsonとpackage-lock.jsonがあり、READMEにもnpmを使う手順が書かれている想定です。Node.jsとnpmは、そのプロジェクトで求められるバージョンが利用できるものとします。

まず、ターミナルで開いている場所が、目的のアプリのフォルダーかを確認します。別のアプリや、1つ上のフォルダーで作業すると、違うファイルを読み込んでしまうことがあります。

READMEで指定されている導入手順が、たとえば次のものです。

npm install

パッケージ名を付けずに実行すると、プロジェクトに記録された依存関係を導入します。整合するロックファイルがあれば、そこに記録されたバージョンが使われます。ただし、package.jsonと条件が合わなければ、ロックファイルが更新される場合もあります。npm公式：npm installとロックファイル

記録済みの構成を変えず、依存関係をきれいに取りそろえたい場面では、次のコマンドも使われます。

npm ci

npm ciは、ロックファイルを前提に導入します。package.jsonとの不整合があれば、ロックファイルを書き換えて進むのではなく、エラーで止まります。既存のnode_modulesがあれば削除してから導入し、package.jsonとロックファイルは変更しません。公開前の自動処理などでも使われます。npm公式：npm ci

どちらが常に正しいということではありません。目的と、プロジェクトの手順に合わせて選びます。

5. 新しい部品の追加・更新・削除を区別する

既存のアプリを動かすために部品を取りそろえることと、新しい機能のために部品を追加することは、別の作業です。

たとえば、日付処理のパッケージdayjsを新しく採用する、と判断した場合の説明用コマンドは次のとおりです。この記事で導入を勧めているという意味ではありません。

npm install dayjs

通常の設定では、パッケージを導入し、package.jsonの依存関係とロックファイルにも反映します。パッケージ名を付けないnpm installとの違いに注目してください。npm公式：npm install

すでに使っている部品を更新するときや、不要になった部品を削除するときは、別の操作を使います。

npm updateは、宣言されたバージョンの条件に従って更新する操作です。常に最新のメジャーバージョンへ上がるわけではありません。また、npm uninstallは部品や依存関係の記録を削除しますが、自分で書いた利用コードを自動で直してくれるわけではありません。npm公式：npm update、npm公式：npm uninstall

AIが「依存関係を直します」と言ったときも、何を変えるつもりかを確認します。取りそろえるだけなのか、新しい部品を入れるのか、使うバージョンを変えるのかで、アプリへの影響は違います。

6. npm runは、プロジェクトに登録した作業を実行する

AIコーディングでは、次のようなコマンドもよく出てきます。

npm run dev
npm run build

これは、パッケージを導入するコマンドではありません。package.jsonのscriptsに登録された作業を実行するコマンドです。npmには、部品の管理に加えて、こうした作業を呼び出す機能もあります。npm公式：npm run

たとえば、次は説明用の設定です。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

この例では、npm run devがviteを、npm run buildがvite buildを呼び出します。npmは、登録された指示を呼び出す窓口で、実際の処理を行うのは呼び出された道具です。

devやbuildという名前なら、どのアプリでも中身が同じとは限りません。プロジェクトにその名前の作業が登録されていなければ、実行もできません。

部品の導入が成功したことと、アプリが動くこと、ビルドが通ることは、別々に確認します。

7. 導入が止まったときは、原因を分けて確認する

パッケージマネージャーがエラーを出したからといって、アプリのソースコードが必ず間違っているとは限りません。道具、記録、取得先、実行環境のどこで止まったかを見ます。

ログは最後の「失敗しました」だけでなく、原因を説明している行を読みます。AIには、次のように確認内容を伝えられます。

READMEとロックファイルを確認して、このプロジェクトのパッケージマネージャーを使ってください。導入が失敗した場合は、最初の原因を確認し、追加・更新・設定変更のどれが必要か説明してください。

ログに警告が出た場合も、操作自体が成功したかと、警告への対応が必要かを分けて判断します。

また、導入時にパッケージ側の処理が実行される構成もあります。業務では、利用するパッケージや取得先を組織のルールに沿って確認します。Yarn公式：導入の各工程

原因が分からないままロックファイルを削除したり、強制する設定を加えたりすると、再現したかった構成まで変わることがあります。まず、どの条件が合わずに止まったかを確認しましょう。

8. まとめと理解度確認

パッケージマネージャーは、アプリに必要な部品と、その依存関係を導入・管理する道具です。npm・pnpm・Yarnは、その役割を担う別の道具であり、対象プロジェクトの手順に合わせて使います。

既存の構成を取りそろえること、新しい部品を追加すること、バージョンを更新することは違います。また、部品を導入することと、登録された作業を実行することも別です。

AIの作業を見るときは、「どの道具で、何をそろえ、何を変更し、その後どこまで確認したか」を追いかけましょう。

自分の言葉で説明してみる

1. パッケージとパッケージマネージャーは、役割がどう違いますか？
2. READMEにpnpmを使う手順がある場合、普段使うnpmで進めてよいでしょうか？
3. package.jsonとロックファイルは、何を分けて記録していますか？
4. npm installとnpm install dayjsは、この記事では何が違いますか？
5. npm ciで記録に不整合があれば、ロックファイルが自動で書き換わりますか？
6. npm run buildが実行する内容は、どこで決まりますか？

解答例

1. パッケージは導入して使う部品、パッケージマネージャーはその部品の導入や管理を行う道具です。
2. 既存の手順に合わせてpnpmを使います。道具を変えるなら、設定やロックファイル、公開時の処理への影響を含めて、別の変更として判断します。
3. package.jsonは必要な部品やバージョンの条件などを、ロックファイルは具体的に解決された依存関係の構成などを記録します。
4. 前者はプロジェクトの依存関係を導入する操作、後者は指定した部品を追加する操作です。
5. 書き換わりません。package.jsonと整合しなければ、エラーで止まります。
6. package.jsonのscriptsにあるbuildの指示で決まります。同じ名前でも、プロジェクトによって中身は異なります。

参考資料

• npm公式：npmについて
• npm公式：npm install
• npm公式：npm ci
• npm公式：package.json
• npm公式：package-lock.json
• npm公式：npm run
• npm公式：npm update
• npm公式：npm uninstall
• pnpm公式：仕組みと目的
• pnpm公式：install
• Yarn公式：Introduction
• Yarn公式：install

資料確認日：2026年10月12日

npm install

npm ci

npm install dayjs

npm run dev
npm run build

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}