TypeScript 「Cannot find module」エラーの原因と解決方法【モジュール解決の落とし穴と実践的な対処法】

Error: Cannot find module ‘module-name’ or its corresponding type declarations. とは

TypeScript開発において、「Cannot find module」エラーは頻繁に遭遇するモジュール解決に関する問題です。このエラーは、指定されたモジュールが見つからないことを示しており、原因はファイルパスの誤り、`tsconfig.json` の設定不足、あるいは外部ライブラリの型定義ファイルの不足など多岐にわたります。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: パターン1: 相対パスの指定ミス

```typescript
// components/Button.ts
export class Button { /* ... */ }

// pages/index.ts
// 誤った相対パス指定
import { Button } from '../component/Button'; // 'component' ではなく 'components' が正しい

new Button();
```

モジュールをインポートする際の相対パスが、実際のファイルシステム上の位置と一致していない場合に発生します。特に、ディレクトリ名のスペルミスや、階層の誤認識が原因となることが多いです。

```typescript
// components/Button.ts
export class Button { /* ... */ }

// pages/index.ts
// 正しい相対パス指定
import { Button } from '../components/Button'; // 'components' に修正

new Button();
```

パターン2: パターン2: パスエイリアスの設定不足または誤り

```typescript
// tsconfig.json にエイリアスの設定がない、または誤っている
// {
//   "compilerOptions": {
//     "baseUrl": ".",
//     "paths": {
//       "@utils/*": ["src/utils/*"]
//     }
//   }
// }

// src/utils/helpers.ts
export const greet = () => 'Hello';

// src/app.ts
// tsconfig.json に設定がないため解決できない
import { greet } from '@utils/helpers';

console.log(greet());
```

プロジェクト内で短いエイリアス（例: `@utils`）を使ってモジュールをインポートしようとしているが、`tsconfig.json`でそのエイリアスの解決ルールが定義されていないか、定義が間違っている場合に発生します。VS Codeなどのエディタがモジュールを見つけられず、型チェックも失敗します。

```typescript
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".", // プロジェクトルートを基準とする
    "paths": {
      "@utils/*": ["src/utils/*"] // '@utils' を 'src/utils' にマッピング
    }
  }
}

// src/utils/helpers.ts
export const greet = () => 'Hello';

// src/app.ts
// tsconfig.json の設定により解決される
import { greet } from '@utils/helpers';

console.log(greet());
```

パターン3: パターン3: 外部ライブラリの型定義ファイル不足

```typescript
// package.json に @types/lodash がインストールされていない状態
// npm install lodash

// src/app.ts
import _ from 'lodash'; // lodash はインストール済みだが、型定義がない

const arr = [1, 2, 3];
const shuffled = _.shuffle(arr);
console.log(shuffled);
```

JavaScriptで書かれた外部ライブラリを使用しているにも関わらず、そのライブラリに対応するTypeScriptの型定義ファイル（`.d.ts`ファイル）がインストールされていない場合に発生します。TypeScriptコンパイラは型情報なしでモジュールを認識できないため、エラーとなります。

```typescript
// package.json に @types/lodash をインストール
// npm install lodash @types/lodash --save-dev

// src/app.ts
import _ from 'lodash'; // 型定義がインストールされたため解決される

const arr = [1, 2, 3];
const shuffled = _.shuffle(arr);
console.log(shuffled);
```

根本原因の特定方法

エラーメッセージで指定されたモジュール名を正確に確認し、まずはそのファイルが実際に存在するか、パスが正しいかを{marker}ファイルシステム上で確認{/marker}します。次に、`tsconfig.json`の`baseUrl`と`paths`の設定が適切か、外部ライブラリの場合は対応する`@types/`パッケージが`package.json`の`devDependencies`に存在し、`npm install`または`yarn install`が実行されているかを確認します。VS Codeを使っている場合は、ワークスペースのリロードやTypeScriptサーバーの再起動も試してみてください。

TypeScriptコンパイラがどのようにモジュールを解決しているかを詳細に確認するために、`tsconfig.json`の`traceResolution`オプションを`true`に設定してコンパイルを実行できます。

```json
// tsconfig.json
{
  "compilerOptions": {
    // ... その他の設定 ...
    "traceResolution": true
  }
}
```

この設定後、`tsc`コマンドを実行すると、ターミナルにモジュール解決のプロセスが詳細に出力され、{marker}どのパスを探索し、どこで失敗したか{/marker}を把握するのに役立ちます。

防止策とベストプラクティス

このエラーを未然に防ぐためには、{marker}プロジェクト開始時に`tsconfig.json`とビルドツールのモジュール解決設定をしっかり行い、開発者間で認識を合わせること{/marker}が重要です。一貫したパスエイリアス戦略を適用し、ドキュメント化しておくと良いでしょう。また、新しい外部ライブラリをインストールする際には、常に`@types/`パッケージの有無を確認し、一緒にインストールする習慣をつけることが推奨されます。

```json
// tsconfig.json のベストプラクティス例
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/app/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    },
    "moduleResolution": "bundler", // モダンな環境では 'bundler' が推奨されることが多い
    "types": ["node", "jest"] // Node.js環境やテストフレームワークを使用する場合
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}
```

よくある質問（FAQ）

この用語と一緒に知っておきたい用語