“.env.local 파일이 윈도우에서 안 읽혀요” 이 5가지 확인하면 90% 해결됩니다

프론트엔드 개발 중 환경 변수가 제대로 적용되지 않는 문제는 흔히 발생합니다. .env.local 파일을 만들었는데 API 키가 인식되지 않는 상황의 원인과 해결 방법을 정리했습니다.

파일 확장자 문제 확인하기

Windows에서 자주 발생하는 문제

Windows 탐색기에서 파일 확장자를 숨기는 설정이 활성화되어 있으면, .env.local 파일을 만들 때 실제로는 .env.local.txt로 생성되는 경우가 있습니다.

프레임워크별 환경 변수 처리 방식

각 개발 도구와 프레임워크마다 환경 변수를 처리하는 방식이 다를 수 있습니다. Next.js의 경우 자체적인 환경 변수 로딩 시스템을 가지고 있습니다.

주요 개발 도구별 특징

• Next.js: 자동으로 .env 파일들을 순서대로 로드
• 일반 Node.js: dotenv 패키지를 사용해 수동 설정 필요
• 각종 에디터: 환경 변수 지원 수준이 다름

Node.js에서 환경 변수 설정

// dotenv 사용 시 정확한 경로 지정
require('dotenv').config({ path: '.env.local' });

dotenv 패키지를 사용할 때는 파일 경로를 명시적으로 지정하는 것이 좋습니다. 프로젝트 루트에서 상대 경로로 정확한 위치를 지정해야 합니다.

문제 진단 방법

1. 브라우저 개발자 도구에서 Network 탭으로 실제 요청 확인
2. API 테스트 도구로 직접 요청 테스트
3. 콘솔에서 process.env 값 출력해보기

자주 놓치는 주의사항

서버 재시작 필요성

환경 변수를 변경한 후에는 개발 서버를 재시작해야 합니다. Next.js의 경우 .env 파일 변경 시 자동으로 감지하지 않으므로 수동으로 서버를 재시작해야 합니다.

변수명 규칙

클라이언트 사이드에서 접근해야 하는 환경 변수는 NEXT_PUBLIC_ 접두사를 붙여야 합니다. 서버 사이드 전용 변수와 구분해서 사용하세요.

이러한 방법들을 차례대로 시도해보면 대부분의 환경 변수 문제를 해결할 수 있습니다. 문제가 지속된다면 사용하는 도구와 설정을 다시 한번 점검해보세요.