Vite React 환경변수를 바꿨는데 화면이 그대로였던 기록

증상: 값은 바꿨는데 버튼 링크만 예전 주소였다

관리자 페이지에 외부 대시보드로 이동하는 버튼을 하나 붙였다. 로컬 .env의 URL을 새 주소로 바꾸고 새로고침했는데 화면은 계속 예전 주소로 이동했다. 처음에는 React state 문제라고 생각해서 컴포넌트를 계속 확인했지만, 실제 원인은 Vite가 읽는 환경변수 규칙과 개발 서버 재시작을 헷갈린 데 있었다.

제가 헷갈린 지점은 두 가지였다.

• DASHBOARD_URL처럼 접두사 없는 값을 클라이언트 코드에서 읽으려고 했다.
• .env 파일을 수정한 뒤 Vite 개발 서버를 다시 띄우지 않았다.

React 코드만 보면 문제가 없어 보여서 시간을 꽤 썼다.

먼저 브라우저에 박힌 값을 확인했다

환경변수 문제는 서버 파일만 보면 확신하기 어렵다. 번들에 어떤 문자열이 들어갔는지 확인하는 편이 빨랐다.

pnpm build
grep -R "old-dashboard.example" dist

개발 중에는 다음처럼 임시로 찍어 봤다.

console.log(import.meta.env.VITE_DASHBOARD_URL)

여기서 undefined가 나오면 React 렌더링 문제가 아니라 Vite가 값을 노출하지 않은 것이다.

Vite에서 클라이언트로 나가는 변수 이름

Vite는 기본적으로 VITE_로 시작하는 값만 브라우저 번들에 넣는다. 그래서 아래처럼 고쳤다.

VITE_DASHBOARD_URL=https://dashboard.example.com

코드도 process.env가 아니라 import.meta.env를 사용했다.

const dashboardUrl = import.meta.env.VITE_DASHBOARD_URL

Next.js를 만지다가 온 직후라 NEXT_PUBLIC_과 process.env 습관이 섞였다. 프레임워크마다 공개 환경변수 접두사가 다르다는 점을 다시 확인했다.

수정 후에 꼭 한 일

제가 정한 확인 순서는 이렇게 바꿨다.

1. 변수 이름에 VITE_ 접두사가 있는지 본다.
2. 개발 서버를 완전히 종료하고 다시 실행한다.
3. 배포라면 새 빌드가 실제로 배포됐는지 확인한다.
4. 브라우저 캐시가 의심되면 시크릿 창에서 링크를 눌러 본다.

pnpm dev

이미 떠 있는 개발 서버는 .env 변경을 항상 기대한 방식으로 반영하지 않는다. 그래서 환경변수 수정 후에는 그냥 재시작하는 규칙을 만들었다.

짧은 마무리

이 문제는 코드가 복잡해서 생긴 버그가 아니었다. 변수 이름 하나와 재시작 여부를 놓친 문제였다. 앞으로 프론트에서 환경변수가 이상하면 컴포넌트부터 뜯기 전에, 빌드 결과에 어떤 값이 들어갔는지 먼저 확인하려고 한다.