npm コマンド 一覧｜package.json 書き方と実行結果・npm 12対応

npmとは、Node.jsに同梱されているパッケージ管理ツールで、package.json に書いた依存パッケージのインストールや、スクリプトの実行を行うコマンドです。 日常的に使うのは npm install・npm ci・npm run・npx の4つです。

この記事では、npmコマンドを目的別の早見表にまとめ、Node.js 22.22.2同梱のnpm 10.9.7で実行した出力を載せます。type・exports・workspaces まで入った完成形の package.json、^ と ~ の違い、npm ci の役割、エラーの再現と直し方、2026年7月に出たnpm 12（最新12.1.0）の変更点も実行結果で確認します。

npm コマンドの早見表

プロジェクトを始める：npm init

npm init -y は、質問を省略して package.json を作ります。 npm 10.9.7では name・version・description・main・scripts・keywords・author・license（"ISC"）の8項目が入りました（以降、出力のパスは短縮し、長い部分は ... で省略）。

npm 12.1.0では"type": "commonjs" が入り、author と license がなくなりました（リリースノートでは既定ライセンスがISCから空文字に変更）。

インストール：npm install と ^ ~ の違いを実測

$ npm i chalk@~4.0.0
added 6 packages, and audited 7 packages in 638ms
$ npm ls
p1@1.0.0 /work/p1
`-- chalk@4.0.0

$ npm i chalk@^4.0.0
changed 1 package, and audited 7 packages in 393ms
$ npm ls
`-- chalk@4.1.2
$ grep chalk package.json
    "chalk": "^4.1.2"

~4.0.0 は4.0.xの中の最新（4.0.0）、^4.0.0 は4.x.xの中の最新（4.1.2）が入りました。 ^ で指定すると、package.jsonには実際に入った版を先頭にした ^4.1.2 が書かれます。範囲の意味は、npmが内部で使う semver パッケージ（npx -y semver@7.7.2 -r "範囲" 版...）で確かめました。

^ は「マイナー・パッチの更新」、~ は「パッチだけ」を許します。 版を完全に固定するなら npm i -E か npm config set save-exact=true を使います。

依存は dependencies（実行時、npm i）、devDependencies（開発時だけ、-D）、peerDependencies（利用者側に入れてもらう）、optionalDependencies（無くても動く、-O）の4種類です。

package-lock.json と npm ci の関係

package-lock.json は、依存の依存まで含めて「実際に入った版」を記録するファイルです。 ^4.0.0 のような範囲指定でも、lockがあれば全員が同じ版を再現できます。lockはGitにコミットします。

rm -rf node_modules && npm ci は added 6 packages ... in 1s で完了しました。package.jsonに ms を手で追加し、lockを更新せずに npm ci すると次のように止まります。

npm error code EUSAGE
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error Missing: ms@2.1.3 from lock file

npm install でlockを更新してコミットすれば解消します。 CIで npm ci を使うと、lockの更新漏れにすぐ気づけます。

確認と更新：outdated・update・ls・explain

dayjs@1.11.0 を入れた状態（package.jsonは ^1.11.0）で確認しました。

$ npm outdated
Package  Current   Wanted   Latest  Location            Depended by
dayjs     1.11.0  1.11.23  1.11.23  node_modules/dayjs  p3
$ npm update
changed 1 package, and audited 2 packages in 559ms
$ npm ls
`-- dayjs@1.11.23

Wanted は範囲内の最新、Latest はレジストリの最新で、npm update は Wanted まで上げます（package.jsonの ^1.11.0 はそのまま）。範囲外の Latest へは npm i パッケージ@latest で明示的に上げます。npm outdated は古いものがあると終了コード1を返します。

「このパッケージはなぜ入っているのか」は npm explain（別名 npm why）で調べます。

$ npm why has-flag
has-flag@4.0.0
  has-flag@"^4.0.0" from supports-color@7.2.0
    supports-color@"^7.1.0" from chalk@4.1.2
      chalk@"^4.1.2" from the root project

スクリプト実行：npm run と npx

$ npm pkg set scripts.prebuild='echo pre' scripts.build='echo build' scripts.greet='node greet.js'
$ npm run build
> p4@1.0.0 prebuild
> echo pre
pre
> p4@1.0.0 build
> echo build
build
$ npm run greet -- --name=abc
> p4@1.0.0 greet
> node greet.js --name=abc
[ '--name=abc' ]

pre名前 / post名前 のスクリプトは自動で前後に実行されます。 スクリプトに引数を渡すときは -- の後ろに書きます。スクリプト内では node_modules/.bin にパスが通ります。存在しない名前は npm error Missing script: "nope" になり、npm run だけで一覧が出ます。

npx（npm exec）は、インストールせずにパッケージのコマンドを実行します。 npx -y semver@7.7.2 -r '~1.2.0' 1.2.5 1.3.0 は 1.2.5 を返しました（-y で確認を省略）。

セキュリティ：audit と fund

$ npm i lodash@4.17.20
$ npm audit
lodash  <=4.17.23
Severity: high
Command Injection in lodash - https://github.com/advisories/GHSA-35jh-r3h4-6jhm
...（ほか4件）
fix available via `npm audit fix`
node_modules/lodash

1 high severity vulnerability
$ npm audit fix
found 0 vulnerabilities
$ npm ls lodash
`-- lodash@4.18.1

npm audit は既知の脆弱性を一覧にし、npm audit fix は範囲内で直せる版へ更新します。 --force はメジャー更新を含むため動作確認とあわせて行います。--audit-level=critical ではhighのみの今回は終了コード0でした。npm fund は寄付先URLを表示します。

公開まわり：pack・version・publish

$ npm version patch --no-git-tag-version
v1.0.1
$ npm pack --dry-run
...
npm notice 17B index.js
npm notice 426B package.json
...

npm version は版を上げ、Gitリポジトリ内ならコミットとタグも作ります。 npm pack --dry-run で公開されるファイルを確認し、files で絞ります。npm publish（今回は未実行）でスコープ付きを初めて公開するときは --access public を付けます。

設定と保守：config・cache・doctor

$ npm config get registry
https://registry.npmjs.org/
$ npm config set save-exact=true --location=project
$ npm cache verify
Content verified: 2 (645635 bytes)
Finished in 0.042s

--location=project はプロジェクトの .npmrc、user は ~/.npmrc に書きます。 効いている設定は npm config list で確認します。npm doctor は接続・権限・版を点検し、今回は Checking npm version で Use npm v12.1.0 と最新版を案内しました。

link と workspaces：ローカルのパッケージを使う

ライブラリのフォルダで npm link、使う側で npm link mylib とすると、node_modules/mylib -> ../../mylib のシンボリックリンクができ、公開せずに変更を試せます。同じリポジトリ内で複数パッケージを管理するなら workspaces が便利です。

$ npm init -y && npm init -y -w packages/utils
$ npm init -y -w packages/app
$ npm i utils -w app
$ npm run start -w app
5
$ npm ls
+-- app@1.0.0 -> ./packages/app
`-- utils@1.0.0 -> ./packages/utils

-w で対象を指定し、npm i はルートで1回実行します。 ルートには "workspaces" が自動で追記され、各パッケージは node_modules にリンクされます。

package.json の書き方：完成形とフィールド解説

ESM（import）とCommonJS（require）両対応で、CLIも持つ完成形です。 別プロジェクトから import・require・npx で呼び出して確認しました。

{
  "name": "@example/task-utils",
  "version": "1.0.0",
  "description": "タスク管理用の小さなユーティリティ",
  "type": "module",
  "main": "./dist/index.cjs",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "bin": { "task-utils": "./bin/cli.js" },
  "files": ["dist", "bin"],
  "scripts": {
    "start": "node bin/cli.js",
    "test": "node --test"
  },
  "engines": { "node": ">=22" },
  "license": "MIT"
}

ESM: { id: 1, done: true }
CJS: { id: 2, done: true }
$ npx task-utils
{ id: 1, title: '備品を発注', done: true }
$ node -e 'require("@example/task-utils/dist/internal.js")'
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './dist/internal.js' is not defined by "exports" in .../package.json

engines は既定では警告だけで、>=30 を要求するパッケージを入れると npm warn EBADENGINE Unsupported engine と required: { node: '>=30' }、current: { node: 'v22.22.2', npm: '10.9.7' } が表示されて処理は続きます。止めたい場合は --engine-strict で npm error code EBADENGINE にできます。

overrides は依存の依存を指定した版に置き換えます。 chalk@4 が使う color-name に対し npm pkg set overrides.color-name=1.1.3 && npm i を実行すると、npm ls color-name に color-name@1.1.3 overridden と表示されました。

npm 12の変更点（2026年7月リリース）

npm 12の最大の変更は、依存パッケージの preinstall・install・postinstall スクリプトが既定で実行されなくなったことです。 サプライチェーン攻撃（依存パッケージ経由の攻撃）への備えです。npm 12.1.0で postinstall を持つ esbuild を入れた結果です。

$ npm i esbuild
added 2 packages, and audited 3 packages in 2s
found 0 vulnerabilities
npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts:
npm warn install-scripts   esbuild@0.28.2 (postinstall: node install.js)
npm warn install-scripts
npm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.
$ npm install-scripts approve esbuild
Approved esbuild:
  added esbuild@0.28.2
$ grep -A2 allowScripts package.json
  "allowScripts": {
    "esbuild@0.28.2": true
$ npm rebuild esbuild
rebuilt dependencies successfully

確認したパッケージだけを approve し、allowScripts をコミットします。 グローバルや npx では --allow-scripts=名前 を使います。主な変更点です（公式リリースノートより）。

よくあるエラーと直し方

ERESOLVE（peer依存の衝突） は、react@19 と react@17 用の react-dom@17 を同時に入れて再現しました。

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error Found: react@19.3.0
npm error Could not resolve dependency:
npm error peer react@"17.0.2" from react-dom@17.0.2
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps

npm view react-dom@17 peerDependencies で要求を確認し、npm i react@19 react-dom@19 と版をそろえると解消しました。 --legacy-peer-deps はpeerの確認を省く一時的な手段です。

EACCES（権限不足） は、書き込み権限のないフォルダに npm i -g して Error: EACCES: permission denied, mkdir を再現しました。npm公式は、sudo ではなくnvmなどでNode.jsを入れ直すか、npm config set prefix ~/.npm-global とし PATH に ~/.npm-global/bin を追加する方法を案内しています。

pnpm・yarn・bun との対応表

lockファイルの形式はツールごとに異なるため、1つのプロジェクトでは1つにそろえ、packageManager で明示します。

よくある質問

Q. npm install と npm ci はどちらを使えばよいですか？ A. 開発中の追加・更新は npm install、CI・本番ビルド・クローン直後は npm ci です。

Q. package-lock.jsonはGitに入れますか？ A. 入れます。 全員が同じ版を再現でき、npm ci が使えます。

Q. npm 12にするとインストールが失敗しますか？ A. インストールは完了しますが、依存の postinstall などが実行されません。 警告に出たパッケージを確認し、npm install-scripts approve 名前 で許可して npm rebuild します。

まとめ

• 日常の操作は npm i・npm ci・npm run・npx の4つ。確認は outdated・ls・why
• ^ はマイナーまで、~ はパッチまで。0.x系の ^ はマイナーを固定
• lockはコミットし、CIでは npm ci。不一致は EUSAGE で止まる
• package.jsonは type と exports で入口を決める。書いていないパスは読めない
• engines は既定で警告のみ、overrides で依存の依存を差し替え
• npm 12は依存のインストールスクリプトが既定で止まる。npm install-scripts approve で許可
• ERESOLVEは版をそろえる、EACCESは sudo ではなく置き場所を見直す

株式会社RJCでは、開発環境のツールの変化を実際に試して確かめ、その結果をプロジェクトの中で仲間と共有しています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。