Kako riješiti grešku Uncaught ReferenceError: process is not defined u Viteu

Najvažnije rješenje je jednostavno: ako greška dolazi iz vašeg koda na strani preglednika u Viteu, zamijenite process.env s Viteovim import.meta.env API-jem. Objekt process pripada Node.js-u, dok normalna Vite klijentska aplikacija radi u pregledniku. Vite namjerno izlaže sigurne varijable okoline za klijenta putem import.meta.env.

Na primjer, kod migriran iz drugog alata može sadržavati process.env.REACT_APP_API_URL. U Viteu, tipična zamjena je import.meta.env.VITE_API_URL, pri čemu je VITE_API_URL definiran u .env datoteci. Ako greška dolazi iz paketa treće strane, a ne iz vašeg izvornog koda, najbolje rješenje može biti ažuriranje, zamjena ili konfiguracija tog paketa, umjesto dodavanja općeg Node.js polifila.

Ove smjernice prate trenutnu Vite dokumentaciju dostupnu 11. rujna 2026. Autoritativne reference su Viteova dokumentacija o varijablama okoline i načinima rada, dokumentacija o zajedničkim opcijama i SSR vodič. Za razliku između koda preglednika i Node.js runtime API-ja, pogledajte službenu Node.js dokumentaciju o procesu.

Zašto Vite kaže “process is not defined”?

Preglednik nema ugrađeni Node.js process globalni objekt. Nodeova dokumentacija opisuje process kao objekt koji pruža informacije o trenutnom Node.js procesu i kontrolu nad njim. Ako kod koji očekuje taj Node objekt dospije u bundle preglednika, referenca poput process.env.API_URL može neuspješno izvršiti u runtimeu s ReferenceError: process is not defined.

Viteov klijentski model je drugačiji. Njegov službeni API za okolinu izlaže vrijednosti pod import.meta.env. Vite također pruža ugrađene vrijednosti kao što su import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL i import.meta.env.SSR.

Koje rješenje se primjenjuje na vaš projekt?

1. Zamijenite process.env u kodu preglednika

Počnite tako da pretražite svoj izvorni direktorij za process.env i goli referencu na process. Ako je referenca u kodu koji se isporučuje pregledniku, pretvorite je u Viteov API za okolinu.

Prije:

const apiUrl = process.env.REACT_APP_API_URL

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

Nakon:

const apiUrl = import.meta.env.VITE_API_URL

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

Ako vam je potreban točan naziv moda, a ne boolean za razvoj/produkciju, koristite import.meta.env.MODE. Vite dokumentira modove i NODE_ENV kao povezane, ali odvojene koncepte, pa nemojte pretpostavljati da je prilagođeni mod poput staging ekvivalentan promjeni NODE_ENV.

2. Preimenujte klijentske varijable okoline s prefiksom VITE_

Zadano, Vite izlaže samo varijable okoline čija imena počinju s VITE_ u klijentski izvorni kod. To je sigurnosna granica namijenjena smanjenju slučajnog izlaganja tajni na strani servera.

Datoteke .env na razini projekta mogu sadržavati:

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

Klijentski kod može čitati import.meta.env.VITE_API_URL i import.meta.env.VITE_APP_NAME. Neprefiksirani DB_PASSWORD nije izložen putem import.meta.env po zadanim postavkama.

Nemojte tretirati prefiks VITE_ kao spremište tajni. Vite izričito upozorava da su prefiksirane vrijednosti ugrađene u klijentski kod. Sve što se isporučuje pregledniku treba smatrati čitljivim od strane korisnika. API tajne, privatni ključevi za potpisivanje, lozinke baze podataka i slične vjerodajnice pripadaju na server, a ne u Vite klijentski bundle.

Vite učitava .env i .env.local, kao i datoteke specifične za mod, poput .env.production ili .env.staging. Vrijednosti specifične za mod imaju prednost nad generičkim datotekama, dok varijable već prisutne u okolini kada Vite pokreće imaju viši prioritet od vrijednosti iz datoteka.

3. Ponovno pokrenite Vite nakon promjene .env datoteka

Vite učitava datoteke okoline pri pokretanju. Nakon što dodate, preimenujete ili uredite vrijednost u .env* datoteci, zaustavite poslužitelj za razvoj i ponovno ga pokrenite. Samo osvježavanje preglednika može vas ostaviti da testirate vrijednosti koje su učitane prije promjene.

# zaustavite trenutni dev server, zatim ga ponovno pokrenite
npm run dev

Također potvrdite da je datoteka okoline u direktoriju koji je Vite konfiguriran da koristi. Zadani envDir je korijen projekta. Ako vaš projekt ima prilagođeni root ili envDir, ispravno imenovana varijabla u pogrešnom direktoriju i dalje se može pojaviti kao undefined.

4. Provjerite rezultat prije promjene bilo čega drugog

Ponovno učitajte aplikaciju i provjerite konzolu preglednika. Izvorna iznimka process is not defined trebala bi nestati. Zatim provjerite specifično ponašanje koje ovisi o varijabli – na primjer, API zahtjev trebao bi ciljati očekivani osnovni URL.

Za privremenu dijagnozu, razumno je zabilježiti ne-tajnu vrijednost poput osnovnog URL-a API-ja ili moda. Uklonite nepotrebno bilježenje naknadno, posebno ako bi moglo izložiti detalje interne konfiguracije.

Što ako greška dolazi iz ovisnosti?

Ako vaša pretraga ne pronađe referencu na process u vašem izvoru, pregledajte stack trace. Putanja unutar node_modules često znači da je paket napisan s Node.js pretpostavkama ili da je odabran pogrešan unos paketa za upotrebu u pregledniku.

Najsigurniji redoslijed je ažurirati ovisnost, provjeriti njezinu službenu dokumentaciju za podršku preglednika i preferirati pregledniku kompatibilan paket ili izvoz. Generički polifil može učiniti da greška nestane, ali ostaviti druge Node-only API-je neriješene, pa to nije automatski potpuno rješenje.

Ako ovisnost treba samo jednu konstantu tijekom kompilacije, Viteova define opcija može izvršiti ciljanu globalnu zamjenu. Na primjer, usko ograničen zahtjev za kompatibilnošću može se riješiti definicijom točnog identifikatora koji ovisnost čita, umjesto izmišljanja cijelog process objekta:

import { defineConfig } from 'vite'

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

Koristite ovo samo kada razumijete što ovisnost očekuje. Vite dokumentira define kao globalnu zamjenu konstanti koja je dostupna tijekom razvoja i statički zamijenjena tijekom builda. Nemojte ga koristiti za ubacivanje tajni u klijentski kod.

Kada je process.env valjan u Vite projektu?

Može biti valjan u kodu na strani Nodea. Uobičajeni primjer je vite.config.ts. Međutim, Viteova trenutna dokumentacija konfiguracije pravi važnu razliku: .env* datoteke se ne ubacuju automatski u process.env dok se konfiguracijska datoteka početno evaluira. Ako su vam te datoteke potrebne unutar konfiguracije, koristite Viteov loadEnv pomoćnik.

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

Prazan prefiks proslijeđen loadEnv znači da konfiguracija može čitati sve pronađene vrijednosti. To ih ne izlaže automatski pregledniku, ali bilo koja vrijednost koju namjerno stavite u define može postati dio klijentskog koda. Izložite samo ono što je sigurno.

Što se mijenja za SSR?

Vite razlikuje klijentska i serverska okruženja. U tipičnom SSR postavku, serverski kod može raditi u Node.js-u dok klijentski bundle radi u pregledniku. To znači da referenca na process.env može biti potpuno valjana u server-only modulu i nevaljana u zajedničkom modulu koji se također izvršava na klijentu.

Ako se greška pojavi samo nakon hidratacije ili navigacije preglednika, provjerite je li utility orijentiran na server uvezen u klijentski kod. Koristite import.meta.env.SSR gdje je prikladno za razlikovanje konteksta izvršavanja, ali također držite tajne i Node-only API-je izvan grana i modula dostupnih klijentu.

Uobičajena rješenja koja stvaraju nove probleme

• Dodavanje window.process = {}: ovo potiskuje samo neke pretrage i može sakriti stvarni problem kompatibilnosti.
• Postavljanje envPrefix na prazan niz: Vite izričito odbija ovo jer bi moglo izložiti svaku varijablu okoline klijentskom kodu.
• Preimenovanje tajne da počinje s VITE_: to čini tajnu podobnom za izlaganje klijentu; umjesto toga, premjestite radnje ovisne o tajni na backend.
• Promjena samo .env datoteke: morate također ažurirati referencu u kodu s process.env.NAME na import.meta.env.VITE_NAME i ponovno pokrenuti Vite.
• Polifiliranje svakog Node globalnog objekta: ovo može dodati težinu bundleu i i dalje ne uspijeti ako ovisnost oslanja na nepodržane Node module ili runtime ponašanje.

Brzi primjer migracije

Pretpostavimo da je React projekt prethodno imao ovu datoteku:

REACT_APP_API_URL=https://api.example.com

i ovu komponentu:

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

U Viteu, preimenujte varijablu:

VITE_API_URL=https://api.example.com

Zatim promijenite komponentu:

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

Ponovno pokrenite dev server i ponovno testirajte. Ovo je ispravno rješenje kada je vrijednost sigurna za izlaganje klijentu. Ako stara varijabla sadrži privatnu vjerodajnicu, nemojte je migrirati na ovaj način; premjestite privilegiranu operaciju iza serverskog endpointa.

Završna provjera: kako znate da je rješenje dovršeno?

Potpuno rješenje ima više od jednog znaka. Preglednik više ne prijavljuje process is not defined; vaše očekivane klijentski sigurne varijable rješavaju se na namjeravane vrijednosti; razvojni i produkcijski modovi ponašaju se kako se očekuje; i produkcijski build radi bez uvođenja novih grešaka Node globalnih objekata.

Pokrenite svoj normalni razvojni test, zatim stvorite produkcijski build sa skriptom za build vašeg projekta i pregledajte ga ili implementirajte u okruženju koje nalikuje produkciji. Ako se neuspjeh pojavi samo u produkciji, pregledajte .env datoteke specifične za mod i kodne putanje ovisnosti. Ako se pojavi samo u jednoj ovisnosti, fokusirajte se na tu ovisnost umjesto dodavanja sve širih shimova cijeloj aplikaciji.

Za većinu Vite aplikacija, trajno pravilo je jednostavno: koristite import.meta.env za klijentsku konfiguraciju, držite tajne na serveru i rezervirajte Node globalne objekte poput process za kod koji se stvarno izvršava u Node okruženju.