TypeScript モジュールが見つからないエラーを修正: ts(2307) インポートの問題

エラーの概要

リファクタリングの途中、またはブランチをプルした直後に、IDEが一面真っ赤になることがあります：

Cannot find module './Component' or its corresponding type declarations. ts(2307)

ビルドが失敗し、何もコンパイルできなくなります。ファイルを確認すると——存在しています。インポートを確認すると——正しく見えます。一体何が起きているのでしょうか？

TypeScriptがインポートしようとしているモジュールを解決できない状態です。ファイルがディスク上に存在していても、TypeScriptが「認識」できないか、型が完全に欠落しているかのどちらかです。原因を一つひとつ排除していきましょう——少なくとも5つの異なるシナリオが考えられます。

素早い診断

何かを触る前に、どのシナリオに該当するかを特定してください：

ファイルは存在するのにTypeScriptが警告を出す → パスまたは拡張子の問題
npmパッケージをインポートしている → @typesパッケージが不足している
TSファイル以外（CSS、SVG、JSON）をインポートしている → モジュール宣言が不足している
パッケージをインストールしたばかり → tsconfigまたはnode_modulesの問題
モノレポまたはパスエイリアスを使っている → tsconfigのpaths設定ミス

修正1: ファイルパスと拡張子を確認する

深夜2時によくやる凡ミス：パスの間違いです。TypeScriptはLinuxとmacOSではアルファベットの大文字小文字を区別します。Windowsはより寛容なため、ローカルでは動くのにCIで壊れるという、大文字小文字のバグが特に気づきにくくなります。

// 誤り — 実際のファイル名は 'Button.tsx'
import Button from './button';

// 正しい
import Button from './Button';

ディレクトリのインデックスが抜けていないかも確認してください：

// ComponentがインデックスファイルのあるディレクトリFの場合
import Component from './Component';       // ./Component/index.tsx に解決される
import Component from './Component/index'; // 明示的な指定

.tsxファイルの場合、tsconfigにJSXサポートが設定されていることを確認してください：

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

修正2: npmモジュールの@typesパッケージが不足している

lodashやexpressなどのサードパーティパッケージは、JavaScriptのみを同梱していることが多く、型が含まれていません。TypeScriptはそれらをどう扱えばよいかわかりません。

Cannot find module 'lodash' or its corresponding type declarations. ts(2307)

対応する@typesパッケージをインストールしてください：

npm install --save-dev @types/lodash
# または
yarn add -D @types/lodash
# または
pnpm add -D @types/lodash

インストール後、VS CodeでTypeScriptサーバーを再起動してください：Ctrl+Shift+P → TypeScript: Restart TS Server。このステップを省略したことが、「まだ直らない」という報告の驚くほど多くの原因になっています。

インストール前にtypesパッケージが存在するか確認するには：

npm search @types/your-package-name

修正3: モジュール宣言を自分で記述する

@typesパッケージが存在しない場合は、自分で宣言を書く必要があります。src/declarations.d.ts（またはsrc/global.d.ts）を作成し、以下を追加してください：

// 最小限 — 「これは存在する」とTSに伝える
declare module 'some-untyped-package';

// より良い — 型の形状がわかれば追加する
declare module 'some-untyped-package' {
  export function doSomething(input: string): void;
  export default function main(): void;
}

静的アセットにも宣言が必要です。SVG、CSSモジュール、画像はすべて明示的なモジュール宣言が必要であり、そうしないとTypeScriptがインポートを拒否します：

// src/declarations.d.ts
declare module '*.svg' {
  const content: string;
  export default content;
}

declare module '*.css' {
  const styles: Record;
  export default styles;
}

declare module '*.png' {
  const src: string;
  export default src;
}

修正4: tsconfig.jsonのモジュール解決設定を修正する

解決戦略が間違っていると、TypeScriptが誤った場所を探してしまいます。ESMへの移行やバンドラーの切り替えを行うプロジェクトで多く見られる問題です。

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true
  }
}

どのmoduleResolutionを選ぶべきか：

"bundler" — Viteまたはwebpackプロジェクト向け（TypeScript 5.0以降）
"node16"または"nodenext" — ネイティブESMを使うNode.js向け
"node" — 従来のCommonJS、古いプロジェクト向け

見落としがちな設定が他にもあります：esModuleInterop: trueはCommonJSパッケージからのデフォルトインポートに必要です。resolveJsonModule: trueはimport data from './data.json'のような記述に必要です。また、ソースファイルがincludeまたはrootDirのパス内に実際に含まれているかも確認してください。

修正5: パスエイリアスが解決されない

@/components/Buttonのようなパスエイリアスは便利ですが、気づかないうちに壊れることがあります。注意点として、tsconfigのpathsは型チェックにしか影響しません。別途設定しない限り、バンドラーはそれらを認識しません。

手順1 — tsconfig.jsonに追加する：

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

手順2 — バンドラーにも同じ設定を反映させる。Viteの場合：

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

webpackの場合：

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

修正6: node_modulesを削除して再インストールする

インストールの失敗やロックファイルの競合により、node_modulesが中途半端な壊れた状態になることがあります。パッケージはインストール済みに見えても、ファイルが破損していたり不整合が生じていたりします。これは核オプションとも言える手段ですが、他の方法で解決できない場合の約80%で効果があります。

rm -rf node_modules
rm package-lock.json  # または yarn.lock / pnpm-lock.yaml
npm install

その後、TSサーバーを再起動してください。

修正7: declarations.d.tsがtsconfigに含まれているか確認する

.d.tsファイルを作成したのにTypeScriptが無視している場合は、そのファイルがtsconfigのincludeでカバーされているディレクトリ内にあるか、明示的に列挙されている必要があります：

{
  "include": [
    "src/**/*",
    "src/declarations.d.ts"
  ]
}

最もシンプルな対処法：.d.tsファイルをsrc/内のどこかに置くだけで、tsconfigが自動的に認識します。

修正の確認

TypeScriptコンパイラをチェック専用モードで実行します——出力ファイルは生成せず、型エラーのみを確認します：

npx tsc --noEmit

# 何も出力されなければエラーなし

VS Codeでは、TSサーバーを再起動すると赤い波線が消えるはずです。tsc --noEmitがクリーンに通過しているのにエラーが表示され続ける場合は、TypeScriptの実際のエラーではなくVS Codeのキャッシュの問題です。ワークスペースを閉じて再度開いてください。

それでも解決しない場合は？解決過程をトレースする

それでもダメな場合は、詳細な解決ログを有効にしてください。TypeScriptが確認したすべてのパスと、どこで諦めたかが出力されます：

npx tsc --noEmit --traceResolution 2>&1 | grep -A5 "Module name '.*Component'"

出力は多くなりますが、ts(2307)の決定的なデバッガーです。Loading module as file/folderやFile '.../Component.ts' does not existといった行が確認でき、TypeScriptがどのディレクトリを検索しているか、なぜ見つからないのかが正確にわかります。