[AI 감성 일기장] Vite와 TypeScript에서 절대 경로 인식 오류 해결

문제 상황

Vite + TypeScript 환경에서 tsconfig.json에 정의된 절대 경로 별칭(@) 을 사용하여 모듈을 import했는데 오류가 발생했다.

 

원인 분석

절대 경로를 설정할 때 기존에 CRA에서 사용하던 방식과 똑같이 tsconfig.json에 설정을 해주었었다.

{
  "paths": {
    "pages/*": ["pages/*"],
    "components/*": ["components/*"],
    "util/*": ["util/*"]
  },
}

그런데 알고보니 이 설정이 타입스크립트에만 유효하고, Vite는 이를 직접적으로 해석하여 모듈을 로드하지 않는다고 한다.

 

각각의 역할

• tsconfig.json의 paths: 타입스크립트가 타입 검사를 위해 사용
• vite.config.ts의 resolve.alias: Vite가 개발 서버 또는 빌드 시 실제 파일 시스템에서 모듈을 찾아 로드하기 위해 사용

즉, 코드는 paths 덕분에 타입 오류 없이 작성되지만, 정작 Vite 개발 서버가 import 구문을 처리할 때 해달 별칭을 실제 경로로 변환하지 못하면서 "모듈을 찾을 수 없다"는 런타임/빌드 오류가 발생한 것이다.

 

해결 방안

이를 해결하기 위해서는 Vite의 설정 파일인 vite.config.ts에서 resolve.alias옵션을 사용하여 경로 별칭을 명시적으로 정의해줘야 한다.

export default defineConfig({
  resolve: {
    alias: {
      // `src` 디렉토리를 기준으로 각 경로 별칭 정의
      pages: "/src/pages", 
      components: "/src/components",
      // 여기에 필요한 추가 경로 별칭을 설정할 수 있다
    },
  },
});

참고로 경로 별칭을 설정할 때에는 /src/pages와 같이 경로 앞에 /를 붙여서 절대 경로로 처리되도록 해야 한다.