Hogyan javítsd ki az Uncaught ReferenceError: process is not defined hibát Vite-ban

A legfontosabb javítás egyszerű: ha a hiba a böngészőoldali Vite kódból származik, cseréld le a process.env használatát a Vite import.meta.env API-jára. A process objektum a Node.js-hez tartozik, míg egy normál Vite kliensalkalmazás a böngészőben fut. A Vite szándékosan a import.meta.env révén teszi közzé a kliensbiztonságos környezeti változókat.

Például egy másik eszközláncból migrált kód tartalmazhat process.env.REACT_APP_API_URL hivatkozásokat. Vite-ban a tipikus helyettesítés az import.meta.env.VITE_API_URL, ahol a VITE_API_URL egy .env fájlban van definiálva. Ha a hiba nem a saját forráskódból, hanem egy harmadik féltől származó csomagból származik, a legjobb megoldás lehet az adott csomag frissítése, cseréje vagy konfigurálása, ahelyett, hogy általános Node.js polifillt adnál hozzá.

Ez az útmutató a 2026. szeptember 11-én elérhető aktuális Vite dokumentáción alapul. A hiteles hivatkozások a Vite Környezeti változók és módok dokumentációja, a Közös beállítások dokumentációja és az SSR útmutató. A böngészőkód és a Node.js futtatókörnyezet API-k közötti különbségekért lásd a hivatalos Node.js process dokumentációt.

Miért jelzi a Vite, hogy „process is not defined”?

A böngészőnek nincs beépített Node.js process globális változója. A Node dokumentációja a process-t úgy írja le, mint egy objektumot, amely információt nyújt és irányítást biztosít az aktuális Node.js folyamattal kapcsolatban. Ha olyan kód, amely erre a Node objektumra számít, bekerül a böngésző bundle-be, egy ilyen hivatkozás, mint a process.env.API_URL, futásidejű hibát okozhat: ReferenceError: process is not defined.

A Vite kliensmodellje eltérő. Hivatalos környezet API-ja az értékeket az import.meta.env alatt teszi közzé. A Vite beépített értékeket is biztosít, mint például az import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL és import.meta.env.SSR.

Melyik javítás vonatkozik a projektedre?

1. process.env cseréje a böngészőkódban

Kezdd azzal, hogy átkutatod a forráskönyvtáradat process.env és puszta process hivatkozások után. Ha a hivatkozás olyan kódban van, amelyet a böngészőnek szállítanak, alakítsd át a Vite környezet API-jára.

Előtte:

const apiUrl = process.env.REACT_APP_API_URL

if (process.env.NODE_ENV === 'development') {
  console.log('Development mode')
}

Utána:

const apiUrl = import.meta.env.VITE_API_URL

if (import.meta.env.DEV) {
  console.log('Development mode')
}

Ha a pontos módnevet szeretnéd, nem pedig egy fejlesztés/produkció logikai értéket, használd az import.meta.env.MODE-ot. A Vite dokumentációja a módokat és a NODE_ENV-ot kapcsolódó, de különálló fogalmakként kezeli, tehát ne feltételezd, hogy egy egyedi mód, mint a staging, egyenértékű a NODE_ENV megváltoztatásával.

2. Kliens környezeti változók átnevezése VITE_ előtaggal

Alapértelmezés szerint a Vite csak azokat a környezeti változókat teszi közzé a kliens forráskód számára, amelyek neve VITE_-vel kezdődik. Ez egy biztonsági határ, amelynek célja a szerveroldali titkok véletlen kiszivárgásának csökkentése.

Egy projektszintű .env fájl tartalmazhatja:

VITE_API_URL=https://api.example.com
VITE_APP_NAME=Example App
DB_PASSWORD=do-not-expose-this

A kliens kód beolvashatja az import.meta.env.VITE_API_URL és az import.meta.env.VITE_APP_NAME értékeket. Az előtag nélküli DB_PASSWORD alapértelmezés szerint nem kerül közzétételre az import.meta.env révén.

Ne kezeld a VITE_ előtagot titoktárolóként. A Vite kifejezetten figyelmeztet, hogy az előtagos értékek beépülnek a kliensoldali kódba. Bármit, amit a böngészőnek szállítanak, a felhasználó által olvashatónak kell tekinteni. API titkok, privát aláíró kulcsok, adatbázis jelszavak és hasonló hitelesítő adatok a szerveren tartoznak, nem a Vite kliens bundle-ben.

A Vite betölti a .env és .env.local fájlokat, valamint a mód-specifikus fájlokat, mint például a .env.production vagy a .env.staging. A mód-specifikus értékek elsőbbséget élveznek az általános fájlokkal szemben, míg a Vite indításakor a környezetben már jelenlévő változók magasabb prioritást élveznek a fájlokból származó értékekkel szemben.

3. Vite újraindítása a .env fájlok módosítása után

A Vite az indításkor tölti be a környezeti fájlokat. Miután hozzáadtál, átneveztél vagy szerkesztettél egy értéket egy .env* fájlban, állítsd le a fejlesztői szervert, és indítsd újra. Egy egyszerű böngésző frissítés önmagában arra vezethet, hogy a módosítás előtt betöltött értékeket teszteled.

# állítsd le az aktuális dev szervert, majd indítsd újra
npm run dev

Ellenőrizd azt is, hogy a környezeti fájl abban a könyvtárban van-e, amelyet a Vite konfigurációja használ. Az alapértelmezett envDir a projekt gyökérkönyvtára. Ha a projektednek egyedi root vagy envDir beállítása van, egy helyesen elnevezett változó rossz könyvtárban továbbra is undefined-ként jelenhet meg.

4. Az eredmény ellenőrzése, mielőtt bármi mást változtatnál

Töltsd újra az alkalmazást, és ellenőrizd a böngésző konzolját. Az eredeti process is not defined kivételnek el kell tűnnie. Ezután ellenőrizd a konkrét viselkedést, amely a változótól függ – például egy API kérésnek a várt alap URL-re kell irányulnia.

Ideiglenes diagnosztikára ésszerű egy nem titkos érték, mint például az API alap URL vagy a mód naplózása. Utána távolítsd el a felesleges naplózást, különösen, ha az belső konfigurációs részleteket fedhetne fel.

Mi van, ha a hiba egy függőségből származik?

Ha a keresésed során nem találsz process hivatkozást a forráskódban, vizsgáld meg a stack trace-t. Egy node_modules-on belüli útvonal gyakran azt jelenti, hogy egy csomagot Node.js feltételezésekkel írtak, vagy a rossz csomagbejegyzést választották ki böngészőhasználatra.

A legbiztonságosabb sorrend a függőség frissítése, a hivatalos dokumentációjának ellenőrzése böngészőtámogatás szempontjából, és egy böngészőkompatibilis csomag vagy export előnyben részesítése. Egy általános polifill eltüntetheti a hibát, miközben más Node-only API-k megoldatlanok maradnak, tehát ez nem automatikusan teljes javítás.

Ha egy függőségnek csak egy fordítási idejű állandóra van szüksége, a Vite define opciója elvégezhet egy célzott globális helyettesítést. Például egy szűk körű kompatibilitási követelmény kezelhető úgy, hogy definiáljuk a függőség által olvasott pontos azonosítót, ahelyett, hogy egy teljes process objektumot gyártanánk:

import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    'process.env.LEGACY_FLAG': JSON.stringify('enabled')
  }
})

Ezt csak akkor használd, ha érted, mit vár a függőség. A Vite dokumentációja a define-ot globális állandó helyettesítésként írja le, amely fejlesztés közben elérhető, és build közben statikusan helyettesítődik. Ne használd titkok böngészőkódba juttatására.

Mikor érvényes a process.env egy Vite projektben?

Érvényes lehet Node-oldali kódban. Egy gyakori példa a vite.config.ts. Azonban a Vite aktuális konfigurációs dokumentációja fontos különbséget tesz: a .env* fájlok nem kerülnek automatikusan injektálásra a process.env-be, miközben a konfigurációs fájlt kezdetben kiértékelik. Ha ezekre a fájlokra van szükséged a konfigurációban, használd a Vite loadEnv segédfüggvényét.

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    define: {
      __APP_API_URL__: JSON.stringify(env.APP_API_URL)
    }
  }
})

A loadEnv-nek átadott üres előtag azt jelenti, hogy a konfiguráció minden egyező értéket beolvashat. Ez nem teszi őket automatikusan közzé a böngésző számára, de bármely érték, amelyet szándékosan a define-ba helyesel, a kliens kód részévé válhat. Csak azt tedd közzé, ami biztonságos.

Mi változik SSR esetén?

A Vite megkülönbözteti a kliens és a szerver környezeteket. Egy tipikus SSR beállításban a szerver kód futtatható Node.js-ben, míg a kliens bundle a böngészőben fut. Ez azt jelenti, hogy egy process.env hivatkozás tökéletesen érvényes lehet egy csak szerveroldali modulban, és érvénytelen egy megosztott modulban, amely a kliensen is fut.

Ha a hiba csak hidráció vagy böngésző navigáció után jelenik meg, ellenőrizd, hogy egy szerverorientált segédfüggvényt importáltak-e a kliens kódba. Használd az import.meta.env.SSR-t, ahol megfelelő, a futtatási kontextusok megkülönböztetésére, de tartsd a titkokat és a Node-only API-kat a kliens által elérhető ágakon és modulokon kívül.

Gyakori javítások, amelyek új problémákat okoznak

• window.process = {} hozzáadása: ez csak egyes kereséseket nyom el, és elrejtheti a valódi kompatibilitási problémát.
• Az envPrefix üres karakterláncra állítása: a Vite kifejezetten elutasítja ezt, mert minden környezeti változót a kliens kódhoz férhetne.
• Egy titok átnevezése VITE_-vel kezdődőre: ez alkalmassá teszi a titkot a kliens közzétételére; helyette a titokfüggő munkát helyezd át a backendre.
• Csak a .env fájl módosítása: frissítened kell a kód hivatkozásait is process.env.NAME-ról import.meta.env.VITE_NAME-ra, és újra kell indítanod a Vite-ot.
• Minden Node globális polifillje: ez növelheti a bundle súlyát, és továbbra is sikertelen lehet, ha egy függőség nem támogatott Node modulokra vagy futásidejű viselkedésre támaszkodik.

Egy gyors migrációs példa

Tegyük fel, hogy egy React projektnek korábban ez a fájlja volt:

REACT_APP_API_URL=https://api.example.com

és ez a komponens:

const endpoint = process.env.REACT_APP_API_URL
fetch(`${endpoint}/users`)

Vite-ban nevezd át a változót:

VITE_API_URL=https://api.example.com

Ezután változtasd meg a komponenst:

const endpoint = import.meta.env.VITE_API_URL
fetch(`${endpoint}/users`)

Indítsd újra a dev szervert, és teszteld újra. Ez a helyes megoldás, ha az érték biztonságosan közzétehető a kliens számára. Ha a régi változó privát hitelesítő adatot tartalmaz, ne migráld így; helyezd a jogosultsággal rendelkező műveletet egy szerver végpont mögé.

Végső ellenőrzés: honnan tudod, hogy a javítás teljes?

Egy teljes javításnak több jele is van. A böngésző nem jelzi többé a process is not defined hibát; a várt kliensbiztonságos változók a szándékolt értékekre oldódnak fel; a fejlesztési és produkciós módok a vártak szerint viselkednek; és a produkciós build működik új Node-globális hibák bevezetése nélkül.

Futtasd a normál fejlesztési tesztet, majd készíts egy produkciós buildet a projekted build szkriptjével, és előnézd vagy telepítsd egy produkcióhoz hasonló környezetben. Ha a hiba csak produkcióban jelenik meg, vizsgálj meg mód-specifikus .env fájlokat és függőség kódútvonalakat. Ha csak egy függőségben jelenik meg, fókuszálj arra a függőségre, ahelyett, hogy egyre szélesebb körű shimeket adnál az egész alkalmazáshoz.

A legtöbb Vite alkalmazás számára a tartós szabály egyértelmű: használj import.meta.env-et a kliens konfigurációhoz, tartsd a titkokat a szerveren, és tartsd fenn a Node globális változókat, mint a process, olyan kódok számára, amelyek valóban Node környezetben futnak.