Så här åtgärdar du Uncaught ReferenceError: process is not defined i Vite

Den viktigaste åtgärden är enkel: om felet kommer från din klientbaserade Vite-kod, ersätt process.env med Vites import.meta.env-API. process-objektet tillhör Node.js, medan en vanlig Vite-klientapplikation körs i webbläsaren. Vite exponerar medvetet klientsäkra miljövariabler via import.meta.env istället.

Till exempel kan kod som migrerats från ett annat verktygskedja innehålla process.env.REACT_APP_API_URL. I Vite är en typisk ersättning import.meta.env.VITE_API_URL, där VITE_API_URL definieras i en .env-fil. Om felet kommer från ett tredjepartspaket snarare än din egen källkod, kan den bästa åtgärden vara att uppdatera, ersätta eller konfigurera det paketet istället för att lägga till en allmän Node.js-polyfill.

Denna vägledning följer den aktuella Vite-dokumentationen som var tillgänglig den 11 september 2026. De auktoritativa referenserna är Vites dokumentation om miljövariabler och lägen, dokumentation om delade alternativ och SSR-guide. För distinktionen mellan webbläsarkod och Node.js-runtime-API:er, se den officiella Node.js process-dokumentationen.

Varför säger Vite “process is not defined”?

Webbläsaren har ingen inbyggd Node.js process-global. Nodes dokumentation beskriver process som ett objekt som tillhandahåller information om och kontroll över den aktuella Node.js-processen. Om kod som förväntar sig det Node-objektet når en webbläsarbunt, kan en referens som process.env.API_URL misslyckas vid körning med ReferenceError: process is not defined.

Vites klientmodell är annorlunda. Dess officiella miljö-API exponerar värden under import.meta.env. Vite tillhandahåller också inbyggda värden som import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL och import.meta.env.SSR.

Vilken åtgärd gäller för ditt projekt?

1. Ersätt process.env i webbläsarkod

Börja med att söka i din källkatalog efter process.env och nakna referenser till process. Om referensen finns i kod som levereras till webbläsaren, konvertera den till Vites miljö-API.

Före:

const apiUrl = process.env.REACT_APP_API_URL

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

Efter:

const apiUrl = import.meta.env.VITE_API_URL

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

Om du behöver det exakta lägesnamnet istället för en utvecklings-/produktionsboolesk, använd import.meta.env.MODE. Vite dokumenterar lägen och NODE_ENV som relaterade men separata koncept, så anta inte att ett anpassat läge som staging är ekvivalent med att ändra NODE_ENV.

2. Byt namn på klientmiljövariabler med VITE_-prefixet

Som standard exponerar Vite endast miljövariabler vars namn börjar med VITE_ till klientkällkod. Detta är en säkerhetsgräns avsedd att minska oavsiktlig exponering av serversidans hemligheter.

En projektnivå .env-fil kan innehålla:

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

Klientkod kan läsa import.meta.env.VITE_API_URL och import.meta.env.VITE_APP_NAME. Den oprefixade DB_PASSWORD exponeras inte via import.meta.env som standard.

Behandla inte VITE_-prefixet som hemlighetslagring. Vite varnar uttryckligen för att prefixade värden bundlas in i klientkoden. Allt som levereras till en webbläsare bör betraktas som läsbar av användaren. API-hemligheter, privata signeringsnycklar, databaslösenord och liknande autentiseringsuppgifter hör hemma på en server, inte i ett Vite-klientbunt.

Vite laddar .env och .env.local, plus läges-specifika filer som .env.production eller .env.staging. Läges-specifika värden har företräde framför generiska filer, medan variabler som redan finns i miljön när Vite startar har högre prioritet än värden från filerna.

3. Starta om Vite efter att ha ändrat .env-filer

Vite laddar miljöfiler när det startar. Efter att du har lagt till, bytt namn på eller redigerat ett värde i en .env*-fil, stoppa utvecklingsservern och starta den igen. Enbart en webbläsaruppdatering kan lämna dig med att testa värden som laddades innan ändringen.

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

Bekräfta också att miljöfilen finns i den katalog som Vite är konfigurerat att använda. Den standard envDir är projektroten. Om ditt projekt har en anpassad root eller envDir, kan en korrekt namngiven variabel i fel katalog fortfarande visas som undefined.

4. Verifiera resultatet innan du ändrar något annat

Ladda om applikationen och kontrollera webbläsarkonsolen. Det ursprungliga undantaget process is not defined bör vara borta. Verifiera sedan det specifika beteendet som beror på variabeln – till exempel bör en API-förfrågan rikta in sig mot den förväntade bas-URL:en.

För tillfällig diagnos är det rimligt att logga ett icke-hemligt värde som API-bas-URL:en eller läget. Ta bort onödig loggning efteråt, särskilt om det kan exponera interna konfigurationsdetaljer.

Vad händer om felet kommer från ett beroende?

Om din sökning inte hittar någon process-referens i din källa, inspektera stackspåret. En sökväg inuti node_modules betyder ofta att ett paket skrevs med Node.js-antaganden eller att fel paketpost valdes för webbläsaranvändning.

Den säkraste ordningen är att uppdatera beroendet, kontrollera dess officiella dokumentation för webbläsarstöd och föredra ett webbläsarkompatibelt paket eller export. En allmän polyfill kan få ett fel att försvinna medan andra Node-only-API:er förblir olösta, så det är inte automatiskt en komplett åtgärd.

Om ett beroende bara behöver en konstant vid kompileringstid, kan Vites define-alternativ utföra en riktad global ersättning. Till exempel kan ett snävt avgränsat kompatibilitetskrav hanteras genom att definiera den exakta identifieraren som beroendet läser istället för att fabricera ett fullständigt process-objekt:

import { defineConfig } from 'vite'

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

Använd detta endast när du förstår vad beroendet förväntar sig. Vite dokumenterar define som en global konstantersättning som är tillgänglig under utveckling och statiskt ersätts under bygget. Använd det inte för att trycka in hemligheter i webbläsarkoden.

När är process.env giltigt i ett Vite-projekt?

Det kan vara giltigt i Node-sidokod. Ett vanligt exempel är vite.config.ts. Men Vites nuvarande konfigurationsdokumentation gör en viktig distinktion: .env*-filer injiceras inte automatiskt i process.env medan konfigurationsfilen initialt utvärderas. Om du behöver dessa filer inne i konfigurationen, använd Vites loadEnv-hjälpfunktion.

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

Det tomma prefixet som skickas till loadEnv innebär att konfigurationen kan läsa alla matchade värden. Det exponerar dem inte automatiskt för webbläsaren, men varje värde du medvetet placerar i define kan bli en del av klientkoden. Exponera endast det som är säkert.

Vad ändras för SSR?

Vite skiljer på klient- och servermiljöer. I en typisk SSR-installation kan serverkod köras i Node.js medan klientbunten körs i webbläsaren. Det innebär att en process.env-referens kan vara helt giltig i en server-only-modul och ogiltig i en delad modul som också exekveras på klienten.

Om felet dyker upp först efter hydrering eller webbläsarnavigering, kontrollera om ett serverorienterat verktyg importerades in i klientkoden. Använd import.meta.env.SSR där det är lämpligt för att skilja på exekveringskontexter, men håll också hemligheter och Node-only-API:er utanför klient-åtkomliga grenar och moduler.

Vanliga åtgärder som skapar nya problem

• Lägga till window.process = {}: detta undertrycker endast vissa uppslag och kan dölja det verkliga kompatibilitetsproblemet.
• Ställa in envPrefix till en tom sträng: Vite avvisar detta uttryckligen eftersom det kunde exponera varje miljövariabel för klientkoden.
• Byta namn på en hemlighet så att den börjar med VITE_: det gör hemligheten kvalificerad för klientexponering; flytta hemlighetsberoende arbete till en backend istället.
• Ändra endast .env-filen: du måste också uppdatera kodreferenser från process.env.NAME till import.meta.env.VITE_NAME och starta om Vite.
• Polyfilla varje Node-global: detta kan lägga till buntvikt och fortfarande misslyckas om ett beroende förlitar sig på osupportade Node-moduler eller runtime-beteende.

Ett snabbt migreringsexempel

Anta att ett React-projekt tidigare hade denna fil:

REACT_APP_API_URL=https://api.example.com

och denna komponent:

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

I Vite, byt namn på variabeln:

VITE_API_URL=https://api.example.com

Ändra sedan komponenten:

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

Starta om utvecklingsservern och testa igen. Detta är den rätta lösningen när värdet är säkert att exponera för klienten. Om den gamla variabeln innehåller ett privat autentiseringsuppgift, migrera den inte på detta sätt; flytta den privilegierade operationen bakom en serverendpoint.

Slutlig kontroll: hur vet du att åtgärden är komplett?

En komplett åtgärd har mer än ett tecken. Webbläsaren rapporterar inte längre process is not defined; dina förväntade klientsäkra variabler löser upp till de avsedda värdena; utvecklings- och produktionslägen beter sig som förväntat; och ett produktionsbygge fungerar utan att introducera nya Node-globala fel.

Kör ditt normala utvecklingstest, skapa sedan ett produktionsbygge med ditt projekts byggs script och förhandsgranska eller distribuera det i en miljö som liknar produktion. Om felet dyker upp endast i produktion, inspektera läges-specifika .env-filer och beroendekodvägar. Om det dyker upp endast i ett beroende, fokusera på det beroendet istället för att lägga till allt bredare shimmar till hela appen.

För de flesta Vite-applikationer är den bestående regeln enkel: använd import.meta.env för klientkonfiguration, håll hemligheter på servern, och reservera Node-globaler som process för kod som faktiskt körs i en Node-miljö.