Kaip ištaisyti klaidą „Uncaught ReferenceError: process is not defined“ naudojant Vite

Svarbiausias sprendimas yra paprastas: jei klaida kyla iš jūsų naršyklės pusės Vite kodo, pakeiskite process.env į Vite import.meta.env API. process objektas priklauso Node.js, o įprasta Vite kliento programa veikia naršyklėje. Vite sąmoningai pateikia naršyklei saugius aplinkos kintamuosius per import.meta.env.

Pavyzdžiui, kodas, perkeltas iš kitos įrankių grandinės, gali turėti process.env.REACT_APP_API_URL. Vite aplinkoje tipiškas pakaitalas yra import.meta.env.VITE_API_URL, kur VITE_API_URL apibrėžtas .env faile. Jei klaida kyla iš trečiosios šalies paketo, o ne iš jūsų paties šaltinio kodo, geriausias sprendimas gali būti to paketo atnaujinimas, pakeitimas arba konfigūravimas, o ne visuotinio Node.js polifilo pridėjimas.

Šios gairės atitinka dabartinę Vite dokumentaciją, prieinamą 2026 m. rugsėjo 11 d. Autoritetingi šaltiniai yra Vite Aplinkos kintamųjų ir režimų dokumentacija, Bendrų parinkčių dokumentacija ir SSR vadovas. Dėl skirtumo tarp naršyklės kodo ir Node.js vykdymo aplinkos API, žr. oficialią Node.js process dokumentaciją.

Kodėl Vite rodo „process is not defined“?

Naršyklėje nėra integruoto Node.js process globalaus objekto. Node dokumentacija apibūdina process kaip objektą, kuris suteikia informacijos apie dabartinį Node.js procesą ir leidžia jį valdyti. Jei kodas, tikintis to Node objekto, patenka į naršyklės paketą, nuoroda, tokia kaip process.env.API_URL, vykdymo metu gali sugriūti su klaida ReferenceError: process is not defined.

Vite kliento modelis yra kitoks. Jo oficiali aplinkos API pateikia reikšmes po import.meta.env. Vite taip pat pateikia integruotas reikšmes, tokias kaip import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL ir import.meta.env.SSR.

Kuris sprendimas tinka jūsų projektui?

1. Pakeiskite process.env naršyklės kode

Pirmiausia paieškokite process.env ir paprastų nuorodų į process savo šaltinio kataloge. Jei nuoroda yra kode, kuris pateikiamas naršyklei, konvertuokite ją į Vite aplinkos API.

Prieš:

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

Jei jums reikia tikslaus režimo pavadinimo, o ne kūrimo/gamybos loginio kintamojo, naudokite import.meta.env.MODE. Vite dokumentacija nurodo, kad režimai ir NODE_ENV yra susiję, bet atskiri konceptai, todėl nemanyskite, kad toks individualus režimas kaip staging yra tas pats, kas NODE_ENV keitimas.

2. Pervardykite kliento aplinkos kintamuosius su VITE_ prefiksu

Pagal numatytuosius nustatymus Vite kliento šaltinio kodui pateikia tik tuos aplinkos kintamuosius, kurių pavadinimai prasideda VITE_. Tai saugumo riba, skirta sumažinti atsitiktinį serverio slaptažodžių atskleidimą.

Projekto lygmens .env faile gali būti:

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

Kliento kodas gali skaityti import.meta.env.VITE_API_URL ir import.meta.env.VITE_APP_NAME. Kintamasis DB_PASSWORD be prefikso pagal numatytuosius nustatymus per import.meta.env nėra atskleidžiamas.

Nelaikykite VITE_ prefikso slaptažodžių saugykla. Vite aiškiai įspėja, kad su prefiksu pažymėtos reikšmės yra įtraukiamos į kliento pusės kodą. Bet kas, pateikta naršyklei, turėtų būti laikoma vartotojo perskaitytina. API slaptažodžiai, privatūs parašų raktai, duomenų bazių slaptažodžiai ir panašūs kredencialai turi būti serveryje, o ne Vite kliento pakete.

Vite įkelia .env ir .env.local, taip pat režimui specifinius failus, tokius kaip .env.production arba .env.staging. Režimui specifinės reikšmės turi pirmenybę prieš bendruosius failus, o kintamieji, kurie jau yra aplinkoje, kai Vite startuoja, turi aukštesnį prioritetą nei reikšmės iš failų.

3. Paleiskite Vite iš naujo po .env failų keitimo

Vite įkelia aplinkos failus startuodamas. Pridėję, pervardinę arba redaguodami reikšmę .env* faile, sustabdykite kūrimo serverį ir paleiskite jį iš naujo. Vien naršyklės atnaujinimas gali palikti jus testuojant reikšmes, kurios buvo įkeltos prieš pakeitimą.

# sustabdykite dabartinį dev serverį, tada paleiskite jį iš naujo
npm run dev

Taip pat įsitikinkite, kad aplinkos failas yra kataloge, kurį Vite yra sukonfigūruotas naudoti. Numatytasis envDir yra projekto šaknis. Jei jūsų projektas turi individualų root arba envDir, teisingai pavadintas kintamasis neteisingame kataloge vis tiek gali atrodyti kaip undefined.

4. Patikrinkite rezultatą prieš keisdami ką nors kita

Perkraukite programą ir patikrinkite naršyklės konsolę. Pradinė process is not defined išimtis turėtų dingti. Tada patikrinkite specifinį elgesį, kuris priklauso nuo kintamojo – pavyzdžiui, API užklausa turėtų nukreipti į tikėtiną bazinį URL.

Laikinai diagnostikai yra pagrįsta loginti ne slaptažodinę reikšmę, tokią kaip API bazinis URL arba režimas. Vėliau pašalinkite nereikalingus žurnalus, ypač jei jie galėtų atskleisti vidinės konfigūracijos detales.

Ką daryti, jei klaida kyla iš priklausomybės?

Jei paieška jūsų šaltinyje neranda process nuorodos, ištirkite steką. Kelias, esantis node_modules, dažnai reiškia, kad paketas buvo parašytas su Node.js prielaidomis arba naršyklei buvo pasirinktas neteisingas paketo įėjimas.

Saugiausia tvarka yra atnaujinti priklausomybę, patikrinti jos oficialią dokumentaciją dėl naršyklės palaikymo ir pirmenybę teikti naršyklei suderinamam paketui arba eksportui. Bendras polifilas gali paslėpti klaidą, tačiau palikti neišspręstus kitus tik Node skirtus API, todėl tai nėra automatiškai pilnas sprendimas.

Jei priklausomybei reikia tik vienos kompiliavimo laiko konstantos, Vite define parinktis gali atlikti tikslinį globalų pakeitimą. Pavyzdžiui, siaurai apibrėgtą suderinamumo reikalavimą galima išspręsti apibrėžiant tikslų identifikatorių, kurį priklausomybė skaito, vietoj to, kad būtų sukurtas visas process objektas:

import { defineConfig } from 'vite'

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

Tai naudokite tik tada, kai suprantate, ko tikisi priklausomybė. Vite dokumentacija apibūdina define kaip globalią konstantų pakeitimą, kuris yra prieinamas kūrimo metu ir statinis pakeitimas kompiliavimo metu. Nenaudokite jo slaptažodžiams įstumti į naršyklės kodą.

Kada process.env yra galiojantis Vite projekte?

Tai gali būti galiojantis Node pusės kode. Tipiškas pavyzdys yra vite.config.ts. Tačiau dabartinė Vite konfigūracijos dokumentacija daro svarbų skirtumą: .env* failai nėra automatiškai įterpiami į process.env, kai konfigūracijos failas pradinio vertinimo metu. Jei jums reikia tų failų konfigūracijoje, naudokite Vite loadEnv pagalbą.

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

Tuščias prefiksas, perduotas loadEnv, reiškia, kad konfigūracija gali skaityti visas atitinkančias reikšmes. Tai automatiškai jų neatleidžia naršyklei, tačiau bet kuri reikšmė, kurią sąmoningai įdedate į define, gali tapti kliento kodo dalimi. Atskleiskite tik tai, kas yra saugu.

Kas keičiasi SSR atveju?

Vite skiria kliento ir serverio aplinkas. Tipinėje SSR konfigūracijoje serverio kodas gali veikti Node.js, o kliento paketas – naršyklėje. Tai reiškia, kad process.env nuoroda gali būti visiškai galiojanti tik serverio modulyje, bet negaliojanti bendrame modulyje, kuris taip pat vykdomas kliento pusėje.

Jei klaida pasirodo tik po hidratacijos arba naršyklės navigacijos, patikrinkite, ar serveriui orientuota naudinga funkcija nebuvo importuota į kliento kodą. Kur tinkama, naudokite import.meta.env.SSR, kad atskirtumėte vykdymo kontekstus, tačiau taip pat laikykite slaptažodžius ir tik Node skirtus API toliau nuo klientui pasiekiamų šakų ir modulių.

Dažni sprendimai, kurie sukuria naujų problemų

• Pridedant window.process = {}: tai slopina tik kai kuriuos paieškos atvejus ir gali paslėpti tikrąją suderinamumo problemą.
• Nustatant envPrefix į tuščią eilutę: Vite tai aiškiai atmeta, nes tai galėtų atskleisti visus aplinkos kintamuosius kliento kodui.
• Pervardinant slaptažodį, kad jis prasidėtų VITE_: tai padaro slaptažodį tinkamą kliento atskleidimui; vietoj to perkelti slaptažodžiu paremtą darbą į backend.
• Keičiant tik .env failą: taip pat turite atnaujinti kodo nuorodas nuo process.env.NAME iki import.meta.env.VITE_NAME ir paleisti Vite iš naujo.
• Polifilinimas visiems Node globaliems objektams: tai gali padidinti paketo svorį ir vis tiek sugriūti, jei priklausomybė remiasi nepalaikomais Node moduliais arba vykdymo elgsena.

Greitas migracijos pavyzdys

Tarkime, React projektas anksčiau turėjo šį failą:

REACT_APP_API_URL=https://api.example.com

ir šį komponentą:

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

Vite aplinkoje pervardykite kintamąjį:

VITE_API_URL=https://api.example.com

Tada pakeiskite komponentą:

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

Paleiskite dev serverį iš naujo ir vėl išbandykite. Tai yra teisingas sprendimas, kai reikšmė yra saugi atskleisti klientui. Jei senasis kintamasis turi privatų kredencialą, nemigruokite jo tokiu būdu; perkelti privilegijuotą operaciją už serverio endpointo.

Galutinis patikrinimas: kaip žinoti, kad sprendimas yra baigtas?

Pilnas sprendimas turi daugiau nei vieną požymį. Naršyklė neberodo process is not defined; jūsų tikėtini klientui saugūs kintamieji išsprendžiasi į norimas reikšmes; kūrimo ir gamybos režimai veikia kaip tikėtasi; ir gamybos kompiliacija veikia neįvedant naujų Node globalių klaidų.

Paleiskite įprastą kūrimo testą, tada sukurkite gamybos kompiliaciją naudodami projekto kompiliavimo skriptą ir peržiūrėkite arba diekite ją aplinkoje, kuri panaši į gamybą. Jei gedimas pasirodo tik gamyboje, ištirkite režimui specifinius .env failus ir priklausomybių kodo kelius. Jei jis pasirodo tik vienoje priklausomybėje, sutelkite dėmesį į tą priklausomybę, o ne pridėkite vis platesnius priedus visai programai.

Daugumai Vite programų ilgaamžė taisyklė yra paprasta: naudokite import.meta.env kliento konfigūracijai, laikykite slaptažodžius serveryje ir rezervuokite Node globalius objektus, tokius kaip process, kodui, kuris iš tikrųjų veikia Node aplinkoje.