Slik løser du Uncaught ReferenceError: process is not defined i Vite
Den viktigste løsningen er enkel: Hvis feilen kommer fra din nettleserbaserte Vite-kode, erstatt process.env med Vites import.meta.env-API. process-objektet tilhører Node.js, mens en vanlig Vite-klientapplikasjon kjører i nettleseren. Vite eksponerer bevisst klientsikre miljøvariabler gjennom import.meta.env i stedet.
For eksempel kan kode migrert fra et annet verktøykjede inneholde process.env.REACT_APP_API_URL. I Vite er en typisk erstatning import.meta.env.VITE_API_URL, der VITE_API_URL er definert i en .env-fil. Hvis feilen kommer fra en tredjepartspakke og ikke din egen kildekode, kan den beste løsningen være å oppdatere, erstatte eller konfigurere den pakkene i stedet for å legge til en generell Node.js-polyfill.
Nettleseren har ingen innebygd Node.js process-global. Nodes dokumentasjon beskriver process som et objekt som gir informasjon om og kontroll over den gjeldende Node.js-prosessen. Hvis kode som forventer det Node-objektet havner i en nettleserpakke, kan en referanse som process.env.API_URL feile under kjøring med ReferenceError: process is not defined.
Vites klientmodell er forskjellig. Dets offisielle miljø-API eksponerer verdier under import.meta.env. Vite gir også innebygde verdier som import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL og import.meta.env.SSR.
AI-generert illustrasjon: et typisk nettleserkonsollsymptom når klientkode refererer til Node.js process-globalen.
Hvilken løsning gjelder for prosjektet ditt?
Hva du finner
Beste første løsning
Din egen React-, Vue-, Svelte- eller vanilla klientkode bruker process.env
Erstatt den med import.meta.env og bruk en variabel med VITE_-prefiks.
Du migrerte fra Create React App og bruker fortsatt REACT_APP_*
Bytt navn på klientvariablene til VITE_* og oppdater alle referanser.
Du bruker bare process.env.NODE_ENV for å skille mellom utvikling og produksjon
Foretrekk import.meta.env.DEV, import.meta.env.PROD eller import.meta.env.MODE i nettleserkode.
Stakksporet peker inn i node_modules
Sjekk om avhengigheten har en nettleserkompatibel utgivelse eller bygging før du legger til kompatibilitets-shims.
Referansen er inne i vite.config.ts eller annet Node-basert verktøy
process.env kan være gyldig der; bruk Vites loadEnv når du trenger verdier fra .env*-filer under konfigurasjonsutvikling.
Koden er server-only SSR-kode
Node-globaler kan være hensiktsmessige på serveren, men delte moduler må ikke utføre Node-only-kode i nettleseren.
1. Erstatt process.env i nettleserkode
Begynn med å søke i kildekatalogen din etter process.env og nakne referanser til process. Hvis referansen er i kode som leveres til nettleseren, konverter den til Vites miljø-API.
const apiUrl = import.meta.env.VITE_API_URL
if (import.meta.env.DEV) {
console.log('Development mode')
}
Hvis du trenger det nøyaktige modusnavnet i stedet for en utviklings/produksjons-boolean, bruk import.meta.env.MODE. Vite dokumenterer moduser og NODE_ENV som relaterte men separate konsepter, så anta ikke at en egendefinert modus som staging er det samme som å endre NODE_ENV.
AI-generert illustrasjon: den anbefalte klientendringen er å lese Vite-variabler gjennom import.meta.env.
2. Bytt navn på klientmiljøvariabler med VITE_-prefikset
Som standard eksponerer Vite bare miljøvariabler hvis navn starter med VITE_ til klientkildekode. Dette er en sikkerhetsgrense ment for å redusere utilsiktet eksponering av server-side hemmeligheter.
Klientkode kan lese import.meta.env.VITE_API_URL og import.meta.env.VITE_APP_NAME. Den uprefiksede DB_PASSWORD eksponeres ikke gjennom import.meta.env som standard.
Behandle ikke VITE_-prefikset som hemmelig lagring. Vite advarer uttrykkelig mot at prefikserte verdier buntles inn i klientkode. Alt som leveres til en nettleser bør betraktes som lesbart av brukeren. API-hemmeligheter, private signaturnøkler, databasepassord og lignende legitimasjoner hører hjemme på en server, ikke i en Vite-klientbunt.
Vite laster .env og .env.local, samt modusspesifikke filer som .env.production eller .env.staging. Modusspesifikke verdier har forrang over generiske filer, mens variabler allerede til stede i miljøet når Vite starter, har høyere prioritet enn verdier fra filene.
3. Start Vite på nytt etter endringer i .env-filer
Vite laster miljøfiler når den starter. Etter at du har lagt til, byttet navn på eller redigert en verdi i en .env*-fil, stopp utviklingsserveren og start den på nytt. En ren nettleseroppdatering kan la deg teste verdier som ble lastet før endringen.
# stop the current dev server, then start it again
npm run dev
Bekreft også at miljøfilen er i katalogen Vite er konfigurert til å bruke. Standard envDir er prosjektroten. Hvis prosjektet ditt har en egendefinert root eller envDir, kan en korrekt navngitt variabel i feil katalog fortsatt vises som undefined.
4. Verifiser resultatet før du endrer noe annet
Last inn applikasjonen på nytt og sjekk nettleserkonsollen. Den opprinnelige process is not defined-unntaket skal være borte. Verifiser deretter den spesifikke atferden som avhenger av variabelen – for eksempel bør en API-forespørsel målrette mot den forventede base-URL-en.
For midlertidig diagnose er det rimelig å logge en ikke-hemmelig verdi som API-base-URL-en eller modusen. Fjern unødvendig logging etterpå, spesielt hvis den kan eksponere interne konfigurasjonsdetaljer.
AI-generert illustrasjon: verifiser at nettleserkonsollen er ren og at den tiltenkte ikke-hemmelige konfigurasjonsverdien er tilgjengelig.
Hva om feilen kommer fra en avhengighet?
Hvis søket ditt ikke finner noen process-referanse i kilden din, inspiser stakksporet. En sti inne i node_modules betyr ofte at en pakke ble skrevet med Node.js-antakelser, eller at feil pakkeoppføring ble valgt for nettleserbruk.
Den sikreste rekkefølgen er å oppdatere avhengigheten, sjekke dens offisielle dokumentasjon for nettleserstøtte, og foretrekke en nettleserkompatibel pakke eller eksport. En generell polyfill kan få en feil til å forsvinne mens andre Node-only-API-er forblir uløste, så det er ikke automatisk en komplett løsning.
Hvis en avhengighet bare trenger én kompileringskonstant, kan Vites define-alternativ utføre en målrettet global erstatning. For eksempel kan et avgrenset kompatibilitetskrav håndteres ved å definere den nøyaktige identifikatoren avhengigheten leser, i stedet for å fabrikere et fullstendig process-objekt:
Bruk dette bare når du forstår hva avhengigheten forventer. Vite dokumenterer define som en global konstanterstatning som er tilgjengelig under utvikling og statisk erstattes under bygging. Bruk det ikke for å dytte hemmeligheter inn i nettleserkode.
Når er process.env gyldig i et Vite-prosjekt?
Det kan være gyldig i Node-side-kode. Et vanlig eksempel er vite.config.ts. Imidlertid gjør Vites gjeldende konfigurasjonsdokumentasjon en viktig distinksjon: .env*-filer injiseres ikke automatisk i process.env mens konfigurasjonsfilen først blir evaluert. Hvis du trenger disse filene inne i konfigurasjonen, bruk Vites loadEnv-hjelper.
Det tomme prefikset sendt til loadEnv betyr at konfigurasjonen kan lese alle matchede verdier. Det eksponerer dem ikke automatisk for nettleseren, men enhver verdi du bevisst plasserer i define, kan bli en del av klientkoden. Eksponer bare det som er trygt.
Hva endres for SSR?
Vite skiller mellom klient- og servermiljøer. I et typisk SSR-oppsett kan serverkode kjøre i Node.js mens klientbunten kjører i nettleseren. Det betyr at en process.env-referanse kan være helt gyldig i en server-only-modul og ugyldig i en delt modul som også utføres på klienten.
Hvis feilen dukker opp bare etter hydrering eller nettlesernavigasjon, sjekk om et serverorientert verktøy ble importert inn i klientkode. Bruk import.meta.env.SSR der det er hensiktsmessig for å skille utførelseskontekster, men hold også hemmeligheter og Node-only-API-er utenfor klient-tilgjengelige grener og moduler.
Vanlige løsninger som skaper nye problemer
Å legge til window.process = {}: dette undertrykker bare noen oppslag og kan skjule det virkelige kompatibilitetsproblemet.
Å sette envPrefix til en tom streng: Vite avviser dette uttrykkelig fordi det kan eksponere alle miljøvariabler til klientkode.
Å bytte navn på en hemmelighet til å starte med VITE_: det gjør hemmeligheten kvalifisert for klienteksponering; flytt hemmelighetsavhengig arbeid til en backend i stedet.
Å endre bare .env-filen: du må også oppdatere kodereferanser fra process.env.NAME til import.meta.env.VITE_NAME og starte Vite på nytt.
Å polyfille alle Node-globaler: dette kan legge til buntvekt og fortsatt feile hvis en avhengighet er avhengig av ikke-støttede Node-moduler eller runtime-atferd.
Et raskt migreringseksempel
La oss si at et React-prosjekt tidligere hadde denne filen:
Start utviklingsserveren på nytt og test igjen. Dette er den riktige løsningen når verdien er trygg å eksponere til klienten. Hvis den gamle variabelen inneholder en privat legitimasjon, ikke migrer den på denne måten; flytt den privilegerte operasjonen bak en server-endepunkt.
Endelig sjekk: Hvordan vet du at løsningen er fullført?
En komplett løsning har mer enn ett tegn. Nettleseren rapporterer ikke lenger process is not defined; dine forventede klientsikre variabler løses til de tiltenkte verdiene; utviklings- og produksjonsmoduser oppfører seg som forventet; og et produksjonsbygg fungerer uten å introdusere nye Node-globalfeil.
Kjør din normale utviklingstest, opprett deretter et produksjonsbygg med prosjektets byggeskript og forhåndsvis eller distribuer det i et miljø som ligner produksjon. Hvis feilen dukker opp bare i produksjon, inspiser modusspesifikke .env-filer og avhengighetskodestier. Hvis den dukker opp bare i én avhengighet, fokuser på den avhengigheten i stedet for å legge til stadig bredere shims til hele appen.
For de fleste Vite-applikasjoner er den varige regelen rett frem: bruk import.meta.env for klientkonfigurasjon, hold hemmeligheter på serveren, og reserver Node-globaler som process for kode som faktisk kjører i et Node-miljø.