환경변수 타입 때문에 Next.js가 막힐 때

Next.js 프로젝트에서 환경변수를 쓸 때, 문자열 형태로 저장되는데도 숫자나 boolean으로 사용하려고 하면 예상치 못한 버그가 생긴다. 특히 배포 환경에서만 나타나는 경우가 많아서 찾기 어렵다.

핵심은 환경변수를 큰 '설정 블록'으로 보지 말고, 각 변수의 타입과 사용처를 따로 봐야 한다는 것이다.

환경변수 형식 확인

먼저 .env 파일이나 배포 환경의 환경변수를 본다. Next.js는 모든 환경변수를 문자열로 읽는다.

# .env 파일 또는 배포 환경에서
echo $NEXT_PUBLIC_API_PORT  # "3000" (문자열)
echo $NEXT_PUBLIC_DEBUG     # "false" (문자열, boolean 아님)

Build 로그에서 타입 에러 찾기

Production build 할 때 타입 체커가 환경변수 타입 에러를 잡을 수 있다.

npm run build
# 로그에서 "Cannot assign type 'string | undefined' to type 'number'" 같은 메시지를 찾는다

환경변수 타입 강제

Next.js 13+ 에서는 zod 같은 검증 라이브러리로 환경변수의 타입을 강제할 수 있다.

# npm install zod

그 다음 환경변수를 파싱할 때 명시적으로 타입을 변환한다.

런타임에서 타입 변환

환경변수를 사용하는 곳에서 명시적으로 타입을 변환한다.

# API_PORT는 문자열이므로 숫자로 변환해야 함
const port = parseInt(process.env.NEXT_PUBLIC_API_PORT || "3000", 10)

# boolean은 문자열 비교로 확인
const isDebug = process.env.NEXT_PUBLIC_DEBUG === "true"

로컬과 배포 환경의 환경변수 비교

로컬 .env와 배포 환경의 환경변수가 형식이 다를 수 있다. 로컬에서는 숫자로 입력했지만 배포 환경에서는 문자열로 저장되었을 수도 있다.

# 로컬: .env 파일
NEXT_PUBLIC_MAX_RETRIES=5

# 배포: 환경변수로 설정 (문자열로 저장됨)
export NEXT_PUBLIC_MAX_RETRIES="5"

배포 환경에서 build 테스트

Production build를 배포 환경의 환경변수로 해본다. 로컬 .env와 다른 값이나 누락된 값이 있으면 이 단계에서 발견된다.

TypeScript strict mode 확인

tsconfig.json의 strict 옵션이 true면 환경변수 타입 에러를 더 엄격하게 잡는다.

# tsconfig.json
"strict": true  // 또는 개별 옵션들 확인

1. build 로그에서 타입 에러 메시지를 찾는다.
2. 각 환경변수의 타입을 명시적으로 확인한다.
3. 환경변수를 사용하는 곳에서 타입 변환을 명시적으로 한다.

마지막 확인

수정한 후에는 배포 환경과 정확히 같은 환경변수로 다시 build 해본다. 각 단계에서 환경변수 값을 로그로 남겨두면 다음에 환경변수 문제가 나올 때 재사용할 수 있다.