Windows 환경에서 개발하면 자주 터지는 문제가 하나 있다.

로컬에서는 잘 되는데
Linux 서버(Docker / CI)에서만 import 에러로 터지는 것이다.

원인은 단순하다.

• Windows → 파일 경로 대소문자 구분 안 함
• Linux → 대소문자 엄격

예를 들어 실제 파일이

dashboard.css

인데 코드가

import "./Dashboard.css"

이면

• Windows → 정상
• Linux → 모듈 못 찾음

문제는 이게 배포하거나 CI 돌릴 때 터진다는 점이다.

그래서 해결 방법은 하나다.

커밋 단계에서 차단한다.

---

목표

이 설정의 목적은 딱 하나다.

• Windows에서도 Linux 기준 import 검사
• 커밋 시 자동 검사
• 문제 있으면 커밋 자체 차단
• 코드 스타일 검사는 전부 끔

즉

배포 지뢰만 잡는 ESLint 구성이다.

---

프로젝트 구조

기준 구조는 다음이다.

프로젝트-루트/
├─ .git
├─ .husky/
│  └─ pre-commit
├─ package.json
├─ frontend/
│  ├─ package.json
│  ├─ eslint.config.js
│  └─ src/
└─ backend/

핵심 포인트 하나.

Husky는 반드시 .git이 있는 루트에 설치한다.

frontend에만 설치하면 Git hook이 동작하지 않는다.

---

1. 루트에 Husky 설치

루트에서 실행한다.

npm init -y
npm install -D husky lint-staged

루트 package.json 수정.

{
  "scripts": {
    "prepare": "husky"
  }
}

Husky 초기화.

npm run prepare

확인.

git config --get core.hooksPath

출력

.husky

아니면 수동 설정.

git config core.hooksPath .husky

---

2. pre-commit 훅 생성

파일 생성.

.husky/pre-commit

내용.

set -e
cd frontend
npx eslint src

동작 흐름.

git commit
 ↓
pre-commit 실행
 ↓
eslint 검사
 ↓
에러 있으면 커밋 중단

Husky v9 기준 주의사항.

다음 두 줄 넣지 않는다.

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

구형 문법이다.

---

3. frontend에 ESLint 설치

frontend에서 실행.

npm install -D eslint @eslint/js eslint-plugin-import eslint-import-resolver-alias

frontend package.json

{
  "scripts": {
    "prepare": "husky"
  }
}

---

4. ESLint 설정

핵심은 하나.

import 경로를 Linux 기준으로 검사한다.

frontend/eslint.config.js

import js from "@eslint/js";
import importPlugin from "eslint-plugin-import";

export default [
  js.configs.recommended,

  {
    files: ["**/*.js", "**/*.jsx"],

    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module"
    },

    plugins: {
      import: importPlugin
    },

    settings: {
      "import/resolver": {
        alias: {
          map: [
            ["@", "./src"],
            ["@components", "./src/components"],
            ["@common", "./src/components/common"],
            ["@hooks", "./src/hooks"],
            ["@contexts", "./src/contexts"],
            ["@pages", "./src/pages"],
            ["@utils", "./src/utils"],
            ["@assets", "./src/assets"]
          ],
          extensions: [".js", ".jsx"]
        }
      }
    },

    rules: {
      "import/no-unresolved": [
        "error",
        {
          caseSensitive: true,
          ignore: ["\\.svg\\?react$"]
        }
      ],

      "no-unused-vars": "off",
      "no-console": "off",
      "no-empty": "off",
      "no-undef": "off"
    }
  },

  {
    ignores: [
      "dist/**",
      "node_modules/**"
    ]
  }
];

핵심 규칙.

import/no-unresolved

이 규칙이 다음을 잡는다.

• import 대소문자 오류
• 존재하지 않는 파일
• 상대 경로 오류

---

5. ESLint 테스트

cd frontend
npx eslint src

결과

• 출력 없음 → 정상
• 에러 출력 → 수정

---

6. 실제 커밋 흐름

git commit
 ↓
pre-commit 실행
 ↓
eslint 검사
 ↓
에러 → 커밋 차단
정상 → 커밋 진행

IDE 상관없이 동일하게 동작한다.

• IntelliJ
• VSCode
• CLI
• SourceTree

---

7. 실제 삽질 포인트

Husky를 frontend에 설치

.git이 루트에 있기 때문에 훅이 작동하지 않는다.

반드시 루트에 설치.

---

Husky 구형 문법 사용

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

이미 deprecated.

v10에서 에러 난다.

---

Windows 대소문자 문제

Windows에서는

Dashboard.css
dashboard.css

둘 다 동작한다.

Linux는 다르다.

실제 파일

dashboard.css

코드

import "./Dashboard.css"

Linux에서는 바로 터진다.

이 ESLint 설정은 Windows에서도 Linux 기준 검사한다.

---

8. 팀원 온보딩

새로 clone 하면 다음만 하면 된다.

npm install
cd frontend
npm install

prepare 스크립트 때문에 Husky는 자동 설정된다.

---

9. 이 설정이 잡는 것

잡는 것

• import 대소문자 오류
• 존재하지 않는 파일 import
• 상대경로 오류
• Linux에서만 터지는 리소스 경로 문제

의도적으로 안 잡는 것

• 코드 스타일
• unused vars
• react hooks deps
• legacy 코드 문제

목적은 하나다.

배포 지뢰 제거.

---

결론

이 설정을 넣으면

대소문자 import 실수는

배포 때가 아니라

커밋하는 순간 막힌다.