テクノロジー · 実用ガイド
npmでEACCES（権限拒否）が出たら？sudo・chown・prefix変更の前に失敗パスを読む
キャッシュ、プロジェクト、グローバルprefix、コンテナでは所有者が違います。変更前に正確なパスを保存し、範囲を分類します。
EACCES は一つのファイルシステム操作が拒否されたことを示すだけで、npm 全体やキャッシュ、プロジェクト、グローバルprefixのすべてが壊れたという意味ではありません。
決め手は正確な `npm ERR! path`、syscall、実行アカウントです。所有権、権限、キャッシュ、prefix、ユーザーを変更する前に保存します。
本ガイドはユーザーキャッシュ、ローカルプロジェクト、グローバルprefix、コンテナ/CI の四つに分類し、読み取り専用の証拠カードを作ります。
同じエラーコードでも四つの権限範囲がある
`~/.npm` はユーザーキャッシュ、プロジェクト内の `node_modules` は作業ツリー、`npm config get prefix` 配下はグローバルインストールを示します。`/workspace`、`/app`、マウントや不自然な HOME はコンテナ、CI、リモート環境の不一致かもしれません。
各範囲の所有者と対処は別です。prefix変更で `/var/test/node_modules` は書き込み可能にならず、キャッシュの再帰変更で読み取り専用マウントは直りません。sudo は新しい root 所有ファイルを作る恐れがあります。
変更前に読み取り専用の証拠カードを作る
EACCES ブロック全体、code、syscall、path、cwd、Node/npm 版、元のコマンドを保存します。`npm config get cache`、`npm config get prefix`、`npm prefix`、`npm root -g`、アカウントと作業ディレクトリも記録します。
macOS/Linux では `ls -ld` や `namei -l`、コンテナでは UID/GID、HOME、マウント、Windows では `Get-Acl` を確認します。トークンや `.npmrc` の内容は共有しません。
キャッシュのパスなら所有権とランタイムを先に確認
失敗パスがキャッシュ配下なら、プロジェクト自体は正常かもしれません。キャッシュと親の所有者、UID、過去の sudo やコンテナ書き込みを比べます。`npm cache verify` は整合性確認で、キャッシュ削除は権限診断ではありません。
npm が表示する chown を無条件に実行しません。Termux の事例では root 所有という診断自体が環境に合いませんでした。実際の誤所有を確認してから HOME の所有者が限定的な修復を判断します。
プロジェクトのパスならプロジェクト境界を直す
`/var/test/node_modules`、リポジトリ、マウントされた workspace で失敗したら、現在のアカウントがローカルインストール先に書けません。prefix変更は無関係です。所有者、グループ、ACL、マウント方式、作成元を確認します。
`chmod -R 777`、`chmod a+w`、共有ツリーの無審査な再帰 chown は避けます。意図したアカウント/グループへ戻すか、その workspace の所有者としてビルドします。
グローバルprefixなら npm の正式な経路を使う
npm は Node のバージョン管理ツール、またはユーザー所有の prefix を推奨し、単発コマンドには `npx` も案内しています。
失敗パスが本当にグローバルprefix配下か確認します。管理端末のシステム Node は管理者の方針かもしれないため、迂回せず承認済み環境を依頼します。
コンテナとCIではUID、HOME、マウントを合わせる
コンテナではユーザー名より数値 UID/GID が重要です。ホストのバインドマウント、共有キャッシュ、以前の root ステップを双方で確認します。
永続策は UID の整合、ジョブ別キャッシュ、マウント方針の修正です。所有者の承認なしに一時コンテナからホストボリュームを再帰 chown しません。
最小の承認済み操作を選び、引き継ぐ
失敗パス、syscall、アカウント、cache、local/global prefix、プロジェクト所有者、環境種別を引き継ぎに残し、四分類を明示します。
予期しないパス、共有所有権の不一致、read-only マウント、管理ランタイム、不明なアカウント、権限拡大があれば停止します。強いアカウントで消すことではなく、意図したアカウントで意図した操作が成功することが解決です。
