Node.jsを用いた開発において、昨日まで動いていたコードが突然動かなくなったり、新しいプロジェクトを立ち上げようとしてエラーの壁にぶつかったりすることは、エンジニアにとって日常的な課題です。

Node.jsは進化が速く、2026年現在では多くの便利な機能が標準搭載されていますが、その一方でバージョン間の互換性やモジュールシステムの仕様変更に起因するトラブルも少なくありません。

本記事では、Node.jsが動かない原因を論理的に切り分け、最短ルートで解決するためのトラブルシューティング手順を網羅的に解説します。

目次 [ close ]
  1. Node.jsが起動しない場合の基本チェックリスト
    1. パス（PATH）の設定とインストールの確認
    2. バージョン管理ツールの活用
  2. 実行エラーの分類と解決策
    1. 構文エラー（SyntaxError）への対処
    2. 実行時エラー（Runtime Error）の追跡
  3. 依存ライブラリ（node_modules）のトラブル
    1. node_modulesのクリーンアップ
    2. Corepackとパッケージマネージャの不一致
  4. モジュールシステム（ESM vs CommonJS）の混在
    1. type: moduleの設定
  5. ネットワーク・パーミッション・環境変数の問題
    1. EADDRINUSE（ポート重複エラー）
    2. パーミッションエラー（EACCES）
    3. 環境変数の読み込みエラー
  6. 最新のNode.jsデバッグツールの活用
    1. --watch フラグによる効率化
    2. Chrome DevToolsとの連携
  7. OS固有の問題と対策
    1. ファイルパスの区切り文字
    2. 改行コードの問題
  8. メモリ不足（Heap out of memory）
  9. まとめ

Node.jsが起動しない場合の基本チェックリスト

Node.jsがそもそも起動しない、あるいは「command not found」と表示される場合は、実行環境そのものに問題がある可能性が高いと言えます。

まずは以下の基本的なポイントを確認しましょう。

パス（PATH）の設定とインストールの確認

Node.jsをインストールしたはずなのにコマンドが認識されない場合、実行バイナリへのパスが通っていないことが考えられます。

ターミナル（またはコマンドプロンプト）を開き、以下のコマンドを入力して反応を確認してください。

Shell
# Node.jsのバージョンを確認
node -v

もしここで「command not found: node」といったメッセージが表示される場合は、パスの設定が正しく行われていないか、インストール自体が失敗しています。

バージョン管理ツールの活用

2026年現在の開発現場では、Node.jsを直接インストールするのではなく、Voltaやnvm（Node Version Manager）、asdfなどのバージョン管理ツールを使用するのが一般的です。

プロジェクトごとに推奨されるNode.jsのバージョンが異なるため、ツールが正しく切り替わっているかを確認する必要があります。

Shell
# Voltaを使用している場合の例
volta list node

特定のプロジェクトでだけ動かない場合は、プロジェクトのルートディレクトリにある package.json の engines フィールドや、 .node-version ファイルの設定と、現在使用しているバージョンが一致しているかを確認してください。

実行エラーの分類と解決策

Node.jsは起動するものの、プログラムの実行中にエラーが発生して停止する場合、その原因は「構文エラー」「ランタイムエラー」「依存関係のエラー」の3つに大きく分類できます。

構文エラー（SyntaxError）への対処

SyntaxError は、プログラムがJavaScriptの文法に従っていない場合に発生します。

最近のNode.jsでは、新しい構文（Optional Chainingの高度な利用や、新しいTC39プロポーザルの機能など）が次々と導入されています。

JavaScript
// 構文エラーの例：古いNode.jsで新しい構文を使おうとした場合
const data = user?.profile?.settings ?? 'default';
console.log(data);

もし古いNode.js環境で最新の構文を使用しようとすると、パースに失敗して実行すらされません。

この場合、Node.jsのバージョンをプロジェクトの要求に合わせることが解決の近道です。

実行時エラー（Runtime Error）の追跡

コード自体は読み込まれるものの、実行中にクラッシュする場合は、スタックトレースを読み解く必要があります。

代表的なエラーとして以下のものが挙げられます。

エラー名主な原因対策
ReferenceError定義されていない変数を参照した変数名のタイポやスコープを確認する
TypeError関数ではないものを呼び出した、あるいはnull/undefinedのプロパティを参照したオプショナルチェイニング等で安全にアクセスする
Error [ERR_MODULE_NOT_FOUND]指定したモジュールが見つからないインポートパスが正しいか、拡張子が必要か確認する

特に、2026年のNode.js環境では ESモジュール（ESM） が標準となっています。

import 時にファイルの拡張子（.jsなど）を省略するとエラーになるケースが多いため、注意が必要です。

依存ライブラリ（node_modules）のトラブル

「昨日まで動いていたのに、今日 npm install したら動かなくなった」というケースは非常に多いトラブルです。

これは依存ライブラリのアップデートによって、破壊的変更（Breaking Changes）が導入されたことが原因である可能性があります。

node_modulesのクリーンアップ

依存関係が複雑に絡み合い、どうしようもなくなった場合は、一度環境をリセットするのが最も確実です。

以下の手順で依存関係を再構築してください。

Shell
# node_modulesディレクトリとロックファイルを削除
# Windows (PowerShell) の場合
Remove-Item -Recurse -Force node_modules, package-lock.json

# macOS / Linux の場合
rm -rf node_modules package-lock.json

# 再インストールを実行
npm install

これにより、package.json に基づいたクリーンな状態のライブラリが再構築されます。

Corepackとパッケージマネージャの不一致

2026年現在、Node.jsには Corepack が標準的に組み込まれています。

これは npm, yarn, pnpm といったパッケージマネージャのバージョンをプロジェクトごとに自動で管理する仕組みです。

もしプロジェクトで pnpm を使うように設定されているのに npm で操作しようとすると、不整合が発生して動かなくなることがあります。

Shell
# Corepackを有効化する
corepack enable

# プロジェクト指定のパッケージマネージャを強制する
pnpm install

プロジェクトごとに指定されたパッケージマネージャを遵守することが、依存関係トラブルを防ぐ鍵となります。

モジュールシステム（ESM vs CommonJS）の混在

Node.jsにおける最大の混乱の源は、依然として CommonJS（CJS） と ESモジュール（ESM） の混在にあります。

type: moduleの設定

package.json に "type": "module" が記述されている場合、そのプロジェクト内のすべての .js ファイルはESMとして扱われます。

この状態で require() を使用するとエラーになります。

JavaScript
// package.jsonで "type": "module" が指定されている場合
// 以下の書き方はエラーになる
const fs = require('fs'); 

// 正しい書き方
import fs from 'node:fs';

逆に、古いプロジェクトで import 構文を使いたい場合は、拡張子を .mjs にするか、 package.json を適切に設定する必要があります。

エラーメッセージに「ReferenceError: require is not defined」と表示された場合は、ほぼ確実にこのモジュールシステムの不一致が原因です。

ネットワーク・パーミッション・環境変数の問題

Node.jsアプリケーションが特定の外部リソースにアクセスできない、あるいは起動時に権限エラーが出る場合の対処法を解説します。

EADDRINUSE（ポート重複エラー）

サーバーを起動しようとして「Error: listen EADDRINUSE: address already in use :::3000」と表示される場合、指定したポート（この例では3000）が既に他のプロセスで使用されています。

Shell
# ポート3000を使用しているプロセスを特定して終了させる (macOS/Linux)
lsof -i :3000
kill -9 <PID>

以前実行したNode.jsのプロセスが正常に終了せず、バックグラウンドで残り続けている場合によく発生します。

パーミッションエラー（EACCES）

npm install -g を実行した際や、特定のディレクトリに書き込みを行おうとした際に発生します。

2026年のベストプラクティスとしては、sudo を使って npm コマンドを実行することは避けるべきです。

権限エラーが発生した場合は、前述のバージョン管理ツール（Volta等）を使用して、ユーザーディレクトリ内でNode.jsが完結するように設定することで解決します。

環境変数の読み込みエラー

Node.js 20.6.0以降、標準で .env ファイルを読み込む機能が搭載されています。

2026年現在、外部ライブラリ（dotenvなど）を使わずに環境変数を読み込むのが主流です。

Shell
# .envファイルを指定してNode.jsを実行
node --env-file=.env index.js

もし環境変数が undefined になる場合は、ファイルのパスが正しいか、あるいは実行時のフラグが漏れていないかを確認してください。

最新のNode.jsデバッグツールの活用

コードのどこで問題が起きているのか特定できない場合は、Node.jsに標準搭載されているデバッグ機能をフル活用しましょう。

–watch フラグによる効率化

開発中にコードを変更するたびに手動で再起動していると、エラーの特定に時間がかかります。

Node.jsには標準でウォッチモードが搭載されています。

Shell
# ファイル変更を検知して自動再起動
node --watch index.js

これにより、修正が即座に反映され、どの変更がエラーを引き起こしたのかを特定しやすくなります。

Chrome DevToolsとの連携

複雑なオブジェクトの中身や非同期処理のスタックトレースを追いたい場合は、インスペクタを使用します。

Shell
node --inspect-brk index.js

このコマンドを実行した後、ブラウザ（ChromeやEdge）で chrome://inspect を開くと、ブラウザのデバッガと同じUIでNode.jsのコードを1行ずつステップ実行できます。

変数の書き換えやメモリリークの調査にも非常に有効です。

OS固有の問題と対策

Node.js自体はクロスプラットフォームですが、OS固有の挙動によって「自分の環境では動くが、他の人の環境では動かない」という現象が発生します。

ファイルパスの区切り文字

Windowsはバックスラッシュ（\）、macOS/Linuxはフォワードスラッシュ（/）を使用します。

パスを文字列結合で作成していると、異なるOSで実行した際に「ファイルが見つからない」エラーが発生します。

JavaScript
import path from 'node:path';

// 悪い例：OS依存
// const myPath = __dirname + '\\config.json';

// 良い例：pathモジュールを使用
const myPath = path.join(process.cwd(), 'config', 'settings.json');

pathモジュールを常に使用するように徹底することで、OSに依存しない堅牢なコードになります。

改行コードの問題

Windows（CRLF）とmacOS/Linux（LF）では改行コードが異なります。

スクリプトファイル（.shなど）をNode.jsから呼び出す際、改行コードが原因で「ファイルが存在するのに実行できない」という不可解なエラーに陥ることがあります。

Gitの設定で autocrlf を適切に管理し、プロジェクト全体でLFに統一することを推奨します。

メモリ不足（Heap out of memory）

大規模なデータを処理している際や、ビルドツール（webpack, Viteなど）を実行している際に、「FATAL ERROR: Reached heap limit Allocation failed – JavaScript heap out of memory」というエラーで停止することがあります。

Node.jsのデフォルトのメモリ割り当て制限に達したことが原因です。

この場合、実行時のオプションでメモリ上限を拡張することで回避できます。

Shell
# メモリ上限を4GBに設定して実行
node --max-old-space-size=4096 index.js

ただし、これは根本的な解決ではなく、メモリリークが発生していないかを前述のデバッガで調査することが本質的な対策となります。

まとめ

Node.jsが動かない原因の多くは、環境の不整合、依存関係の衝突、あるいは新しい仕様への未対応に集約されます。

エラーが発生した際は、まず「どこまでが正常に動いているか」を切り分け、以下の順序で確認を行ってください。

  1. Node.jsのバージョンとパスが正しいか確認する
  2. node\_modules をクリーンにして再インストールする
  3. エラーメッセージから、ESM関連や構文ミスがないか特定する
  4. --inspect や --watch などの最新機能を活用して詳細な挙動を追跡する

Node.jsは2026年現在、以前よりもエラーハンドリングやデバッグ機能が強化されています。

エラーメッセージを無視せず、スタックトレースの最上部にある「自分の書いたコードの行数」を起点に調査を進めることで、ほとんどの問題は解決可能です。

一つひとつのエラーを丁寧に取り除いていくプロセスは、単なる修正作業ではなく、Node.jsの内部構造への理解を深める貴重な機会となります。

本記事のトラブルシューティング手順を参考に、安定した開発環境を構築してください。