できない.dev

esbuild「Could not resolve」の原因と直し方

esbuild の Could not resolve は、バンドル中に import 先が見つからないと出る。
パッケージを入れるか、Node 向けなら --platform=node を付ければ直る。
エイリアスは tsconfig の paths か --alias で教える。

公開: 更新:

症状できない · exit 1
npx esbuild src/app.js --bundle --outfile=out.js
…
✘ [ERROR] Could not resolve "dayjs"
    src/app.js:1:18:
      1 │ import dayjs from "dayjs";
解決後できた · exit 0
npx esbuild src/app.js --bundle --outfile=out.js
  out.js  14.4kb

⚡ Done in 2ms

2026-11-05 に node:22-bookworm-slim（esbuild 0.28.2 / Node.js 22.23.4） で実際に打って取った出力。検証環境の詳細

要約

--bundle を付けて esbuild を実行すると、import 先が見つからないファイルの位置を示して止まる。
esbuild 0.28.2 では次の表示になり、終了コードは 1 だった。

✘ [ERROR] Could not resolve "dayjs"
 
    src/app.js:2:18:
      2 │ import dayjs from "dayjs";
        ╵                   ~~~~~~~
 
  You can mark the path "dayjs" as external to exclude it from the bundle, which will remove this error and leave the unresolved path in the bundle.

Could not resolve は、import に書いた名前やパスを、esbuild がファイルに結び付けられなかったことを示す。
バンドルするときだけ解決するので、--bundle を付けない変換では同じ import でも出ない。

実行例

dayjs の未インストール、fs の既定 platform、@/lib/x のエイリアス、--resolve-extensions=.js の 4 通りで Could not resolve が出て、いずれも終了コードは 1 だった。npm install dayjs、--platform=node、tsconfig.json の paths を足すと、それぞれ終了コード 0 でバンドルできた。

$ npx esbuild --version
0.28.2
$ npx esbuild src/app.js --bundle --outfile=out.js
✘ [ERROR] Could not resolve "dayjs"
 
    src/app.js:1:18:
      1 │ import dayjs from "dayjs";
        ╵                   ~~~~~~~
 
  You can mark the path "dayjs" as external to exclude it from the bundle, which will remove this error and leave the unresolved path in the bundle.
 
1 error
$ echo $?
1
$ npx esbuild src/server.js --bundle --outfile=dist/server.js
✘ [ERROR] Could not resolve "fs"
 
    src/server.js:1:15:
      1 │ import fs from "fs";
        ╵                ~~~~
 
  The package "fs" wasn't found on the file system but is built into node. Are you trying to bundle for node? You can use "--platform=node" to do that, which will remove this error.
 
1 error
$ echo $?
1
$ npx esbuild src/alias.js --bundle --outfile=dist/alias.js
✘ [ERROR] Could not resolve "@/lib/x"
 
    src/alias.js:1:18:
      1 │ import { x } from "@/lib/x";
        ╵                   ~~~~~~~~~
 
  You can mark the path "@/lib/x" as external to exclude it from the bundle, which will remove this error and leave the unresolved path in the bundle.
 
1 error
$ echo $?
1
$ npx esbuild src/ext.js --bundle --resolve-extensions=.js --outfile=dist/ext.js
✘ [ERROR] Could not resolve "./lib/t"
 
    src/ext.js:1:18:
      1 │ import { t } from "./lib/t";
        ╵                   ~~~~~~~~~
 
1 error
$ echo $?
1
$ npm install dayjs
added 1 package, and audited 4 packages in 558ms
 
found 0 vulnerabilities
$ npx esbuild src/app.js --bundle --outfile=out.js
  out.js  14.4kb
 
⚡ Done in 2ms
$ echo $?
0
$ node out.js
2026/01/01
$ npx esbuild src/app.js --bundle --external:dayjs --outfile=out.js
  out.js  1.7kb
 
⚡ Done in 2ms
$ npx esbuild src/server.js --bundle --platform=node --outfile=dist/server.js
  dist/server.js  1.2kb
 
⚡ Done in 1ms
$ echo $?
0
$ cat tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}
$ npx esbuild src/alias.js --bundle --outfile=dist/alias.js
  dist/alias.js  84b 
 
⚡ Done in 1ms
$ echo $?
0

— 2026-11-05 時点の出力

検証環境Node.js 22.23.4 / npm 10.9.9 / esbuild 0.28.2 / 2026-11-05 検証
検証日
実行環境
node:22-bookworm-slim Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 22.23.4
  • npm 10.9.9
  • esbuild 0.28.2

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 依存を入れるか、バンドルから外す

npm install dayjs
npx esbuild src/app.js --bundle --outfile=out.js

実行時に別の仕組みで読み込むなら、外部扱いにする。--packages=external はすべてのパッケージを外す。

npx esbuild src/app.js --bundle --external:dayjs --outfile=out.js

外したパッケージは、バンドルを動かす環境に入っている必要がある。

2. Node.js で動かすなら platform を指定する

npx esbuild src/server.js --bundle --platform=node --outfile=dist/server.js

--platform=node では組み込みモジュールが自動で外部扱いになり、fs の import が通った。
ブラウザで動かすコードなら、Node.js 専用の import 自体を取り除く。

3. エイリアスを教える

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

tsconfig.json に上の paths を置くと、@/lib/x が src/lib/x.js に解決された。
設定ファイルを使わないなら --alias:@=./src を渡しても通る。

4. パスと拡張子を実ファイルに合わせる

大文字小文字だけが違う場合、esbuild 0.28.2 は Could not resolve ではなく different-path-case の警告を出した。
Linux ではその後 Cannot read file で止まったので、import の綴りを実ファイル名に合わせる。

よくある原因

  1. パッケージを入れていない。dayjs を npm install する前に上の表示になり、入れた後は同じコマンドが通った。
  2. Node.js の組み込みモジュールをブラウザ向けにバンドルしている。
    esbuild の既定の platform は browser なので、import fs from "fs" は Could not resolve "fs" になる。
    このときは --platform=node を使うよう案内が出る。
  3. パスエイリアスの設定が esbuild に届いていない。
    esbuild はバンドル時に tsconfig.json と jsconfig.json の paths を読む。
    どちらにも無いと Could not resolve "@/lib/x" になった。
  4. 相対パスか拡張子が合っていない。
    拡張子を省いた import は .tsx,.ts,.jsx,.js,.css,.json の順に探す。--resolve-extensions=.js に絞ると、./lib/t（実体は t.ts）が解決できなかった。
#esbuild #resolve #import #external #platform