Kā novērst kļūdu “Uncaught ReferenceError: process is not defined” programmā Vite

Svarīgākais risinājums ir vienkāršs: ja kļūda rodas no jūsu pārlūka puses Vite koda, aizstājiet process.env ar Vite import.meta.env API. process objekts pieder Node.js, savukārt parasta Vite klienta lietojumprogramma darbojas pārlūkā. Vite apzināti nodrošina klientam drošus vides mainīgos, izmantojot import.meta.env.

Piemēram, kods, kas migrēts no cita rīku kopuma, var saturēt process.env.REACT_APP_API_URL. Vite tipiska aizstāšana ir import.meta.env.VITE_API_URL, kur VITE_API_URL ir definēts .env failā. Ja kļūda rodas no trešās puses pakotnes, nevis no jūsu pašu avota, labākais risinājums var būt šīs pakotnes atjaunināšana, aizstāšana vai konfigurēšana, nevis vispārīga Node.js polifila pievienošana.

Šie norādījumi atbilst pašreizējai Vite dokumentācijai, kas bija pieejama 2026. gada 11. septembrī. Autoritatīvie atsauces materiāli ir Vite Vides mainīgo un režīmu dokumentācija, Kopīgo opciju dokumentācija un SSR ceļvedis. Lai saprastu atšķirību starp pārlūka kodu un Node.js izpildes laika API, skatiet oficiālo Node.js process dokumentāciju.

Kāpēc Vite rāda kļūdu “process is not defined”?

Pārlūkā nav iebūvēta Node.js process globālā mainīgā. Node dokumentācija apraksta process kā objektu, kas sniedz informāciju par pašreizējo Node.js procesu un ļauj to kontrolēt. Ja kods, kas sagaida šo Node objektu, nonāk pārlūka pakotnē, atsauce, piemēram, process.env.API_URL, izpildes laikā var neizdoties ar kļūdu ReferenceError: process is not defined.

Vite klienta modelis ir atšķirīgs. Tā oficiālā vides API eksponē vērtības zem import.meta.env. Vite nodrošina arī iebūvētas vērtības, piemēram, import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL un import.meta.env.SSR.

Kuris risinājums attiecas uz jūsu projektu?

1. Aizstājiet process.env pārlūka kodā

Sāciet, meklējot avota direktorijā process.env un vienkāršas atsauces uz process. Ja atsauce ir kodā, kas tiek piegādāts pārlūkam, pārveidojiet to par Vite vides API.

Pirms:

const apiUrl = process.env.REACT_APP_API_URL

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

Pēc:

const apiUrl = import.meta.env.VITE_API_URL

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

Ja jums ir nepieciešams precīzs režīma nosaukums, nevis izstrādes/ražošanas boolean vērtība, izmantojiet import.meta.env.MODE. Vite dokumentācijā režīmi un NODE_ENV ir aprakstīti kā saistīti, bet atsevišķi jēdzieni, tāpēc neuzskatiet, ka pielāgots režīms, piemēram, staging, ir līdzvērtīgs NODE_ENV maiņai.

2. Pārdēvējiet klienta vides mainīgos ar prefiksu VITE_

Pēc noklusējuma Vite eksponē tikai tos vides mainīgos, kuru nosaukumi sākas ar VITE_, klienta avota kodā. Tas ir drošības robežšķirtne, kas paredzēta, lai samazinātu nejaušu servera puses noslēpumu atklāšanu.

Projekta līmeņa .env failā var būt:

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

Klienta kods var lasīt import.meta.env.VITE_API_URL un import.meta.env.VITE_APP_NAME. Neprefiksētais DB_PASSWORD pēc noklusējuma netiek eksponēts, izmantojot import.meta.env.

Nekonsiderējiet VITE_ prefiksu kā noslēpumu glabāšanu. Vite skaidri brīdina, ka prefiksētās vērtības tiek iekļautas klienta puses kodā. Jebkas, kas tiek piegādāts pārlūkam, ir jāuzskata par lietotājam lasāmu. API noslēpumi, privātās parakstīšanas atslēgas, datubāzes paroles un līdzīgi akreditācijas dati pieder serverim, nevis Vite klienta pakotnei.

Vite ielādē .env un .env.local, kā arī režīmam specifiskus failus, piemēram, .env.production vai .env.staging. Režīmam specifiskās vērtības ir prioritārākas par vispārīgiem failiem, savukārt mainīgie, kas jau ir vidē, kad Vite startē, ir prioritārāki par vērtībām no failiem.

3. Pārstartējiet Vite pēc .env failu maiņas

Vite ielādē vides failus, kad tas startē. Pēc tam, kad esat pievienojis, pārdēvējis vai rediģējis vērtību .env* failā, apturiet izstrādes serveri un startējiet to vēlreiz. Vienkārša pārlūka atsvaidzināšana var atstāt jūs testēt vērtības, kas tika ielādētas pirms izmaiņām.

# apturiet pašreizējo dev serveri, tad startējiet to vēlreiz
npm run dev

Tāpat pārliecinieties, ka vides fails atrodas direktorijā, kuru Vite ir konfigurējis izmantošanai. Noklusējuma envDir ir projekta sakne. Ja jūsu projektam ir pielāgots root vai envDir, pareizi nosaukts mainīgais nepareizā direktorijā joprojām var parādīties kā undefined.

4. Pārbaudiet rezultātu, pirms maināt kaut ko citu

Pārlādējiet lietojumprogrammu un pārbaudiet pārlūka konsoli. Sākotnējai process is not defined izņēmumam jābūt pazudušam. Pēc tam pārbaudiet konkrēto uzvedību, kas ir atkarīga no mainīgā – piemēram, API pieprasījumam jānorāda uz paredzēto bāzes URL.

Īslaicīgai diagnostikai ir saprātīgi žurnalēt neslēptu vērtību, piemēram, API bāzes URL vai režīmu. Pēc tam noņemiet nevajadzīgo žurnalēšanu, īpaši, ja tas varētu atklāt iekšējas konfigurācijas detaļas.

Ko darīt, ja kļūda nāk no atkarības?

Ja jūsu meklējumos nav atrasta neviena process atsauce jūsu avotā, pārbaudiet steka izsekošanu. Ceļš, kas atrodas node_modules, bieži nozīmē, ka pakotne tika rakstīta ar Node.js pieņēmumiem vai pārlūka lietošanai tika izvēlēta nepareiza pakotnes ieeja.

Drošākā secība ir atjaunināt atkarību, pārbaudīt tās oficiālo dokumentāciju par pārlūka atbalstu un dot priekšroku pārlūkam saderīgai pakotnei vai eksportam. Vispārīgs polifils var likt kļūdai pazust, atstājot citas tikai Node API neatrisinātas, tāpēc tas automātiski nav pilnīgs risinājums.

Ja atkarībai ir nepieciešama tikai viena kompilācijas laika konstante, Vite define opcija var veikt mērķtiecīgu globālu aizstāšanu. Piemēram, šauri ierobežotu saderības prasību var apstrādāt, definējot precīzu identifikatoru, ko atkarība lasa, nevis izveidojot pilnu process objektu:

import { defineConfig } from 'vite'

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

Izmantojiet to tikai tad, kad saprotat, ko atkarība sagaida. Vite dokumentācijā define ir aprakstīts kā globāla konstantes aizstāšana, kas ir pieejama izstrādes laikā un statiski aizstāta būves laikā. Neizmantojiet to, lai ievietotu noslēpumus pārlūka kodā.

Kad process.env ir derīgs Vite projektā?

Tas var būt derīgs Node puses kodā. Biežs piemērs ir vite.config.ts. Tomēr Vite pašreizējā konfigurācijas dokumentācija izdara svarīgu atšķirību: .env* faili netiek automātiski ievadīti process.env, kamēr konfigurācijas fails sākotnēji tiek izvērtēts. Ja jums šie faili ir nepieciešami konfigurācijā, izmantojiet Vite loadEnv palīgfunkciju.

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

Tukšais prefikss, kas nodots loadEnv, nozīmē, ka konfigurācija var lasīt visas sakritušās vērtības. Tas automātiski neeksponē tās pārlūkam, bet jebkura vērtība, ko jūs apzināti ievietojat define, var kļūt par daļu no klienta koda. Eksponējiet tikai to, kas ir droši.

Kas mainās SSR gadījumā?

Vite atšķir klienta un servera vides. Tipiskā SSR iestatījumā servera kods var darboties Node.js, savukārt klienta pakotne darbojas pārlūkā. Tas nozīmē, ka process.env atsauce var būt pilnībā derīga tikai servera modulī un nederīga kopīgā modulī, kas tiek izpildīts arī klientā.

Ja kļūda parādās tikai pēc hidrācijas vai pārlūka navigācijas, pārbaudiet, vai uz klienta kodu netika importēta serverim paredzēta utilīta. Izmantojiet import.meta.env.SSR, kur tas ir piemērots, lai atšķirtu izpildes kontekstus, bet arī turiet noslēpumus un tikai Node API ārpus klientam sasniedzamām zarām un moduļiem.

Bieži risinājumi, kas rada jaunas problēmas

• Pievienojot window.process = {}: tas apspiež tikai dažas meklēšanas darbības un var slēpt īsto saderības problēmu.
• Iestatot envPrefix uz tukšu virkni: Vite to skaidri noraida, jo tas varētu eksponēt visus vides mainīgos klienta kodā.
• Pārdēvējot noslēpumu, lai tas sāktos ar VITE_: tas padara noslēpumu piemērotu klienta eksponēšanai; tā vietā pārvietojiet ar noslēpumu saistīto darbu uz backend.
• Mainot tikai .env failu: jums ir jāatjaunina arī koda atsauces no process.env.NAME uz import.meta.env.VITE_NAME un jāpārstartē Vite.
• Polifilējot visus Node globālos mainīgos: tas var palielināt pakotnes svaru un joprojām neizdoties, ja atkarība paļaujas uz neatbalstītiem Node moduļiem vai izpildes laika uzvedību.

Ātrs migrācijas piemērs

Pieņemsim, ka React projektā iepriekš bija šāds fails:

REACT_APP_API_URL=https://api.example.com

un šāds komponents:

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

Vite pārdēvējiet mainīgo:

VITE_API_URL=https://api.example.com

Tad mainiet komponentu:

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

Pārstartējiet dev serveri un testējiet vēlreiz. Tas ir pareizais risinājums, ja vērtība ir droši eksponējama klientam. Ja vecais mainīgais satur privātu akreditācijas datu, nemigrējiet to šādā veidā; pārvietojiet privilēģēto darbību aiz servera endpoint.

Beigu pārbaude: kā zināt, ka risinājums ir pabeigts?

Pilnīgam risinājumam ir vairāk nekā viena pazīme. Pārlūks vairs neziņo par process is not defined; jūsu paredzētie klientam drošie mainīgie atrisina paredzētās vērtības; izstrādes un ražošanas režīmi uzvedas kā paredzēts; un ražošanas būve darbojas, neieviešot jaunas Node globālo mainīgo kļūdas.

Palaidiet savu parasto izstrādes testu, pēc tam izveidojiet ražošanas būvi ar projekta būves skriptu un priekšskatiet vai izvietojiet to vidē, kas līdzinās ražošanai. Ja kļūme parādās tikai ražošanā, pārbaudiet režīmam specifiskos .env failus un atkarību koda ceļus. Ja tā parādās tikai vienā atkarībā, koncentrējieties uz šo atkarību, nevis pievienojiet arvien plašākus shims visai lietotnei.

Vairumam Vite lietojumprogrammu noturīgais noteikums ir vienkāršs: izmantojiet import.meta.env klienta konfigurācijai, turiet noslēpumus serverī un rezervējiet Node globālos mainīgos, piemēram, process, kodam, kas patiešām darbojas Node vidē.