Node.jsのERR_MODULE_NOT_FOUNDの直し方

​​Node.js​ES Modules,JavaScript,トラブルシュート

Node.js でスクリプトを実行したとき、ターミナルに Error [ERR_MODULE_NOT_FOUND]: Cannot find module と出て止まるのは、import で指定したファイルが見つからないときです(公式のエラー一覧にある ERR_MODULE_NOT_FOUND の説明)。ES モジュール("type": "module" のプロジェクトや .mjs のファイル)では、import './greet' のように拡張子 .js を省くと、ファイルがあってもこのエラーになります。import './greet.js' と拡張子まで書くと、エラーは消えます。

require で書いていたコードを import に書き換えたとき、拡張子を足し忘れると出ます。私は検証環境でエラーを起こし、メッセージの全文と、直すと消えることを確かめました。

補足

検証環境は Ubuntu 24.04 です。主に Node.js 24.22.1(npm 11.19.1)で試し、Node.js 22.23.4 でも同じファイルを実行しました。Windows と macOS、TypeScript のファイル(.ts)を直接実行する場合、webpack や Vite などのツールの中で出るエラーは試していません。

エラーの全文

検証環境(Ubuntu 24.04、Node.js 24.22.1)で、次の3つのファイルを用意しました。package.json に "type": "module" があるので、.js のファイルは ES モジュールとして読まれます。

json
{
  "name": "app",
  "version": "1.0.0",
  "type": "module"
}

src/greet.js は、あいさつの文字列を返す関数を export するだけのファイルです。

js
export function greet(name) {
  return `hello, ${name}`;
}

src/index.js で、この関数を拡張子を省いて import します。

js
import { greet } from './greet';

console.log(greet('neko'));

node src/index.js を実行すると、次のように出て止まりました(終了コードは1。パスは例示用の値に置き換えています)。

text
$ node src/index.js
node:internal/modules/esm/resolve:272
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/app/src/greet' imported from /path/to/app/src/index.js
    at finalizeResolution (node:internal/modules/esm/resolve:272:11)
    at moduleResolve (node:internal/modules/esm/resolve:879:10)
    at defaultResolve (node:internal/modules/esm/resolve:1006:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:705:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:725:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:763:56)
    at #resolve (node:internal/modules/esm/loader:687:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:607:35)
    at ModuleJob.syncLink (node:internal/modules/esm/module_job:276:33)
    at ModuleJob.link (node:internal/modules/esm/module_job:381:17) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///path/to/app/src/greet'
}

Node.js v24.22.1

Cannot find module '…/src/greet' imported from …/src/index.js は、「index.js から読もうとした …/src/greet というモジュールが見つからない」という意味です。見つからなかった名前が greet で終わっていて、.js が付いていません。Node.js は import に書かれたとおりの名前でファイルを探し、.js を自分で補わないので、greet.js があっても見つかりません。

Node.js 22.23.4 でも、Error [ERR_MODULE_NOT_FOUND]: Cannot find module … の行は同じでした(最初の行に出る resolve の行番号と、スタックの行番号・関数名は少し違います)。

拡張子 .js を付けるとエラーが消える

import の行に .js を足します。

js
import { greet } from './greet.js';

console.log(greet('neko'));
text
$ node src/index.js
hello, neko

エラーは出ず、関数の戻り値が表示されました。Node.js 22.23.4 でも同じでした。

公式ドキュメントの「拡張子は省略できない」という説明には、import で相対パスや絶対パスを指定するときは拡張子を書かなければならない、とあります。フォルダーの中の index.js を読むときも、'./startup/index.js' のようにファイル名まで書く必要があります。ブラウザーで import を使うときと同じ動きだ、とも書かれています。

ポイント

このエラーは、ファイル名のつづりを間違えたときも同じ文面で出ます。'./gret.js' と書いて試すと、Cannot find module '/path/to/app/src/gret.js' と出ました。メッセージに出ているパスを見て、拡張子がないのか、つづりや階層が違うのかを確かめます。

require では拡張子を省いても動く理由

require を使う CommonJS のコードでは、require('./greet') と書いても動きます。package.json を "type": "commonjs" にした別のフォルダーで、exports.greet = … と書いた greet.js を、次の index.js から読みました。

js
const { greet } = require('./greet');

console.log(greet('neko'));
text
$ node index.js
hello, neko

require がファイルを探す手順では、書かれた名前のファイルがなければ、.js、.json、.node を順に付けて探します。ES モジュールの import には、この補う仕組みがありません。CommonJS から ES モジュールへ書き換えるときは、require('./greet') を import … from './greet.js' のように、拡張子を足して書き換えます。

古いフラグでは直らない

以前の Node.js では、--experimental-specifier-resolution=node という実験的なフラグを付けて実行すると、import でも拡張子が補われました(Node.js 18 のドキュメントにある、このフラグの説明)。このフラグは、Node.js 19.0.0 の変更履歴にあるとおり、19.0.0 で取り除かれています。

Node.js 24.22.1 でこのフラグを付けて node --experimental-specifier-resolution=node src/index.js を実行すると、フラグについてのエラーや警告は出ず、拡張子を省いたときと同じ ERR_MODULE_NOT_FOUND で止まりました。古い記事に書かれたこのフラグを付けても、今の Node.js では直りません。

拡張子を書かずに済ませたいときは package.json の imports

import のたびに .js を書きたくないなら、package.json の "imports" フィールド(プロジェクトの中だけで使う、# で始まる名前の対応表)を使う方法があります。次のように、#src/ で始まる名前を ./src/ の .js のファイルに対応させました。

json
{
  "name": "app",
  "version": "1.0.0",
  "type": "module",
  "imports": {
    "#src/*": "./src/*.js"
  }
}

src/index-imports.js では、#src/greet と拡張子なしで書きます。

js
import { greet } from '#src/greet';

console.log(greet('neko'));
text
$ node src/index-imports.js
hello, neko

Node.js 24.22.1 と 22.23.4 のどちらでも、エラーは出ずに動きました。* の部分は文字列としてそのまま置き換えられるので、#src/greet は ./src/greet.js になります(公式ドキュメントの、* を使った対応の説明)。ただし、相対パスの './greet' は対象にならず、これまでどおりエラーになります。ふだんの相対パスの import には、.js を付けるのがいちばん手早い直し方です。

​Posted by 86