TypeScript 환경변수에서 null이 나올 때 타입 검증하기

프로젝트에서 환경변수 관련 타입 에러가 반복되면, 보통은 몇 가지 확인 포인트를 먼저 봐야 한다.

환경변수가 null로 들어오는 문제는 대부분 빌드 단계나 로컬 설정 차이에서 비롯된다. 증상을 정확히 파악하려면 타입 검증부터 시작하는 게 낫다.

먼저 볼 것: 타입 정의와 로컬 환경

환경변수가 제대로 로드되는지 확인하는 가장 빠른 방법은 빌드 단계에서 타입을 검증하는 것이다.

npm run build
npx tsc --noEmit

두 명령을 실행했을 때 에러가 나면, 실제 환경변수 설정이 빠진 거다. 타입 검증 메시지가 구체적으로 어느 환경변수가 undefined인지 알려주므로, 그걸 기준으로 .env 파일을 확인한다.

타입 가드로 null 처리하기

TypeScript에서는 런타임에 null이 들어올 수 있다고 가정하고 코드를 짜는 게 안전하다.

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error('API_KEY is not defined');
}

const config = { key: apiKey }; // 여기서 apiKey는 string 타입으로 인정됨

if 문으로 null 여부를 확인한 후에 사용하면, TypeScript가 자동으로 타입을 좁혀준다. 이렇게 하면 이후 코드에서 null 체크를 반복할 필요가 없다.

로컬 환경과 배포 환경이 다를 때

로컬에서는 .env 파일이 제대로 로드되지만, 배포 환경에서는 환경변수가 설정되지 않은 경우가 있다. 이런 경우는 배포 설정을 먼저 확인해야 한다.

• 로컬: 개발 환경에서는 .env.local 파일로 환경변수를 로드
• 배포: CI/CD 파이프라인이나 서버 설정에서 환경변수를 주입해야 함

빌드 로그에서 경고나 에러 메시지가 있는지 확인하면, 어느 단계에서 환경변수 로드에 실패했는지 알 수 있다.

확인 체크리스트

1. npx tsc --noEmit으로 타입 에러 확인
2. 로컬 .env 파일에서 필요한 환경변수 모두 정의했는지 확인
3. 배포 환경에서는 CI/CD 설정이나 서버의 환경변수 설정에 같은 변수들이 있는지 확인
4. 빌드 로그에서 환경변수 관련 경고 메시지 확인
5. 필요하면 환경변수 기본값을 설정하거나, null 체크를 엄격하게 유지

타입 검증과 null 처리를 확실히 하면, 배포 후 환경변수 타입 에러로 인한 문제는 대부분 사전에 방지할 수 있다.