Vite로 옮겼더니 브라우저에서 'process is not defined' 에러가 납니다

Question

CRA로 만든 프로젝트를 Vite로 옮기는 중입니다. 빌드는 되는데 브라우저에서 화면이 하얗게 뜨고 콘솔에 이 에러가 찍혀요.

Uncaught ReferenceError: process is not defined

추적해보니 예전에 CRA에서 process.env.REACT_APP_API_URL 이런 식으로 환경변수를 읽던 코드들이 문제였습니다. CRA에선 이게 잘 됐거든요. Vite에서는 process 자체가 없다고 나오는데, 환경변수를 아예 못 쓰는 건 아닐 테고 뭔가 방식이 다른 것 같습니다. 어떻게 바꿔야 하나요?

김영삼 · Accepted Answer

Vite는 브라우저 번들에 Node의 process 객체를 넣어주지 않아서 그래요. CRA(webpack 기반)는 process.env를 빌드 때 문자열로 치환해줬는데, Vite는 그걸 안 하고 대신 import.meta.env라는 표준 방식을 씁니다. 그래서 process.env.XXX가 런타임까지 살아남아 있다가 process가 없어서 터지는 거예요.

두 가지를 바꾸면 됩니다. 첫째, 환경변수 접근을 import.meta.env로 바꾸세요. import.meta.env.VITE_API_URL 이런 식으로요. 둘째, 변수 이름 접두어가 REACT_APP_가 아니라 VITE_여야 합니다. Vite는 보안상 VITE_로 시작하는 것만 클라이언트 번들에 노출해요. 그래서 .env 파일의 REACT_APP_API_URL도 VITE_API_URL로 이름을 바꿔줘야 합니다. 접두어 없는 변수는 클라이언트에서 안 보이니 주의하시고요.

만약 직접 짠 코드가 아니라 어떤 서드파티 라이브러리가 내부에서 process.env를 참조해서 터지는 거라면, 그땐 vite.config에서 define 옵션으로 process.env를 빈 객체로 채워주는(define: 'process.env': 넣어서) 우회가 가능합니다. 다만 이건 라이브러리가 강제할 때만 쓰는 최후수단이고, 본인 코드는 import.meta.env로 제대로 옮기는 게 맞아요. 참고로 import.meta.env엔 MODE, DEV, PROD 같은 것도 들어있어서 개발/프로덕션 분기도 이걸로 하시면 됩니다.

댓글 1