ERR_MODULE_NOT_FOUND エラーの解決方法

問題

Node.jsプロジェクトでESモジュールを使用している際に、以下のエラーが発生することがあります：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/module'

このエラーは、モジュールのインポート時にファイル拡張子の指定が正しくない場合や、モジュール解決の設定が適切でない場合に発生します。

原因

Node.jsのESモジュールシステムでは、CommonJSとは異なり、ファイル拡張子の明示的な指定が要求されます。また、package.jsonで"type": "module"を指定している場合、モジュール解決の挙動が変わります。

解決方法

1. ファイル拡張子を明示する

ESモジュールでは、インポート時にファイル拡張子（.js）を必ず含める必要があります：

// ❌ 間違い
import { urls } from './helpers';

// ✅ 正しい
import { urls } from './helpers.js';

2. package.jsonの設定を確認する

package.jsonに"type": "module"が設定されていることを確認してください：

{
  "name": "your-project",
  "type": "module",
  // ...その他の設定
}

3. 実験的なフラグを使用する（一時的な解決策）

Node.jsの実行時に実験的なフラグを使用して、従来のモジュール解決方法を有効にできます：

node --experimental-specifier-resolution=node index.js

または、package.jsonのスクリプトで設定：

{
  "scripts": {
    "start": "NODE_OPTIONS='--experimental-specifier-resolution=node' node index.js"
  }
}

WARNING

実験的なフラグは将来のバージョンで削除される可能性があるため、本番環境では推奨されません。

4. モジュールパスマッピングを使用する

package.jsonでサブパスインポートを設定することで、クリーンなインポートパスを使用できます：

{
  "imports": {
    "#helpers": "./helpers.js"
  }
}

import { urls } from "#helpers";

5. node_modulesの再インストール

場合によっては、依存関係の問題が原因でこのエラーが発生することがあります：

rm -rf node_modules
npm install

6. TypeScriptを使用している場合の設定

TypeScriptプロジェクトでは、tsconfig.jsonを適切に設定する必要があります：

{
  "compilerOptions": {
    "lib": ["es2020"],
    "module": "ES2022",
    "moduleResolution": "node",
    "target": "es2022"
  }
}

よくある間違いと修正例

間違い	修正例
import { urls } from './helpers';	import { urls } from './helpers.js';
import { connect } from './dir/file';	import { connect } from './dir/file.js';
パスに./を忘れる	相対パスには必ず./を付ける

まとめ

ERR_MODULE_NOT_FOUNDエラーを解決するための主要な方法は：

1. ファイル拡張子を明示する - ESモジュールでは必須
2. package.jsonの設定を確認する - "type": "module"の有無
3. 相対パスを正しく記述する - ./で始める

これらの対策により、モジュール解決の問題の大部分は解決できます。実験的なフラグに依存するのではなく、標準的な方法で問題を解決することをお勧めします。

TIP

開発時にはVS Codeの「Path Intellisense」拡張機能を使用すると、パスの入力補完が効いてミスを防げます。