できない.dev

TypeScript で tsconfig の paths エイリアスが実行時に解決されない

tsconfig の paths は実行時には効かず、tsconfig-paths などのローダか bundler の alias 設定を足せば直る。
tsc はコンパイル後の JS の import を書き換えないためである。

公開: 更新:

症状できない · exit 1
node dist/main.js
…
Error: Cannot find module '@/greet'
Require stack:
- /tmp/tmp.YIheaGIC6h/dist/main.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1207:15)
解決後できた · exit 0
node dist/main.js
Hello, world

2026-10-29 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

tsconfig.json の paths は tsc が型を解決するためだけのマッピング で、コンパイル後の JS は import "@/foo" のまま残る。
Node がそのパスを知らなければ実行時に Cannot find module になる。
実行系(ts-node / node / bundler)ごとに 同じ alias を別途設定する 必要がある。

実行例

node:20(Debian GNU/Linux 12)環境で上記の手順を動かすと、tsc 単体のコンパイルでは出力 JS の require("@/greet") がそのまま残った。
node dist/main.js は Cannot find module '@/greet'(終了コード 1)で失敗した。
続けて tsc-alias を適用すると同じ行が require("./greet.js") に書き換えられ、終了コード 0 で正常に終了した。

Version 5.9.3
$ npx tsc
$ echo $?
0
$ grep -n "require(" dist/main.js
3:const greet_1 = require("@/greet");
$ node dist/main.js
node:internal/modules/cjs/loader:1210
  throw err;
  ^
 
Error: Cannot find module '@/greet'
Require stack:
- /tmp/tmp.YIheaGIC6h/dist/main.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1207:15)
    at Module._load (node:internal/modules/cjs/loader:1038:27)
    at Module.require (node:internal/modules/cjs/loader:1289:19)
    at require (node:internal/modules/helpers:182:18)
    at Object.<anonymous> (/tmp/tmp.YIheaGIC6h/dist/main.js:3:17)
    at Module._compile (node:internal/modules/cjs/loader:1521:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1623:10)
    at Module.load (node:internal/modules/cjs/loader:1266:32)
    at Module._load (node:internal/modules/cjs/loader:1091:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/tmp/tmp.YIheaGIC6h/dist/main.js' ]
}
 
Node.js v20.20.2
$ echo $?
1
$ npx tsc-alias
$ grep -n "require(" dist/main.js
3:const greet_1 = require("./greet.js");
$ node dist/main.js
Hello, world
$ echo $?
0

— 2026-10-29 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-29 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

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

解決策

1. tsconfig 側の最低構成

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

値のパスは tsconfig.json のある場所からの相対で解決される(公式の paths の説明(新しいタブで開く))。

2. ts-node で実行する

npm install -D ts-node tsconfig-paths
node -r ts-node/register -r tsconfig-paths/register src/main.ts

tsconfig-paths/register が paths を読んで Node の解決経路に合流させる。
ts-node の代わりに tsx を使うなら前処理は要らず、npx tsx src/main.ts が paths をそのまま解決する。
ts-node 10.9.2 は TypeScript 7.0 では Cannot read properties of undefined (reading 'fileExists') で起動しないので、その場合も tsx を使う。

3. tsc 出力を実体パスに書き換える

npm install -D tsc-alias
npx tsc && npx tsc-alias

ビルド成果物の import "@/foo" を相対パスに置換する。
production で配布するときは、こちらを使う。

4. bundler の alias を合わせる

// vite.config.ts
import { defineConfig } from "vite";
import path from "node:path";
 
export default defineConfig({
  resolve: {
    alias: { "@": path.resolve(__dirname, "src") }
  }
});

webpack も同様に tsconfig の paths と一致するマッピング を定義する。
esbuild はバンドルするとき(--bundle)は tsconfig の paths をそのまま解決するので別の定義は要らないが、バンドルせずに変換だけする場合は import が書き換わらない。

よくある原因

  1. paths は型専用である。
    tsc 単体ではコンパイル時にパスを書き換えない(公式の明記(新しいタブで開く))。
  2. ts-node でローダを指定していない。
    そのままでは paths を解釈できず、@/foo を node_modules で探して失敗する。
  3. bundler 側で設定していない。
    webpack / Vite はそれぞれ独自の alias を持ち、tsconfig の paths を自動では採用しない(esbuild はバンドル時に限り tsconfig の paths を解決する)。
  4. paths の値が相対パスになっていない。
    baseUrl を書かない構成で "@/*": ["*"] のように ./ の無い値を書くと、TS5090 で止まる。
    baseUrl は TypeScript 6.0 で非推奨(TS5101)になり、7.0 で削除された(TS5102)。