Vite에서 import.meta.env 타입 에러 해결하기! 5분이면 끝나는 완벽 가이드

 

Vite에서 import.meta.env 타입 에러 해결하기! 5분이면 끝나는 완벽 가이드

문제 상황

비트(Vite)로 리액트와 타입스크립트 프로젝트를 개발하던 중에 환경변수를 사용하려고 했는데요.

갑자기 이런 에러 메시지가 떴습니다.

// 예시 코드
const apiUrl = import.meta.env.VITE_API_URL;
                              ^ 에러: Property 'env' does not exist on type 'ImportMeta'.

환경변수를 불러오려고 했을 뿐인데 타입스크립트가 'import.meta.env'를 인식하지 못하는 거죠.

처음엔 당황했지만, 생각보다 간단한 방법으로 해결할 수 있었습니다.

 

타입 단언으로는 해결이 안 되더라고요

구글링을 해보니 타입 단언(Type Assertion)을 사용하라는 글들이 많이 나오는데요.

저도 이 방법들을 먼저 시도해봤습니다.

 

시도해본 패턴 1 - as 키워드 사용

const apiUrl = import.meta.env.VITE_API_URL as string;

첫 번째로 'as string'을 붙여서 타입을 강제로 지정해봤는데요.

아쉽게도 제 경우엔 여전히 같은 에러가 발생했습니다.

 

시도해본 패턴 2 - Non-null assertion 연산자

const apiUrl = import.meta.env.VITE_API_URL!;

느낌표를 붙여서 값이 확실히 존재한다고 알려주는 방법도 있거든요.

하지만 이것도 마찬가지로 효과가 없었습니다.

 

완벽하게 해결한 방법

결국 찾아낸 해결책은 타입 정의 파일을 직접 만드는 거였는데요.

단 두 가지 작업만 하면 깔끔하게 해결됩니다.

 

스텝 1. vite-env.d.ts 파일 만들기

프로젝트 루트 디렉토리에 'vite-env.d.ts' 파일을 생성하는데요.

'vite.config.ts'가 있는 바로 그 위치에 만들면 됩니다.

그리고 파일 안에 딱 한 줄만 추가하면 되거든요.

정말 이게 전부입니다.

/// <reference types="vite/client" />

이 한 줄이 타입스크립트에게 'import.meta.env'의 타입 정의를 알려주는 역할을 하는데요.

비트의 클라이언트 타입을 참조하겠다는 의미입니다.

 

스텝 2. TypeScript 설정 파일 업데이트

이제 'tsconfig.app.json' 파일을 열어서 수정해야 하는데요.

프로젝트에 따라 'tsconfig.json'일 수도 있습니다.

'include' 배열에 방금 만든 파일을 추가해주면 되거든요.

아래처럼 설정하시면 됩니다.

{
  "compilerOptions": {
    // 기존 설정들...
  },
  "include": ["/vite-env.d.ts", "src"]
}

프로젝트 구조가 다르다면 경로를 조금 수정해야 할 수도 있는데요.

대부분은 이대로 따라하시면 바로 동작합니다.

 

추가로 알아두면 좋은 팁들

이제 기본적인 문제는 해결됐지만, 몇 가지 더 유용한 정보를 공유하고 싶은데요.

실제 개발하면서 도움이 될 만한 내용들입니다.

 

환경변수 타입 정의하기

환경변수에 대한 타입을 더 명확하게 정의하고 싶다면 이런 방법도 있는데요.

'vite-env.d.ts' 파일에 인터페이스를 추가하는 겁니다.

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_APP_TITLE: string
  // 더 많은 환경변수들...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

이렇게 하면 자동완성도 지원되고 타입 체크도 더 확실해지거든요.

실수로 오타를 내는 일도 방지할 수 있습니다.

 

.env 파일 작성 규칙

비트에서 환경변수를 사용할 때는 반드시 'VITE_' 접두사를 붙여야 하는데요.

이건 보안상의 이유로 만든 규칙입니다.

# .env 파일
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My Awesome App
SECRET_KEY=12345  # 이건 접근 불가능!

'VITE_'로 시작하지 않는 환경변수는 클라이언트에서 접근할 수 없거든요.

실수로 민감한 정보가 노출되는 것을 방지하는 안전장치입니다.

 

개발/운영 환경 분리하기

환경별로 다른 설정을 사용하고 싶다면 파일을 분리하면 되는데요.

이런 식으로 구성하는 게 일반적입니다.

.env                # 모든 환경 공통
.env.development    # 개발 환경 전용
.env.production     # 운영 환경 전용

비트가 자동으로 현재 모드에 맞는 파일을 읽어오거든요.

별도의 설정 없이도 환경별 분기가 가능합니다.

 

마무리

타입스크립트와 비트를 함께 사용하다 보면 이런 타입 에러를 자주 만나게 되는데요.

다음에 같은 문제를 만났을 때 빠르게 해결할 수 있도록 정리해봤습니다.

혹시 비슷한 에러로 고생하고 계신 분들께 도움이 되었으면 좋겠네요.

다른 해결 방법이나 더 좋은 팁이 있다면 댓글로 공유해주시면 감사하겠습니다.

---