'process is not defined' 오류 해결 (Vite·브라우저)

증상

브라우저 콘솔에 다음 오류가 뜨고 앱이 멈춥니다.

Uncaught ReferenceError: process is not defined

원인

process는 Node.js 전역 객체라 브라우저에는 존재하지 않습니다. process.env.XXX처럼 환경변수를 브라우저 코드에서 직접 참조하면 발생합니다. 번들러마다 클라이언트에서 환경변수를 노출하는 방식이 다릅니다.

해결

Vite

import.meta.env를 사용하고, 클라이언트에 노출할 변수는 VITE_ 접두사가 필요합니다.

// ✕ process.env.API_URL
// ○
const apiUrl = import.meta.env.VITE_API_URL;

Next.js

브라우저에서 읽을 변수는 NEXT_PUBLIC_ 접두사를 붙입니다.

const apiUrl = process.env.NEXT_PUBLIC_API_URL; // Next는 빌드 시 치환되어 동작

Create React App

const apiUrl = process.env.REACT_APP_API_URL;

라이브러리가 process를 참조하는 경우

일부 라이브러리가 process.env.NODE_ENV를 쓰면 빌드 설정에서 정의해 줍니다(Vite define).

// vite.config.js
export default { define: { 'process.env.NODE_ENV': JSON.stringify('production') } };

규칙: 브라우저로 가는 환경변수는 반드시 정해진 접두사(VITE_ / NEXT_PUBLIC_ / REACT_APP_)를 붙이고, 비밀 키는 클라이언트에 노출하지 마세요.