node_modulesは消してよい — npmとパッケージ管理

npmとパッケージ管理。パッケージの箱とつながる線、鍵の付いた管理書類。

チュートリアルの通りに npm install を打つと、ものの数十秒で node_modules というフォルダができます。

前回: fetchの結果が undefined — 非同期処理の基本 ここから、書いたコードを「配る・動かす」ための道具の話に入ります。 この記事のコマンドは、断りがない限りすべて VMの中の Ubuntu で打ちます。 ホストのWindowsではありません。

そして、サイズを見て固まりました。

250M	node_modules

入れた覚えがあるのは1つか2つなのに、中には数百個のフォルダが入っています。

何が入っているのか説明できないまま使うのが、正直かなり怖かった。 消していいのかも分からないので、とりあえず放置していました。Gitに上げようとして「ファイルが多すぎる」と言われたこともあります。

結論から書きます。node_modules は消してよいフォルダです。 そして、消してよい理由が分かることが、npm を理解するということそのものでした。

対象レベル: 初級 / 区分: 必修

目次

この記事でわかること

  • node_modules は消してよいということと、その理由
  • apt と npm は「入れる場所」が根本的に違うこと(ここが分かると -g の意味が分かる)
  • package-lock.json を Git に入れないと「自分の環境では動く」が起きる理由
  • npm run の本質はパスを通すことであって、コマンドの短縮ではないこと

この記事でやること

  1. VM に Node.js を入れる(apt ではなく nvm を使う理由も含めて)
  2. npm init -y で package.json を作り、中身を1項目ずつ読む
  3. 軽いツールを1つだけ入れて、node_modules の中を ls で覗く
  4. npm run で動かし、npx と -g の違いを確かめる
  5. node_modules を消して、作り直す

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
パッケージ他人が書いて公開している、部品としてのプログラム。自分で書かずに持ってきて使う
npm(Node Package Manager)そのパッケージを取ってきて、プロジェクトに登録・管理する道具。Node.js に最初から付いてくる
nvm(Node Version Manager)Node.js 自体をホームディレクトリの中に入れて、バージョンを切り替える道具。sudo が要らない
node_modules取ってきたパッケージの実物が置かれるフォルダ。プロジェクトごとに作られ、消しても作り直せる
package.json / package-lock.json前者は「何が必要か」を書いた材料表、後者は「実際に何のどのバージョンを入れたか」の記録
npxパッケージを入れっぱなしにせず、その場で1回だけ実行するコマンド

VMにはまだ Node.js が入っていない

前に ホスト側に道具を入れる回 で、WindowsにNode.jsを入れました。あれはホストの話です。VM の中の Ubuntu には、まだ何も入っていません。

まず確認してください。VMの中の Ubuntu で打ちます。

bash
$ node -v
Command 'node' not found, but can be installed with:
sudo apt install nodejs

このメッセージが、最初の罠です。 親切に「sudo apt install nodejs で入れられますよ」と教えてくれます。でも、ここでその通りにしないほうがいい。

なぜ apt install nodejs を避けるのか

aptの回 で見た通り、apt は Ubuntu 公式のカタログからソフトを取ってきます。出どころが保証されていて安全です。 そこは何も問題ありません。

問題はバージョンです。

Ubuntu の公式リポジトリに入っている Node.js は、たいてい古い。 Ubuntu は「2年間、動作を変えない」ことを重視します。だから、リリース時点のバージョンで固定されます。一方 Node.js は半年ごとに新しいメジャー版が出ます。 この2つの時間軸は合いません。

実際、apt で入る Node.js が、最新のLTS(長期サポート版)より2〜3世代古いということが普通に起きます。チュートリアルの通りに書いたのに動かない、その原因が「Node.jsが古いから」だった、というのはよくある詰まり方です。

もうひとつ、より本質的な問題があります。

apt で入れると、Node.js は「OS全体に1つ」しか置けません。

apt で入れた場合困ること
置かれる場所/usr/bin/nodeOS全体で共有
バージョン1つだけプロジェクトAは18、Bは22 が両立できない
入れ替えsudo が必要全部のプロジェクトに影響する

仕事や学習でプロジェクトが増えると、「このプロジェクトは古いNodeでしか動かない」という状況に必ず出会います。そのたびにOS全体のNodeを入れ替えるのは無理があります。

だから nvm を使う

nvm(Node Version Manager)は、Node.js を「ユーザーのホームディレクトリの中」に入れる道具です。

このサイトでは nvm を推します。 理由は3つです。

  1. バージョンを切り替えられる。 nvm use 18 / nvm use 22 で一瞬で変わる
  2. sudo が要らない。 すべて ~/.nvm の下に入るので、ユーザーと権限の回 で見た「余計な権限を使わない」原則を守れる
  3. プロジェクトごとに変えられる。 ディレクトリを移動して nvm use するだけ

もうひとつの選択肢に NodeSource(Node.js公式が用意している apt 用リポジトリ)があります。こちらも正しい方法です。 サーバーに1つのバージョンだけ入れたい、という場面ではむしろこちらが向いています。ただし今は学習中で、バージョンを行き来する場面のほうが多いので、nvm を選びます。

nvm を入れる前に:スクリプトをそのまま実行する危険

nvm の公式手順は、こう書かれています。

bash
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

この形は、非常によく見かけます。そして、非常に危険な形でもあります。

何をしているか分解します。

部分意味
curl -o- <URL>ネットからファイルを取ってきて、画面(標準出力)に流す
|その出力を、次のコマンドに渡す
bash渡されたものを、そのまま実行する

つまり「ネットにあるものを、中身を見ずに実行する」というコマンドです。 もし配布元が乗っ取られていたら、あなたのユーザー権限でできることは全部できます。 ファイルを読む、送信する、鍵を盗む。sudo を付けていなくても、権限の回 で見た通り、自分のホームディレクトリの中身は全部自分のものです。

これは、aptの回で「検索して出てきたサイトから .deb を拾うな」と書いたのと同じ話です。 違うのは、こちらは公式が推奨している形だという点だけ。「公式が言っているから安全」ではなく、「公式のURLであることを自分で確かめたから、まあ許容する」という順番であるべきです。

中身を先に見る

分けて実行すれば、中身を見られます。 こうします。

まず curl が入っていなければ入れます(Ubuntu Server の最小構成には無いことがあります)。

bash
$ sudo apt update
$ sudo apt install curl

次に、実行せずにファイルとして保存します。

bash
$ cd ~
$ curl -fsSL -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh

-o install_nvm.sh が「画面に流さずファイルに保存する」という指定です。ここが -o-(画面に流す)との違いです。

保存できたら、読みます。

bash
$ less install_nvm.sh

less は上下キーでスクロールでき、q で抜けられます。

全部理解する必要はありません。 見るべきは次の3点だけです。

  • nvm_install_dir が $HOME/.nvm になっているか(ホームの下に入るか)
  • sudo という単語が出てこないか(/less の中で /sudo と打つと検索できます)
  • 見覚えのないドメインに通信していないか(github.com 以外が出てきたら要注意)

検索はこうします。less を開いた状態で打ちます。

/sudo

何も見つからなければ、少なくとも「勝手に管理者権限を取ろうとはしていない」ことが確認できます。

なぜ URL にバージョン番号(v0.40.3)が入っているのか。 これはタグといって、その時点のコードに固定する指定です。master や main を指定すると「今この瞬間の最新」になり、昨日と今日で中身が変わります。 検証したものと実行するものを一致させるために、バージョンを固定したURLを使うのが正しいです。最新のバージョン番号は nvm のGitHubリポジトリのREADMEに書かれています。

実行して、パスを通す

読んで納得したら、実行します。

bash
$ bash install_nvm.sh

最後にこう出ます。

=> Close and reopen your terminal to start using nvm or run the following to use it now:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

「ターミナルを開き直してください」と言われています。 これは、インストーラが ~/.bashrc(シェルの起動時に読まれる設定ファイル)に数行を書き足したからです。すでに開いているシェルには反映されていません。

一番確実なのは、一度ログアウトして入り直すことです。それが面倒なら、こう打ちます。

bash
$ source ~/.bashrc

確認。

bash
$ command -v nvm
nvm

nvm と返れば成功です。 which nvm だと何も出ないので驚きますが、これは正常です。nvm はコマンド(実行ファイル)ではなく、シェルの関数として読み込まれているためです。which は実行ファイルしか探さないので、見つかりません。

Node.js を入れる

bash
$ nvm install --lts

--lts は Long Term Support(長期サポート版) の意味です。迷ったらこれで正解です。 最新版(nvm install node)は新機能が早く入る代わりに、対応していないライブラリがあります。

確認。

bash
$ node -v
$ npm -v
v22.20.0
10.9.3

バージョン番号は時期によって違います。数字が出れば成功です。

ここで大事なことがひとつ。npm は別に入れていません。 Node.js を入れると npm も一緒に付いてきます。 npm は Node.js に同梱されている標準のパッケージ管理ツールだからです。

[スクリーンショット: 01_node_version.png] node -v と npm -v の両方が表示されている画面を撮ってください。プロンプトに Ubuntu のホスト名が出ていることも一緒に写すと、「ホストのWindowsではなくVMの中で打っている」ことが後から自分で確認できます。

入っているバージョンを見る・切り替える

bash
$ nvm ls
->     v22.20.0
default -> lts/* (-> v22.20.0)

-> が付いているのが今使っているバージョンです。

別のバージョンを足したいときは、こうです。

bash
$ nvm install 20
$ nvm use 20
$ node -v      # v20.x.x になる
$ nvm use 22   # 戻す

新しいターミナルを開いたときに使われるバージョンを決めるにはこうします。

bash
$ nvm alias default lts/*

戻し方

nvm ごと消したくなったら、こうです。

bash
$ rm -rf ~/.nvm

これで Node.js も npm も全部消えます。sudo が要らないのがポイントです。ホームディレクトリの下にしか物を置いていないから、消すのもホームの下だけで済みます。

最後に ~/.bashrc の末尾に足された3行(NVM_DIR の行と、その下の2行)を消してください。

bash
$ nano ~/.bashrc

この「入れたものを完全に元に戻せる」という感覚が、sudo apt install との一番の違いです。


apt と npm は「入れる場所」が違う

ここが、この記事で一番大事なところです。

aptの回 で、apt は「通販カタログ」だと書きました。npm も同じくカタログから物を取り寄せる道具です。やっていることは似ています。

決定的に違うのは、どこに置くかです。

aptnpm
何のための道具かOSに必要なソフトを入れるプロジェクトに必要な部品を入れる
置かれる場所/usr/bin などシステム全体そのプロジェクトの node_modules/
誰から見えるか全ユーザー・全プロジェクトそのフォルダの中だけ
同じソフトの複数バージョン原則1つだけプロジェクトごとに別々でよい
必要な権限sudo不要
消すときapt purgeフォルダごと rm -rf

apt は「OS全体に1つ」入れる。npm は「プロジェクトごとに」入れる。

これが分かると、いろいろな謎が一度に解けます。

なぜ node_modules が数百MBもあるのか。 プロジェクトごとに、独立したコピーを持っているからです。 10個プロジェクトを作れば、同じライブラリが10回ディスクに置かれます。無駄に見えますが、これは意図された設計です。 プロジェクトAを壊さずにプロジェクトBのバージョンを上げられる、という利益と引き換えに、ディスクを払っています。

なぜ node_modules を消していいのか。 package.json と package-lock.json があれば、いつでも完全に同じ状態を作り直せるからです。 つまり node_modules は「設計図から生成された成果物」であって、原本ではありません。原本は package.json のほうです。

そして、-g の意味もここで分かります。

bash
$ npm install -g 何か

-g は global の意味で、「プロジェクトの中ではなく、システム側(に近いところ)に入れる」という指定です。 つまり、-g を付けると npm が apt のような振る舞いをするということです。

プロジェクトごとに入れられるという npm の長所を、わざわざ捨てる指定でもあります。だから後で書く通り、基本的には使いません。


練習用のプロジェクトを作る

実際に手を動かします。VMの中の Ubuntu です。

bash
$ mkdir -p ~/practice/npm-test
$ cd ~/practice/npm-test

この時点では、ただの空フォルダです。

bash
$ ls -a
.  ..

npm init -y で package.json を作る

bash
$ npm init -y

-y は「全部の質問に yes(既定値)で答える」という指定です。付けないと、名前は何か、ライセンスは何か、と対話で聞かれます。練習では -y で構いません。

bash
$ ls
package.json

ファイルが1つできました。これだけです。 node_modules はまだありません。

package.json を1項目ずつ読む

bash
$ cat package.json
{
  "name": "npm-test",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": ""
}

npmのバージョンによって項目の並びや有無は少し変わります。 大事なのは中身です。

項目意味今の段階での重要度
nameプロジェクトの名前。 既定ではフォルダ名が入る低(公開しないなら何でもよい)
versionこのプロジェクト自身のバージョン低(公開しないなら触らない)
main他から読み込まれたときの入口ファイル低
scriptsnpm run ○○ で走らせるコマンドの定義高。ここを一番使う
keywords / author / description公開したときの説明用低
licenseライセンス低(公開しないなら ISC のままでよい)
dependencies動かすのに必要な部品(まだ無い)高
devDependencies作るのに必要な道具(まだ無い)高

package.json は、このプロジェクトの「材料表」です。

料理でいえば、package.json はレシピの材料欄、node_modules は買ってきて冷蔵庫に入れた実物です。材料欄さえあれば、実物はいつでも買い直せます。 逆に材料欄を失うと、冷蔵庫の中身を見て何を買ったのか推測するしかなくなります。

[スクリーンショット: 02_package_json.png] npm init -y の直後に cat package.json した画面を撮ってください。dependencies がまだ存在しない状態を残しておくと、次の手順との差が分かります。


dependencies と devDependencies の違い

これから部品を入れますが、その前に区別を押さえます。ここを間違えると、後で本番サーバーが無駄に重くなります。

dependenciesdevDependencies
ひとことで動かすのに要るもの作るのに要るもの
入れ方npm install <名前>npm install --save-dev <名前>
例画面を作るライブラリ、日付を扱うライブラリ整形ツール、テストツール、型チェック
本番サーバーに要るか要る要らない
消したらどうなるかアプリが動かなくなるアプリは動く。開発が不便になるだけ

判断の基準はひとつです。「作ったものを他人のサーバーで動かすとき、それは要るか」。

例えるなら、dependencies は料理の材料、devDependencies は調理器具です。 出来上がった料理を配るときに、フライパンは付けません。でも材料は料理そのものの一部なので、外せません。

本番でインストールするときは、こう打つと devDependencies を飛ばせます。

bash
$ npm install --omit=dev

これが効くのは、正しく分けて登録していた場合だけです。 全部 dependencies に入れていると、本番サーバーに整形ツールやテストツールまで入ります。動きはするので、間違いに気づきにくい。


実際に1つだけ入れてみる

重いフレームワークは入れません。 学習の目的は「中を覗くこと」なので、中が見えるくらい小さいものを選びます。

Prettier(コードを自動で整形するツール)を1つだけ入れます。これは開発中にしか使わない道具なので、--save-dev を付けます。

bash
$ npm install --save-dev prettier

数秒で終わります。

added 1 package, and audited 2 packages in 2s
found 0 vulnerabilities

--save-dev は -D と短く書けます。 npm i -D prettier でも同じです。ネットの記事では短い形をよく見ますが、最初のうちは長い形で打ったほうが、何をしているか自分で分かります。

package.json がどう変わったか

bash
$ cat package.json
{
  "name": "npm-test",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "license": "ISC",
  "devDependencies": {
    "prettier": "^3.6.2"
  }
}

devDependencies という項目が増えました。 npm install は、入れるだけでなくpackage.json に書き足すところまでやります。

^3.6.2 の ^ については、少し後で必ず説明します。ここが一番の落とし穴です。

何が増えたか

bash
$ ls -a
.  ..  node_modules  package.json  package-lock.json

2つ増えました。 node_modules/ と package-lock.json です。


node_modules の中を覗く

ここが、この記事の山場です。

bash
$ ls -a node_modules
.  ..  .bin  .package-lock.json  prettier

驚くほど何もありません。 入れたのは1つなので、prettier というフォルダが1つあるだけです。

「数百MBの謎のフォルダ」の正体は、これがたくさん並んでいるだけでした。

サイズも見てみます。

bash
$ du -sh node_modules
9.5M	node_modules

Prettier ひとつで約10MBです。 これが数十個になれば、数百MBになるのは当たり前だと分かります。

.bin が本体

いま見えた .bin が重要です。

bash
$ ls node_modules/.bin
prettier

これは「実行できるコマンド」が置かれる場所です。 実体はこう確認できます。

bash
$ ls -l node_modules/.bin
prettier -> ../prettier/bin/prettier.cjs

-> はシンボリックリンク(ショートカット)です。 本体は node_modules/prettier/ の中にあって、.bin にはその近道が置かれています。

この .bin が、後で出てくる npm run の正体です。今は「こういうフォルダがある」とだけ覚えておいてください。

直接動かしてみる

bash
$ ./node_modules/.bin/prettier --version
3.6.2

動きました。 でも、毎回このパスを打つのは現実的ではありません。

[スクリーンショット: 03_node_modules.png] ls -a node_modules と ls -l node_modules/.bin を続けて実行した画面を撮ってください。「node_modules の中身は普通のフォルダの集まりでしかない」と分かることが、この記事の一番の目的です。


package-lock.json は必ず Git に入れる

もうひとつ増えたファイルを見ます。

bash
$ head -30 package-lock.json
{
  "name": "npm-test",
  "lockfileVersion": 3,
  "packages": {
    "node_modules/prettier": {
      "version": "3.6.2",
      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.6.2.tgz",
      "integrity": "sha512-...."
    }
  }
}

package.json には ^3.6.2 と書いてあったのに、こちらには 3.6.2 と正確な数字が書かれています。 さらに、取ってきたURLと、改ざん検出用のハッシュ値(integrity)まで記録されています。

package.json が「材料表」なら、package-lock.json は「レシート」です。 何を、どのバージョンで、どこから、実際に買ってきたのかの記録です。

なぜ必ず Git に入れるのか

package-lock.json を Git に入れないと、「自分の環境では動く」が起きます。

理由は ^ にあります。

package.json に "prettier": "^3.6.2" と書いてあるとき、これは「3.6.2 を入れろ」という意味ではありません。

^3.6.2 は「3.6.2 以上、4.0.0 未満なら何でもよい」という意味です。

つまり、あなたが今日 npm install すれば 3.6.2 が入るかもしれませんが、来月に別の人が同じリポジトリをクローンして npm install すると、3.9.1 が入るかもしれません。

あなた1か月後の同僚
package.json の記述^3.6.2^3.6.2(同じ)
実際に入るもの3.6.23.9.1
動くか動く動かないかもしれない

package-lock.json があれば、この差が消えます。 npm はロックファイルがあるとき、そこに書かれた正確なバージョンを優先して入れるからです。

「自分の環境では動くんですけど」の相当な割合が、これです。 コードは完全に同じ、package.json も同じ、なのに動かない。違うのは、実際に入ったライブラリのバージョンだけ、という状況です。

.gitignore はこう書く

Git の導入回 で .gitignore を作りました。npm を使うプロジェクトでは、こう書きます。

bash
$ cat > .gitignore <<'EOF'
  node_modules/
  EOF

書くのは node_modules/ だけです。 package-lock.json は書きません。

ファイルGitに入れるか理由
package.json入れる材料表。これが原本
package-lock.json入れるこれが無いと再現できない
node_modules/入れない上の2つから生成できる。しかも巨大

「生成できるものは入れない。生成の指示書は入れる。」 これが判断の基準です。


^ と ~ と 1.2.3 の意味

バージョン番号の書き方を整理します。Node.js の世界は、セマンティックバージョニング(SemVer)という取り決めに従っています。

3.6.2 は「メジャー.マイナー.パッチ」です。

位置名前何が変わったか
3メジャー今までの使い方が壊れる変更が入った
6マイナー機能が追加された(壊れない)
2パッチバグが直された(壊れない)

この前提の上で、package.json の書き方が意味を持ちます。

書き方許す範囲具体例(3.6.2 のとき)使いどころ
^3.6.2メジャーが同じなら何でも3.6.2 〜 3.999.999npmの既定。バグ修正を自動で取り込みたい
~3.6.2パッチだけ3.6.2 〜 3.6.999もう少し慎重にしたいとき
3.6.2完全に固定3.6.2 のみ絶対に変わってほしくないとき
* / latest何でも4.x でも入る使わない

^0.x.y だけは例外です。 メジャーが 0 のとき(=まだ安定していないという宣言)は、^0.2.3 は 0.2.3 〜 0.2.x しか許しません。0.3.0 は入りません。 「0.x はいつ壊れてもおかしくない」という扱いだからです。

既定を ^ ではなく固定にしたいなら、こう打ちます。

bash
$ npm install --save-exact --save-dev prettier

package.json に "prettier": "3.6.2" と、記号なしで書かれます。

とはいえ、package-lock.json を Git に入れていれば、^ のままでも再現性は保てます。 順番としては、まずロックファイルをコミットする。それが最優先です。


npm ci と npm install の違い

ロックファイルの話には続きがあります。

npm installnpm ci
見るファイルpackage.json が主package-lock.json のみ
ロックファイルと package.json が食い違ったらロックファイルを書き換えるエラーで止まる
既存の node_modules差分だけ更新まるごと消してから入れ直す
ロックファイルが無いとき作るエラーで止まる
速さ場合によるたいてい速い
使う場面手元で開発しているときCI・本番・「壊れたので作り直したい」とき

ci は Continuous Integration(継続的インテグレーション)の略です。

自動テストの環境で npm install を使うと、意味がなくなります。 「ロックファイルには 3.6.2 と書いてあるけど、まあ 3.9.1 でいいか」と勝手に判断されると、テストしたものと、本番で動くものが違うからです。

やってみます。

bash
$ npm ci
added 1 package in 1s

node_modules は一度まるごと消されて、作り直されています。 これが「毎回まっさらから作る」という ci の性質です。

手元で調子が悪いときの決まり手も、これです。

rm -rf node_modules
npm ci

node_modules を消すのが怖くなくなると、この解決策が使えるようになります。


npm run はパスを通している

scripts を使います。package.json を編集します。

bash
$ nano package.json

scripts の部分をこう書き換えます。

  "scripts": {
    "format": "prettier --write .",
    "check": "prettier --check ."
  },

JSON はカンマの位置に厳しいです。 最後の項目の後ろにカンマを付けるとエラーになります。

整形される対象のファイルを1つ作ります。わざと汚く書きます。

bash
$ cat > index.js <<'EOF'
  const   greet = (name)=>{
        return    "hello, "+name
  }
  console.log( greet("obmes") )
  EOF

まず、整形が必要かどうかを調べます。

bash
$ npm run check
> npm-test@1.0.0 check
> prettier --check .

Checking formatting...
[warn] index.js
[warn] Code style issues found in the above file. Run Prettier with --write to fix.

実際に整形します。

bash
$ npm run format
index.js 41ms
bash
$ cat index.js
const greet = (name) => {
  return "hello, " + name;
};
console.log(greet("obmes"));

空白もセミコロンも揃いました。

ここで一番大事なこと

npm run は、コマンドを短くするための機能ではありません。

確かめます。prettier と直接打つと、どうなるか。

bash
$ prettier --version
prettier: command not found

見つかりません。 node_modules/prettier は確かに存在するのに、です。

一方、npm run 経由なら動きました。違いはこれです。

npm run は、コマンドを実行する直前に、node_modules/.bin を PATH の先頭に追加します。

さっき見た .bin フォルダが、ここで効いてきます。

打ち方node_modules/.bin が PATH にあるか結果
prettier無いcommand not found
./node_modules/.bin/prettier関係ない(直接指定)動く
npm run checknpm が一時的に追加する動く
npx prettiernpx が追加する動く

scripts に書いた文字列は、ただのシェルコマンドです。 特別な文法はありません。特別なのは「実行される環境」のほうです。

[スクリーンショット: 04_npm_run.png] prettier --version が command not found になる画面と、npm run check が動く画面を続けて撮ってください。 この2つが並んでいると、npm run が何をしているかが一目で分かります。

どんなスクリプトが定義されているか調べる

他人のプロジェクトを触るとき、最初に打つべきコマンドです。

bash
$ npm run
Scripts available in npm-test@1.0.0 via `npm run-script`:
  test
    echo "Error: no test specified" && exit 1
  format
    prettier --write .
  check
    prettier --check .

「このプロジェクトで何ができるか」の一覧です。 READMEより信用できます。


-g をやめて npx を使う

チュートリアルには、こう書かれていることがあります。

bash
$ sudo npm install -g 何か

この形は、2つの意味で避けたい形です。

1. sudo を付けるのが危険

npm はインストール時に、パッケージに含まれるスクリプトを実行することがあります(後で詳しく書きます)。sudo を付けると、それが管理者権限で動きます。

nvm を使っていれば、そもそも sudo は不要です。 Node.js が ~/.nvm の下にあるので、-g で入れたものも ~/.nvm/versions/node/v22.x/lib/node_modules に入ります。全部ホームの下です。

bash
$ npm root -g
/home/ユーザー名/.nvm/versions/node/v22.20.0/lib/node_modules

/home/ から始まっていれば、sudo は要りません。 もし /usr/ から始まっていたら、apt か公式インストーラで入れた Node.js を使っています。

2. バージョンがプロジェクトと食い違う

-g で入れたものは「OS全体に1つ」です。 apt と同じ状態に戻ります。

こういう事故が起きます。

バージョン
-g で入っている prettier2.8.8(去年入れた)
プロジェクトの devDependencies3.6.2
手元で prettier と打つと2.8.8 が動く
CIで npm run format すると3.6.2 が動く

整形結果が食い違い、変更していないファイルが差分に出続けます。 原因を探すのに時間を溶かすやつです。

npx が解決する

bash
$ npx prettier --version
3.6.2

npx は、まず node_modules/.bin を探します。 そこにあればそれを使います。

無ければ、一時的にダウンロードして実行し、終わったら残しません。

bash
$ npx cowsay "hello"

初回はこう聞かれます。

Need to install the following packages:
cowsay@1.6.0
Ok to proceed? (y)

「入れていいですか」と聞いてくるのが親切な点です。 ここで y を押す前に、そのパッケージ名を自分が知っているか確認してください。 タイプミスで似た名前のパッケージを引く事故があります。

-gnpx
残るかずっと残る残らない(キャッシュのみ)
バージョン1つに固定されるプロジェクトのものが優先される
使う場面ほぼ無い一度きりの実行、雛形の作成

「-g で入れろ」と書いてある記事を見たら、まず npx で代替できないか考える。 これで大半は解決します。


依存が依存を呼ぶ

ここからセキュリティの話です。ここが npm の一番怖いところでもあります。

直接入れたものと、全部の差

bash
$ npm ls --depth=0
npm-test@1.0.0 /home/ユーザー名/practice/npm-test
└── prettier@3.6.2

「自分が入れたもの」の一覧です。1つだけです。

bash
$ npm ls --all

今回は Prettier が依存を持たない珍しいパッケージなので、結果はほぼ同じになります。これは意図的にそういうものを選びました。

普通のパッケージはこうなりません。 例えばテストツールやビルドツールを1つ入れると、画面が流れきらないほどの木が表示されます。

数を数えると分かりやすいです。

bash
$ ls node_modules | wc -l

今は 1 か 2 です。しかし、実際の開発でよく使うツールを1つ入れるだけで、この数字は数十から数百になります。

「1つ入れたつもりが、実際には数百個入っている。」 これが node_modules が数百MBになる本当の理由です。あなたが選んだのは1つでも、そのパッケージが5つに依存し、その5つがそれぞれ10個に依存する。 掛け算で増えます。

そして、その数百個の中には、あなたが一度も名前を見たことがないパッケージが含まれています。 どれか1つが乗っ取られたら、あなたのプロジェクトに影響します。これは理論上の話ではなく、実際に何度も起きています。

npm audit で調べる

bash
$ npm audit
found 0 vulnerabilities

既知の脆弱性が報告されているパッケージが含まれていないかを、npm のデータベースと照合します。

何か見つかると、こう出ます。

# npm audit report

some-package  <1.2.3
Severity: high
Prototype Pollution - https://github.com/advisories/GHSA-xxxx
fix available via `npm audit fix`

自動で直せるものは、こう打ちます。

bash
$ npm audit fix

npm audit fix --force は安易に打たないでください。 --force はメジャーバージョンを上げてでも直そうとします。 つまり、動いていたコードが壊れる変更を勝手に入れます。 「脆弱性は消えたがアプリが動かない」という状態になります。

本番に関係ないものだけ除きたいときはこうです。

bash
$ npm audit --omit=dev

devDependencies は本番サーバーに配られないので、優先度が下がります。 これも、最初に --save-dev を正しく付けていたから使える技です。

インストール時にスクリプトが動く

これが一番知っておくべきことです。

npm install は、ダウンロードするだけではありません。 パッケージの package.json に postinstall などのスクリプトが書かれていると、インストールの過程で、それがあなたの権限で実行されます。

「まだ何も書いていないのに、コードが動く」ということです。C言語のライブラリをビルドするなど、正当な用途があるから存在する仕組みですが、悪用もできます。

止める指定があります。

bash
$ npm install --ignore-scripts

ただし、これを常用すると、正当な理由でスクリプトを使っているパッケージが動かなくなります。 ネイティブモジュールのビルドなどが該当します。

現実的な使い方はこうです。

場面判断
知っているパッケージを入れる普通に npm install
名前をよく知らないものを試す--ignore-scripts を付ける
本番のビルド環境ロックファイル前提で npm ci。信頼できる依存だけにする

結局、一番効く対策

知らないパッケージを入れないことです。

技術的な対策より、これが効きます。判断の材料はこうです。

  • 週間ダウンロード数が極端に少なくないか(npmjs.com で見られます)
  • 最終更新が何年も前で止まっていないか
  • GitHubリポジトリがちゃんと存在するか
  • 名前が有名パッケージと1文字違いでないか(タイポスクワッティングという手口です)

「便利そうだから入れる」の代償は、思っているより大きい。 1つ入れるたびに、自分が読んでいないコードが数十個増えます。 aptの回 で「検索して出てきた .deb を拾うな」と書きましたが、npm では公式のカタログから取っていても、中身の保証は apt ほど強くありません。 npm は誰でも公開できる場所だからです。

[スクリーンショット: 05_npm_audit.png] npm ls --depth=0 と npm audit の結果を撮ってください。「自分が入れたのは1つ」と「実際に監査されている数」が並ぶと、後で本物のプロジェクトを見たときの比較になります。


node_modules は消してよい

最初の疑問に戻ります。消します。

bash
$ du -sh node_modules
$ rm -rf node_modules
$ ls
9.5M	node_modules
index.js  package.json  package-lock.json

消えました。 当然、動かなくなります。

bash
$ npm run check
sh: 1: prettier: not found

作り直します。

bash
$ npm ci
added 1 package in 1s

確認。

bash
$ npm run check
Checking formatting...
All matched files use Prettier code style!

完全に元通りです。

この「消して、作り直せる」という往復を1回やっておくと、node_modules が怖くなくなります。

消してよいもの消してはいけないもの
node_modules/package.json
npm のキャッシュ(npm cache clean --force)package-lock.json
自分が書いたコード

node_modules は成果物であって、原本ではない。 これがこの記事の結論です。

練習を片付ける

このプロジェクトごと消して構いません。

bash
$ cd ~
$ rm -rf ~/practice/npm-test

nvm と Node.js は残しておいてください。 これから先ずっと使います。


よくある詰まり

npm: command not found になった

ターミナルを開き直したのに node も npm も見つからないなら、~/.bashrc に nvm の設定が書かれていない可能性があります。

bash
$ tail -5 ~/.bashrc

export NVM_DIR=... の3行があるか確認してください。無ければ、インストーラの最後に表示された3行を自分で追記します。

もうひとつの原因は、ログインの仕方です。 sudo su や sh で入っていると ~/.bashrc が読まれません。普通に bash でログインしてください。

sudo npm install したら壊れた

sudo を付けると、作られるファイルの持ち主が root になります。 その後 sudo 無しで npm install すると、「書き込めない」と言われます。

直し方は、まず持ち主を戻すことです。

bash
$ sudo chown -R $USER:$USER ~/.npm
$ sudo chown -R $USER:$USER node_modules

そもそも sudo npm を打たないのが正解です。 nvm を使っていれば必要ありません。

EACCES というエラーが出る

権限のエラーです。 権限の回 の内容がそのまま出てきます。sudo で押し切らず、なぜ書き込めないのかを見てください。 ほぼ確実に、過去に sudo npm を打ったことが原因です。

package-lock.json に毎回差分が出る

入れたときと npm install したときで npm のバージョンが違うと起きることがあります。チームで作業しているなら、Node.js のバージョンを揃えてください。 .nvmrc というファイルにバージョンを1行書いておくと、nvm use だけで揃います。

bash
$ node -v > .nvmrc

ネットが遅くて npm install が終わらない

VMのネットワーク設定を疑ってください。 NAT で外に出られているか、ping registry.npmjs.org で確認できます。DNSが引けていないだけということもあります。


まとめ

  • node_modules は消してよい。 package.json と package-lock.json から、いつでも作り直せる生成物だから
  • VMには Node.js を apt で入れない。 古いことが多く、OS全体に1つしか置けない
  • nvm を使う。 バージョンを切り替えられて、sudo が要らず、ホームの下だけで完結する
  • インストールスクリプトをパイプで直接実行しない。 -o でファイルに保存して、less で中身を見てから実行する
  • apt は「OS全体に1つ」、npm は「プロジェクトごとに」入れる。 この違いが分かれば -g の意味も分かる
  • dependencies は動かすのに要るもの、devDependencies は作るのに要るもの。 本番に配るかどうかで分ける
  • package-lock.json は必ず Git に入れる。 ^1.2.3 は 1.x の最新まで許すので、入れないと人によって違うものが入る
  • npm ci はロックファイルに厳密に従う。 CI・本番・作り直しではこちらを使う
  • npm run の本質は node_modules/.bin にパスを通すこと。 コマンドの短縮ではない
  • -g は避けて npx を使う。 -g は npm を apt と同じ状態に戻す指定
  • 依存は依存を呼ぶ。 1つ入れたつもりが数百個入り、その大半は名前も知らないもの
  • npm install はスクリプトを実行する。 npm audit で調べ、--ignore-scripts の存在を知っておき、知らないパッケージは入れない

参考リンク


次に読む

この記事は 【第3段階】プログラミング の 5 / 7 本目です。

記事
← 前の記事読んだだけでは作れない — Frontendの到達作品
→ 次の記事fetchの結果が undefined — 非同期処理の基本

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›Package Managers
  • npm
  • package.json と依存関係
  • セマンティックバージョニング

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次