Jak opravit chybu Uncaught ReferenceError: process is not defined ve Vite

Nejdůležitější oprava je jednoduchá: pokud chyba pochází z vašeho kódu Vite na straně prohlížeče, nahraďte process.env API import.meta.env od Vite. Objekt process patří do Node.js, zatímco běžná klientská aplikace Vite běží v prohlížeči. Vite záměrně zpřístupňuje proměnné prostředí bezpečné pro klienta prostřednictvím import.meta.env.

Například kód migrovaný z jiného nástrojového řetězce může obsahovat process.env.REACT_APP_API_URL. Ve Vite je typickou náhradou import.meta.env.VITE_API_URL, kde je VITE_API_URL definován v souboru .env. Pokud chyba pochází ze balíčku třetí strany, nikoli z vašeho vlastního zdroje, nejlepší opravou může být aktualizace, nahrazení nebo konfigurace tohoto balíčku, místo přidávání obecného polyfillu pro Node.js.

Tato doporučení vycházejí z aktuální dokumentace Vite dostupné k 11. září 2026. Autoritativními odkazy jsou dokumentace Vite k Proměnným prostředí a režimům, dokumentace ke Sdíleným možnostem a průvodce SSR. Pro rozlišení mezi kódem v prohlížeči a runtime API Node.js viz oficiální dokumentace procesu Node.js.

Proč Vite hlásí „process is not defined“?

Prohlížeč nemá vestavěný globální objekt process z Node.js. Dokumentace Node.js popisuje process jako objekt, který poskytuje informace o aktuálním procesu Node.js a kontrolu nad ním. Pokud se kód, který očekává tento objekt Node, dostane do bundlu pro prohlížeč, odkaz jako process.env.API_URL může za běhu selhat s chybou ReferenceError: process is not defined.

Klientský model Vite je odlišný. Jeho oficiální API pro prostředí zpřístupňuje hodnoty pod import.meta.env. Vite také poskytuje vestavěné hodnoty, jako jsou import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL a import.meta.env.SSR.

Která oprava se vztahuje na váš projekt?

1. Nahraďte process.env v kódu pro prohlížeč

Začněte prohledáním zdrojového adresáře pro výskyt process.env a samostatných odkazů na process. Pokud je odkaz v kódu, který je dodáván do prohlížeče, převeďte jej na API prostředí Vite.

Před:

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

Pokud potřebujete přesný název režimu, nikoli boolean pro vývoj/produkci, použijte import.meta.env.MODE. Vite dokumentuje režimy a NODE_ENV jako související, ale oddělené koncepty, takže nepředpokládejte, že vlastní režim, jako je staging, je ekvivalentní změně NODE_ENV.

2. Přejmenujte klientské proměnné prostředí s předponou VITE_

Ve výchozím nastavení Vite zpřístupňuje zdrojovému kódu na straně klienta pouze proměnné prostředí, jejichž názvy začínají na VITE_. Jedná se o bezpečnostní hranici určenou ke snížení náhodného odhalení serverových tajemství.

Soubor .env na úrovni projektu může obsahovat:

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

Klientský kód může číst import.meta.env.VITE_API_URL a import.meta.env.VITE_APP_NAME. Proměnná DB_PASSWORD bez předpony není ve výchozím nastavení zpřístupněna prostřednictvím import.meta.env.

Nepovažujte předponu VITE_ za úložiště tajemství. Vite výslovně varuje, že hodnoty s předponou jsou zabundlovány do kódu na straně klienta. Vše, co je dodáno do prohlížeče, by mělo být považováno za čitelné uživatelem. Tajné klíče API, soukromé podpisové klíče, hesla k databázím a podobné přihlašovací údaje patří na server, nikoli do klientského bundlu Vite.

Vite načítá .env a .env.local, plus soubory specifické pro režim, jako jsou .env.production nebo .env.staging. Hodnoty specifické pro režim mají přednost před obecnými soubory, zatímco proměnné již přítomné v prostředí při spuštění Vite mají vyšší prioritu než hodnoty ze souborů.

3. Restartujte Vite po změně souborů .env

Vite načítá soubory prostředí při spuštění. Poté, co přidáte, přejmenujete nebo upravíte hodnotu v souboru .env*, zastavte vývojový server a znovu jej spusťte. Pouhé obnovení prohlížeče může vést k testování hodnot, které byly načteny před změnou.

# zastavte aktuální dev server a poté jej znovu spusťte
npm run dev

Také se ujistěte, že se soubor prostředí nachází v adresáři, který je nakonfigurován pro použití Vite. Výchozí envDir je kořen projektu. Pokud má váš projekt vlastní root nebo envDir, správně pojmenovaná proměnná ve špatném adresáři se stále může jevit jako undefined.

4. Ověřte výsledek před změnou čehokoli dalšího

Znovu načtěte aplikaci a zkontrolujte konzoli prohlížeče. Původní výjimka process is not defined by měla zmizet. Poté ověřte konkrétní chování, které závisí na proměnné – například API požadavek by měl cílit na očekávanou základní URL.

Pro dočasnou diagnostiku je rozumné logovat ne-tajnou hodnotu, jako je základní URL API nebo režim. Následně odstraňte nepotřebné logování, zejména pokud by mohlo odhalit detaily interní konfigurace.

Co když chyba pochází ze závislosti?

Pokud vaše hledání nenajde žádný odkaz na process ve vašem zdroji, prozkoumejte stack trace. Cesta uvnitř node_modules často znamená, že balíček byl napsán s předpoklady pro Node.js nebo byla pro použití v prohlížeči vybrána špatná položka balíčku.

Nejbezpečnější postup je aktualizovat závislost, zkontrolovat její oficiální dokumentaci pro podporu prohlížeče a preferovat balíček nebo export kompatibilní s prohlížečem. Obecný polyfill může způsobit zmizení chyby, zatímco jiné API pouze pro Node zůstanou nevyřešeny, takže to automaticky není kompletní oprava.

Pokud závislost potřebuje pouze jednu konstantu v době kompilace, možnost define ve Vite může provést cílenou globální náhradu. Například úzce vymezený požadavek na kompatibilitu lze vyřešit definováním přesného identifikátoru, který závislost čte, místo vytváření celého objektu process:

import { defineConfig } from 'vite'

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

Použijte to pouze tehdy, když rozumíte tomu, co závislost očekává. Vite dokumentuje define jako náhradu globální konstanty, která je dostupná během vývoje a staticky nahrazena během buildu. Nepoužívejte to k tlačení tajemství do kódu v prohlížeči.

Kdy je process.env ve Vite projektu platný?

Může být platný v kódu na straně Node. Běžným příkladem je vite.config.ts. Současná dokumentace konfigurace Vite však činí důležitý rozdíl: soubory .env* nejsou automaticky vloženy do process.env během počátečního vyhodnocování konfiguračního souboru. Pokud tyto soubory potřebujete uvnitř konfigurace, použijte 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ázdná předpona předaná loadEnv znamená, že konfigurace může číst všechny odpovídající hodnoty. To je automaticky nezpřístupňuje prohlížeči, ale jakákoli hodnota, kterou záměrně umístíte do define, se může stát součástí klientského kódu. Zpřístupňujte pouze to, co je bezpečné.

Co se mění pro SSR?

Vite rozlišuje klientské a serverové prostředí. V typickém nastavení SSR může serverový kód běžet v Node.js, zatímco klientský bundl běží v prohlížeči. To znamená, že odkaz na process.env může být zcela platný v modulu pouze pro server a neplatný ve sdíleném modulu, který se také spouští na klientu.

Pokud se chyba objeví až po hydrataci nebo navigaci v prohlížeči, zkontrolujte, zda byl do klientského kódu importován nástroj orientovaný na server. Kde je to vhodné, použijte import.meta.env.SSR k rozlišení kontextů spuštění, ale také udržujte tajemství a API pouze pro Node mimo větve a moduly dostupné klientovi.

Běžné opravy, které vytvářejí nové problémy

• Přidání window.process = {}: to potlačí pouze některá hledání a může skrýt skutečný problém s kompatibilitou.
• Nastavení envPrefix na prázdný řetězec: Vite to výslovně odmítá, protože by to mohlo zpřístupnit každou proměnnou prostředí klientskému kódu.
• Přejmenování tajemství tak, aby začínalo na VITE_: to činí tajemství způsobilým pro odhalení klientovi; místo toho přesuňte práci závislou na tajemství na backend.
• Změna pouze souboru .env: musíte také aktualizovat odkazy v kódu z process.env.NAME na import.meta.env.VITE_NAME a restartovat Vite.
• Polyfilling každého globálního objektu Node: to může přidat váhu bundlu a stále selhat, pokud závislost spoléhá na nepodporované moduly Node nebo runtime chování.

Rychlý příklad migrace

Předpokládejme, že projekt React měl dříve tento soubor:

REACT_APP_API_URL=https://api.example.com

a tuto komponentu:

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

Ve Vite přejmenujte proměnnou:

VITE_API_URL=https://api.example.com

Poté změňte komponentu:

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

Restartujte dev server a znovu testujte. Toto je správné řešení, když je hodnota bezpečná pro odhalení klientovi. Pokud stará proměnná obsahuje soukromé přihlašovací údaje, nemigrujte ji tímto způsobem; přesuňte privilegovanou operaci za serverový endpoint.

Závěrečná kontrola: jak poznáte, že je oprava kompletní?

Kompletní oprava má více než jeden znak. Prohlížeč již nehlásí process is not defined; vaše očekávané proměnné bezpečné pro klienta se vyhodnocují na zamýšlené hodnoty; vývojové a produkční režimy se chovají podle očekávání; a produkční build funguje bez zavedení nových chyb globálních objektů Node.

Spusťte svůj běžný vývojový test, poté vytvořte produkční build pomocí build skriptu vašeho projektu a náhledněte jej nebo nasadte do prostředí, které připomíná produkci. Pokud se selhání objeví pouze v produkci, prozkoumejte soubory .env specifické pro režim a cesty kódu závislostí. Pokud se objeví pouze v jedné závislosti, zaměřte se na tuto závislost, místo přidávání stále širších shimů do celé aplikace.

Pro většinu aplikací Vite je trvalé pravidlo přímočaré: používejte import.meta.env pro klientskou konfiguraci, udržujte tajemství na serveru a vyhraďte globální objekty Node, jako je process, pro kód, který skutečně běží v prostředí Node.