Ako opraviť chybu Uncaught ReferenceError: process is not defined vo Vite

Najdôležitejšia oprava je jednoduchá: ak chyba pochádza z vášho kódu Vite na strane prehliadača, nahraďte process.env rozhraním API import.meta.env od Vite. Objekt process patrí do Node.js, zatiaľ čo bežná klientská aplikácia Vite beží v prehliadači. Vite zámerne sprístupňuje premenné prostredia bezpečné pre klienta prostredníctvom import.meta.env.

Napríklad kód migrovaný z iného nástrojového reťazca môže obsahovať process.env.REACT_APP_API_URL. Vo Vite je typickou náhradou import.meta.env.VITE_API_URL, pričom VITE_API_URL je definovaná v súbore .env. Ak chyba pochádza z balíka tretej strany, a nie z vášho vlastného zdroja, najlepšou opravou môže byť aktualizácia, nahradenie alebo konfigurácia tohto balíka namiesto pridávania všeobecného polyfillu pre Node.js.

Tieto pokyny vychádzajú z aktuálnej dokumentácie Vite dostupnej k 11. septembru 2026. Autoritatívnymi referenciami sú dokumentácia Premenné prostredia a režimy od Vite, dokumentácia Zdieľané možnosti a sprievodca SSR. Rozdiel medzi kódom prehliadača a runtime API Node.js nájdete v oficiálnej dokumentácii procesu Node.js.

Prečo Vite hlási chybu „process is not defined“?

Prehliadač nemá vstavaný globálny objekt process z Node.js. Dokumentácia Node.js opisuje process ako objekt, ktorý poskytuje informácie o aktuálnom procese Node.js a kontrolu nad ním. Ak sa kód očakávajúci tento objekt Node dostane do zväzku pre prehliadač, odkaz ako process.env.API_URL môže zlyhať za behu s chybou ReferenceError: process is not defined.

Klientsky model Vite je odlišný. Jeho oficiálne rozhranie prostredia sprístupňuje hodnoty pod import.meta.env. Vite tiež poskytuje vstavané hodnoty, ako sú import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL a import.meta.env.SSR.

Ktorá oprava sa vzťahuje na váš projekt?

1. Nahraďte process.env v kóde prehliadača

Začnite vyhľadaním process.env a holých odkazov na process vo vašom zdrojovom adresári. Ak je odkaz v kóde, ktorý je dodávaný do prehliadača, preveďte ho na rozhranie prostredia Vite.

Pred:

const apiUrl = process.env.REACT_APP_API_URL

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

Po:

const apiUrl = import.meta.env.VITE_API_URL

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

Ak potrebujete presný názov režimu namiesto booleovskej hodnoty vývoj/produkcia, použite import.meta.env.MODE. Vite dokumentuje režimy a NODE_ENV ako súvisiace, ale oddelené koncepty, takže nepredpokladajte, že vlastný režim ako staging je ekvivalentom zmeny NODE_ENV.

2. Premenujte klientske premenné prostredia s predponou VITE_

V predvolenom nastavení Vite sprístupňuje zdrojovému kódu klienta iba premenné prostredia, ktorých názvy začínajú na VITE_. Toto je bezpečnostná hranica určená na zníženie náhodného odhalenia serverových tajomstiev.

Súbor .env na úrovni projektu môže obsahovať:

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

Klientský kód môže čítať import.meta.env.VITE_API_URL a import.meta.env.VITE_APP_NAME. Nepredponená premenná DB_PASSWORD nie je v predvolenom nastavení sprístupnená prostredníctvom import.meta.env.

Nepovažujte predponu VITE_ za úložisko tajomstiev. Vite výslovne varuje, že predponované hodnoty sú zabalené do klientskeho kódu. Všetko, čo je dodané do prehliadača, by sa malo považovať za čitateľné používateľom. Tajné kľúče API, súkromné podpisové kľúče, heslá databáz a podobné poverenia patria na server, nie do klientskeho zväzku Vite.

Vite načítava .env a .env.local, ako aj súbory špecifické pre režim, ako sú .env.production alebo .env.staging. Hodnoty špecifické pre režim majú prednosť pred všeobecnými súbormi, zatiaľ čo premenné už prítomné v prostredí pri štarte Vite majú vyššiu prioritu ako hodnoty zo súborov.

3. Reštartujte Vite po zmene súborov .env

Vite načítava súbory prostredia pri štarte. Po pridaní, premenovaní alebo úprave hodnoty v súbore .env* zastavte vývojový server a znova ho spustite. Samotné obnovenie prehliadača môže spôsobiť, že budete testovať hodnoty načítané pred zmenou.

# stop the current dev server, then start it again
npm run dev

Tiež sa uistite, že súbor prostredia je v adresári, ktorý je Vite nakonfigurovaný používať. Predvolený envDir je koreňový adresár projektu. Ak má váš projekt vlastný root alebo envDir, správne pomenovaná premenná v nesprávnom adresári sa môže stále javiť ako undefined.

4. Overte výsledok pred zmenou čohokoľvek iného

Znovu načítajte aplikáciu a skontrolujte konzolu prehliadača. Pôvodná výnimka process is not defined by mala byť preč. Potom overte konkrétne správanie, ktoré závisí od premennej – napríklad požiadavka na API by mala smerovať na očakávanú základnú URL.

Pre dočasnú diagnostiku je rozumné zaznamenať netajnú hodnotu, ako je základná URL API alebo režim. Následne odstráňte nepotrebné logovanie, najmä ak by mohlo odhaliť detaily vnútornej konfigurácie.

Čo ak chyba pochádza zo závislosti?

Ak vaše vyhľadávanie nenájde žiadny odkaz na process vo vašom zdroji, preskúmajte stack trace. Cesta vnútri node_modules často znamená, že balík bol napísaný s predpokladmi Node.js alebo bola pre použitie v prehliadači vybraná nesprávna položka balíka.

Najbezpečnejší postup je aktualizovať závislosť, skontrolovať jej oficiálnu dokumentáciu pre podporu prehliadača a uprednostniť prehliadačovo kompatibilný balík alebo export. Všeobecný polyfill môže chybu odstrániť, no zanechať iné API určené iba pre Node neriešené, takže to nie je automaticky kompletná oprava.

Ak závislosť potrebuje iba jednu konštantu v čase kompilácie, možnosť define od Vite môže vykonať cielenú globálnu náhradu. Napríklad úzko zameraná kompatibilná požiadavka môže byť vybavená definovaním presného identifikátora, ktorý závislosť číta, namiesto vytvárania celého objektu process:

import { defineConfig } from 'vite'

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

Použite to iba vtedy, keď rozumiete tomu, čo závislosť očakáva. Vite dokumentuje define ako náhradu globálnej konštanty, ktorá je dostupná počas vývoja a staticky nahradená počas zostavovania. Nepoužívajte to na vtláčanie tajomstiev do kódu prehliadača.

Kedy je process.env platný v projekte Vite?

Môže byť platný v kóde na strane Node. Bežným príkladom je vite.config.ts. Aktuálna dokumentácia konfigurácie Vite však robí dôležitý rozdiel: súbory .env* nie sú automaticky injektované do process.env počas počiatočného vyhodnocovania konfiguračného súboru. Ak tieto súbory potrebujete v konfigurácii, použite pomocníka loadEnv od Vite.

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)
    }
  }
})

Prázdna predpona odovzdaná do loadEnv znamená, že konfigurácia môže čítať všetky zodpovedajúce hodnoty. To ich automaticky neexponuje do prehliadača, ale akákoľvek hodnota, ktorú zámerne umiestnite do define, sa môže stať súčasťou klientskeho kódu. Exponujte iba to, čo je bezpečné.

Čo sa mení pri SSR?

Vite rozlišuje klientske a serverové prostredia. V typickom nastavení SSR môže serverový kód bežať v Node.js, zatiaľ čo klientsky zväzok beží v prehliadači. To znamená, že odkaz na process.env môže byť úplne platný v module určenom iba pre server a neplatný v zdieľanom module, ktorý sa vykonáva aj na klientovi.

Ak sa chyba objaví až po hydratácii alebo navigácii v prehliadači, skontrolujte, či bol do klientskeho kódu importovaný nástroj orientovaný na server. Tam, kde je to vhodné, použite import.meta.env.SSR na rozlíšenie kontextov vykonávania, ale zároveň udržujte tajomstvá a API určené iba pre Node mimo vetiev a modulov dostupných pre klienta.

Bežné opravy, ktoré vytvárajú nové problémy

• Pridanie window.process = {}: toto potláča iba niektoré vyhľadávania a môže skryť skutočný problém s kompatibilitou.
• Nastavenie envPrefix na prázdny reťazec: Vite to výslovne odmieta, pretože by to mohlo exponovať každú premennú prostredia do klientskeho kódu.
• Premenovanie tajomstva tak, aby začínalo na VITE_: to robí tajomstvo vhodným na exponovanie klientovi; presuňte prácu závislú od tajomstva na backend.
• Zmena iba súboru .env: musíte tiež aktualizovať odkazy v kóde z process.env.NAME na import.meta.env.VITE_NAME a reštartovať Vite.
• Polyfillovanie každého globálneho objektu Node: to môže pridať váhu zväzku a stále zlyhať, ak závislosť spoľahlí na nepodporovaných moduloch Node alebo správaní za behu.

Rýchly príklad migrácie

Predpokladajme, že projekt React mal predtým tento súbor:

REACT_APP_API_URL=https://api.example.com

a túto komponentu:

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

Vo Vite premenujte premennú:

VITE_API_URL=https://api.example.com

Potom zmeňte komponentu:

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

Reštartujte vývojový server a znova otestujte. Toto je správne riešenie, keď je hodnota bezpečná na exponovanie klientovi. Ak stará premenná obsahuje súkromné poverenie, nemigrujte ju týmto spôsobom; presuňte privilegovanú operáciu za serverový endpoint.

Finálna kontrola: ako viete, že oprava je kompletná?

Kompletná oprava má viac než jeden znak. Prehliadač už nehlási process is not defined; vaše očakávané premenné bezpečné pre klienta sa vyhodnocujú na zamýšľané hodnoty; vývojové a produkčné režimy sa správajú podľa očakávania; a produkčné zostavenie funguje bez zavedenia nových chýb globálneho objektu Node.

Spustite svoj bežný vývojový test, potom vytvorte produkčné zostavenie pomocou skriptu na zostavenie vášho projektu a náhľadovo ho nasadte alebo nasadte do prostredia, ktoré pripomína produkciu. Ak sa zlyhanie objaví iba v produkcii, preskúmajte súbory .env špecifické pre režim a cesty kódu závislostí. Ak sa objaví iba v jednej závislosti, zamerajte sa na túto závislosť namiesto pridávania čoraz širších shimov do celej aplikácie.

Pre väčšinu aplikácií Vite je trvalé pravidlo priamočiare: používajte import.meta.env pre klientsku konfiguráciu, udržujte tajomstvá na serveri a vyhradzujte globálne objekty Node, ako je process, pre kód, ktorý skutočne beží v prostredí Node.