Ошибка TypeScript: "File name differs from already included file name only in casing" на Windows

Причина ошибки

Ошибка возникает из-за особенностей работы TypeScript на Windows. Дело в том, что Windows использует файловую систему NTFS, которая по умолчанию не чувствительна к регистру (case-insensitive). Это означает, что для Windows файлы Header.tsx и header.ts — это один и тот же файл.

Однако TypeScript при компиляции отслеживает регистр имён файлов, чтобы избежать путаницы при переносе кода на Linux или macOS (где файловые системы чувствительны к регистру). Когда TypeScript находит два файла, различающихся только регистром, он выдаёт ошибку, так как на Windows это может привести к неоднозначности.

Как это исправить

Есть несколько способов решения проблемы:

1. Переименуйте один из файлов

Самый простой способ — дать файлам разные имена, которые отличаются не только регистром. Например:

• Header.tsx → HeaderComponent.tsx
• header.ts → headerUtils.ts

2. Используйте опцию forceConsistentCasingInFileNames

Включите эту опцию в tsconfig.json:

{
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  }
}

Хотя это не решит саму ошибку, но поможет TypeScript более строго проверять регистр имён файлов и выдавать предупреждения на ранних этапах.

3. Используйте Git с настройкой регистра

Если вы используете Git, настройте его на чувствительность к регистру:

git config core.ignorecase false

Это поможет избежать проблем при клонировании репозитория на разные ОС.

4. Проверьте, нет ли дублирующихся импортов

Иногда ошибка возникает из-за того, что в разных файлах проекта используются разные варианты написания одного и того же файла. Проверьте все импорты в проекте:

// Плохо (разный регистр)
import Header from './Components/Header';
import header from './Components/header';

// Хорошо (единый регистр)
import Header from './Components/Header';
import headerUtils from './Components/headerUtils';

5. Используйте ESLint с правилом casing

Установите плагин eslint-plugin-import и включите правило:

{
  "rules": {
    "import/extensions": ["error", "never"],
    "import/no-unresolved": "error"
  }
}

Это поможет автоматически выявлять проблемы с регистром имён файлов.

Почему это происходит именно на Windows?

На Linux и macOS файловые системы (ext4, APFS) по умолчанию чувствительны к регистру, поэтому там файлы Header.tsx и header.ts будут считаться разными. На Windows же NTFS не различает регистр, что и приводит к подобным ошибкам.

Лучшая практика — всегда использовать единый стиль именования файлов в проекте. Рекомендую придерживаться PascalCase для компонентов (например, Header.tsx) и camelCase для утилит (например, headerUtils.ts).

{
  "compilerOptions": {
    "preserveSymlinks": true
  }
}

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext"
  }
}