본문 바로가기
Q&A2026년 4월 11일1분 읽기

Vite로 빌드한 React 앱에서 'process is not defined' 에러가 납니다

주
주니어개발자소연
조회 671댓글 4

안녕하세요. CRA에서 Vite로 마이그레이션 중인데, npm run dev는 문제없이 돌아가는데 npm run build 후 preview나 Nginx 배포하면 콘솔에 이 에러가 떠요.

Uncaught ReferenceError: process is not defined
    at index-abc123.js:1:345

문제가 되는 코드는 이런 식입니다.

// src/config.ts
export const API_URL = process.env.REACT_APP_API_URL || "http://localhost:4000";

.env 파일에 REACT_APP_API_URL=https://api.example.com로 적혀 있고, CRA에서는 잘 됐습니다. Vite에서는 뭘 바꿔야 하나요?

이전 글
.env 파일 관리 베스트 프랙티스가 궁금합니다
다음 글
PostgreSQL UPDATE가 트래픽 몰릴 때만 lock wait timeout으로 멈춥니다

댓글 4

김김영삼6개월 전

Vite는 CRA와 환경 변수 주입 방식이 완전히 다릅니다. 두 가지를 동시에 바꾸셔야 해요.


1) env 이름 접두사

Vite에서 클라이언트 번들에 노출되는 변수는 VITE_로 시작해야 합니다. REACT_APP_ 은 무시됩니다.


# .env
VITE_API_URL=https://api.example.com

2) 코드에서 참조 방식

Vite는 process.env를 제공하지 않습니다. import.meta.env를 쓰세요.


export const API_URL = import.meta.env.VITE_API_URL ?? "http://localhost:4000";

3) 서드파티 라이브러리가 process.env를 쓴다면

일부 노드용 라이브러리가 번들에 섞이면 같은 에러가 재발합니다. 임시방편으로 vite.config.ts에 아래를 넣으면 런타임 에러는 막을 수 있지만, 근본적으로는 브라우저용 대체 라이브러리를 쓰는 게 맞습니다.


// vite.config.ts
export default defineConfig({
  define: {
    'process.env': {},
  },
});

위 1~2단계만 바꿔도 대부분 해결됩니다.

프프론트수진6개월 전

저도 CRA → Vite 옮길 때 똑같이 겪었어요. 특히 jsonwebtoken이나 buffer 같은 노드 전용 모듈 쓰는 라이브러리가 묻어 들어가면 define만으론 안 잡히고 vite-plugin-node-polyfills가 필요하더라고요. 한 번 그 단계까지 가면 번들 사이즈 체크도 꼭 해보세요.

주주니어개발자소연6개월 전

import.meta.env.VITE_API_URL로 바꾸니 바로 해결됐습니다. 감사합니다!


추가 질문이 하나 있는데, .env.local, .env.production, .env가 있을 때 우선순위는 어떻게 되나요? 프로덕션 빌드에서 어떤 게 먼저 적용되는지 헷갈려요.

김김영삼주니어개발자소연6개월 전

Vite의 env 로딩 우선순위는 모드에 따라 다릅니다. production 빌드 시:



  1. .env.production.local

  2. .env.local

  3. .env.production

  4. .env


위에 있을수록 우선입니다. .env.local은 git에 올리지 않는다는 규칙이라 로컬 오버라이드 용도, .env.production은 팀 공유용으로 쓰는 게 관례입니다. 참고로 .env.*.local은 mode 전용 로컬 오버라이드라 프로덕션 환경에서 CI에 파일이 없으면 무시됩니다.

Ctrl+Enter로 등록