Kako odpraviti napako Uncaught ReferenceError: process is not defined v Vite

Najpomembnejša rešitev je preprosta: če napaka izvira iz vaše kode na strani brskalnika v Vite, zamenjajte process.env z API-jem import.meta.env v Vite. Predmet process pripada Node.js, medtem ko se običajna odjemalska aplikacija Vite izvaja v brskalniku. Vite namesto tega namenoma izpostavlja varne okoljske spremenljivke za odjemalce prek import.meta.env.

Na primer, koda, migrirana iz drugega orodnega veriga, lahko vsebuje process.env.REACT_APP_API_URL. V Vite je tipična zamenjava import.meta.env.VITE_API_URL, pri čemer je VITE_API_URL definirana v datoteki .env. Če napaka izvira iz paketa tretje osebe in ne iz vaše lastne kode, je najboljša rešitev morda posodobitev, zamenjava ali konfiguracija tega paketa, namesto dodajanja splošnega polifila za Node.js.

Ta navodila sledijo trenutni dokumentaciji Vite, dostopni 11. septembra 2026. Avtoritativni viri so dokumentacija Vite o okoljskih spremenljivkah in načinih, dokumentacija o skupnih možnostih in vodič za SSR. Za razliko med kodo v brskalniku in API-ji za izvajanje Node.js si oglejte uradno dokumentacijo o procesu Node.js.

Zakaj Vite sporoča “process is not defined”?

Brskalnik nima vgrajenega globalnega predmeta process iz Node.js. Dokumentacija Node.js opisuje process kot predmet, ki zagotavlja informacije o trenutnem procesu Node.js in nadzor nad njim. Če koda, ki pričakuje ta predmet Node, pride v sveženj za brskalnik, se lahko sklic, kot je process.env.API_URL, ob izvajanju ne uspe z napako ReferenceError: process is not defined.

Odjemalski model Vite je drugačen. Njegov uradni API za okolje izpostavlja vrednosti pod import.meta.env. Vite zagotavlja tudi vgrajene vrednosti, kot so import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL in import.meta.env.SSR.

Katera rešitev velja za vaš projekt?

1. Zamenjajte process.env v kodi za brskalnik

Začnite z iskanjem process.env in goli sklicev na process v izvorni mapi. Če je sklic v kodi, ki se dostavlja v brskalnik, jo pretvorite v Vitejev API za okolje.

Pred:

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

Če potrebujete natančno ime načina in ne boolean za razvoj/produkcijo, uporabite import.meta.env.MODE. Vite dokumentira načine in NODE_ENV kot povezana, a ločena koncepta, zato ne predpostavljajte, da je način po meri, kot je staging, enakovreden spremembi NODE_ENV.

2. Preimenujte okoljske spremenljivke na strani odjemalca s predpono VITE_

Privzeto Vite izpostavi samo tiste okoljske spremenljivke, katerih imena se začnejo s VITE_, v izvorno kodo na strani odjemalca. To je varnostna meja, ki naj zmanjša naključno razkritje skrivnosti na strani strežnika.

Datoteka .env na ravni projekta lahko vsebuje:

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

Koda na strani odjemalca lahko bere import.meta.env.VITE_API_URL in import.meta.env.VITE_APP_NAME. Nepredponjena DB_PASSWORD privzeto ni izpostavljena prek import.meta.env.

Predpone VITE_ ne obravnavajte kot shrambo za skrivnosti. Vite izrecno opozarja, da so vrednosti s predpono vključene v kodo na strani odjemalca. Vse, kar se dostavi v brskalnik, je treba obravnavati kot berljivo za uporabnika. Skrivnosti API, zasebni ključi za podpisovanje, gesla za bazo podatkov in podobne poverilnice spadajo na strežnik, ne v sveženj odjemalca Vite.

Vite naloži .env in .env.local ter datoteke, specifične za način, kot so .env.production ali .env.staging. Vrednosti, specifične za način, imajo prednost pred splošnimi datotekami, medtem ko imajo spremenljivke, ki so že prisotne v okolju ob zagonu Vite, višjo prednost kot vrednosti iz datotek.

3. Ponovno zaženite Vite po spremembi datotek .env

Vite naloži okoljske datoteke ob zagonu. Ko dodate, preimenujete ali uredite vrednost v datoteki .env*, ustavite razvojni strežnik in ga znova zaženite. Samo osvežitev brskalnika lahko pusti, da testirate vrednosti, ki so bile naložene pred spremembo.

# ustavite trenutni razvojni strežnik, nato ga znova zaženite
npm run dev

Prav tako potrdite, da je okoljska datoteka v imeniku, ki ga je Vite konfiguriral za uporabo. Privzeti envDir je koren projekta. Če ima vaš projekt po meri določen root ali envDir, lahko pravilno poimenovana spremenljivka v napačnem imeniku še vedno prikazuje undefined.

4. Preverite rezultat, preden spremenite karkoli drugega

Ponovno naložite aplikacijo in preverite konzolo brskalnika. Izvorna izjema process is not defined bi morala biti odsotna. Nato preverite specifično obnašanje, ki je odvisno od spremenljivke – na primer, zahteva API bi morala ciljati na pričakovano osnovno URL.

Za začasno diagnozo je smiselno zabeležiti ne-skrivno vrednost, kot je osnovni URL API ali način. Nepotrebno beleženje nato odstranite, zlasti če bi lahko razkrilo podrobnosti notranje konfiguracije.

Kaj, če napaka izvira iz odvisnosti?

Če iskanje ne najde sklica na process v vaši kodi, preglejte skladovnico napak. Pot znotraj node_modules pogosto pomeni, da je bil paket napisan s predpostavkami Node.js ali da je bila za uporabo v brskalniku izbrana napačna vstopna točka paketa.

Najvarnejši vrstni red je posodobitev odvisnosti, preverjanje njene uradne dokumentacije za podporo brskalnikom in prednost paketa ali izvoza, združljivega z brskalnikom. Splošni polifil lahko napako skrije, medtem ko ostanejo drugi API-ji, namenjeni samo Node, nerešeni, zato to ni samodejno popolna rešitev.

Če odvisnost potrebuje samo eno konstanto ob prevajanju, lahko možnost define v Vite opravi ciljno globalno zamenjavo. Na primer, ozko usmerjena zahteva po združljivosti je lahko obravnavana z definicijo natančnega identifikatorja, ki ga odvisnost bere, namesto da bi ustvarili celoten predmet process:

import { defineConfig } from 'vite'

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

To uporabite samo, ko razumete, kaj odvisnost pričakuje. Vite dokumentira define kot globalno zamenjavo konstant, ki je na voljo med razvojem in statično zamenjano med gradnjo. Ne uporabljajte ga za vnos skrivnosti v kodo za brskalnik.

Kdaj je process.env veljaven v projektu Vite?

Lahko je veljaven v kodi na strani Node. Pogost primer je vite.config.ts. Vendar pa trenutna konfiguracijska dokumentacija Vite uvaja pomembno razliko: datoteke .env* se ne vbrizgajo samodejno v process.env, medtem ko se konfiguracijska datoteka začetno vrednoti. Če potrebujete te datoteke znotraj konfiguracije, uporabite pomožno funkcijo loadEnv iz Vite.

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

Prazna predpona, posredovana loadEnv, pomeni, da lahko konfiguracija bere vse ujemanje vrednosti. To jih ne izpostavi samodejno brskalniku, vendar lahko vsaka vrednost, ki jo namenoma postavite v define, postane del kode na strani odjemalca. Izpostavite samo tisto, kar je varno.

Kaj se spremeni za SSR?

Vite razlikuje med okolji odjemalca in strežnika. V tipični nastavitvi SSR se lahko koda na strežniku izvaja v Node.js, medtem ko se sveženj odjemalca izvaja v brskalniku. To pomeni, da je lahko sklic na process.env povsem veljaven v modulu, namenjenem samo strežniku, in neveljaven v skupnem modulu, ki se izvaja tudi na odjemalcu.

Če se napaka pojavi šele po hidraciji ali navigaciji v brskalniku, preverite, ali je bil v kodo za odjemalca uvožen pripomoček, namenjen strežniku. Kjer je primerno, uporabite import.meta.env.SSR za razlikovanje izvajalnih kontekstov, vendar skrivnosti in API-je, namenjene samo Node, držite stran od vej in modulov, dostopnih odjemalcu.

Pogoste rešitve, ki ustvarijo nove težave

• Dodajanje window.process = {}: to zatre samo nekatere iskanja in lahko skrije pravi problem združljivosti.
• Nastavitev envPrefix na prazen niz: Vite to izrecno zavrne, ker bi lahko izpostavil vse okoljske spremenljivke kodi na strani odjemalca.
• Preimenovanje skrivnosti, da se začne z VITE_: to jo naredi primerno za izpostavitev odjemalcu; namesto tega premaknite delo, odvisno od skrivnosti, v zaledje.
• Sprememba samo datoteke .env: posodobiti morate tudi sklice v kodi iz process.env.NAME v import.meta.env.VITE_NAME in ponovno zagnati Vite.
• Polifiliranje vseh globalnih predmetov Node: to lahko poveča težo svežnja in še vedno ne uspe, če odvisnost temelji na nepodprtih modulih Node ali obnašanju ob izvajanju.

Hitri primer migracije

Recimo, da je imel projekt React prej to datoteko:

REACT_APP_API_URL=https://api.example.com

in to komponento:

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

V Vite preimenujte spremenljivko:

VITE_API_URL=https://api.example.com

Nato spremenite komponento:

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

Ponovno zaženite razvojni strežnik in znova testirajte. To je prava rešitev, ko je vrednost varno izpostaviti odjemalcu. Če stara spremenljivka vsebuje zasebno poverilnico, je ne migrirajte na ta način; premaknite pooblaščeno operacijo za strežniško končno točko.

Končni pregled: kako veste, da je popravilo dokončano?

Dokončano popravilo ima več znakov. Brskalnik ne poroča več o process is not defined; pričakovane varne spremenljivke za odjemalca se razrešijo na namenjene vrednosti; razvojni in produkcijski načini se obnašajo kot pričakovano; in produkcijska gradnja deluje brez uvajanja novih napak globalnih predmetov Node.

Izvedite običajni razvojni test, nato ustvarite produkcijsko gradnjo s skriptom za gradnjo vašega projekta in jo predogledajte ali namestite v okolju, ki spominja na produkcijo. Če se napaka pojavi samo v produkciji, preglejte datoteke .env, specifične za način, in kode poti odvisnosti. Če se pojavi samo v eni odvisnosti, se osredotočite na to odvisnost, namesto da bi celotni aplikaciji dodajali vse širše prevleke.

Za večino aplikacij Vite je trajno pravilo preprosto: uporabite import.meta.env za konfiguracijo odjemalca, skrivnosti držite na strežniku in globalne predmete Node, kot je process, rezervirajte za kodo, ki se dejansko izvaja v okolju Node.