Hvernig á að laga Uncaught ReferenceError: process is not defined í Vite

Algengasta lausnin er einföld: ef villan kemur frá Vite kóða sem keyrir í vafra, skiptu út process.env fyrir import.meta.env API Vite. process hluturinn tilheyrir Node.js, en venjuleg Vite viðskiptisforrit keyra í vafra. Vite gefur viljandi aðgang að umhverfisbreytum sem eru öruggar fyrir viðskiptisforrit í gegnum import.meta.env í staðinn.

Til dæmis gæti kóði sem fluttur er frá öðru verkfæra innihaldið process.env.REACT_APP_API_URL. Í Vite er dæmigerð staðgengill import.meta.env.VITE_API_URL, þar sem VITE_API_URL er skilgreint í .env skrá. Ef villan kemur frá þriðja aðila pakka frekar en eigin kóða, er besta lausnin oft að uppfæra, skipta um eða stilla þann pakkann frekar en að bæta við almennum Node.js polyfill.

Þessi leiðbeining fylgja núverandi Vite skjölun sem var í boði þann 11. september 2026. Áreiðanlegar tilvísanir eru Env Variables and Modes skjölunin, Shared Options skjölunin og SSR leiðbeiningarnar hjá Vite. Fyrir muninn á vafra kóða og Node.js keyrsluumhverfi, sjá opinberu Node.js process skjölunina.

Af hverju segir Vite „process is not defined“?

Vafri hefur ekki innbyggða Node.js process heildarbreytu. Skjölun Node lýsir process sem hlut sem veitir upplýsingar um og stjórn á núverandi Node.js ferli. Ef kóði sem búist við þessum Node hlut nær í vafra bundle, getur tilvísun eins og process.env.API_URL mistekist við keyrslu með ReferenceError: process is not defined.

Viðskiptis líkan Vite er öðruvísi. Opinber umhverfis API þess gefur gildi undir import.meta.env. Vite veitir einnig innbyggð gildi eins og import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL og import.meta.env.SSR.

Hvaða lagfæring á við um verkefnið þitt?

1. Skiptu út process.env í vafra kóða

Byrjaðu á að leita í source möppunni þinni eftir process.env og berum tilvísunum á process. Ef tilvísunin er í kóða sem afhentur er í vafra, umbreyttu henni í umhverfis API Vite.

Áður:

const apiUrl = process.env.REACT_APP_API_URL

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

Eftir:

const apiUrl = import.meta.env.VITE_API_URL

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

Ef þú þarft nákvæmt heiti á ham frekar en þróunar/framleiðslu boolean, notaðu import.meta.env.MODE. Vite skjalsetur ham og NODE_ENV sem tengd en aðskilin hugtök, svo ekki gera ráð fyrir að sérsniðinn hamur eins og staging sé jafngilt því að breyta NODE_ENV.

2. Endurnefndu viðskiptis umhverfisbreytur með VITE_ forskeytinu

Sjálfgefið gefur Vite aðeins aðgang að umhverfisbreytum sem heiti þeirra byrja á VITE_ til viðskiptis source kóða. Þetta er öryggis mörk sem ætlað er að minnka óviljaða afhjúpun á server-hliðar leyndarmálum.

Verkefnis-stig .env skrá gæti innihaldið:

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

Viðskiptis kóði getur lesið import.meta.env.VITE_API_URL og import.meta.env.VITE_APP_NAME. Óforskeytta DB_PASSWORD er ekki afhjúpað í gegnum import.meta.env sjálfgefið.

Ekki meðhöndla VITE_ forskeytið sem leyndarmál geymslu. Vite varar sérstaklega við að forskeytt gildi eru bundin inn í viðskiptis kóða. Allt sem afhent er í vafra ætti að teljast lesanlegt af notandanum. API leyndarmál, einkaleyfi fyrir undirritun, gagnagrunns lykilorð og svipaðar auðkennisupplýsingar eiga heima á server, ekki í Vite viðskiptis bundle.

Vite hleður .env og .env.local, auk ham-sérstakra skráa eins og .env.production eða .env.staging. Ham-sérstök gildi hafa forgang fram yfir almennar skrár, en breytur sem eru nú þegar til staðar í umhverfinu þegar Vite byrjar hafa hærri forgang en gildi úr skránum.

3. Endurræstu Vite eftir breytingar á .env skránum

Vite hleður umhverfisskrár þegar það byrjar. Eftir að þú bætir við, endurnefnir eða breytir gildi í .env* skrá, stoppaðu þróunar serverinn og ræstu hann aftur. Einungis vafra endurhleðsla gæti skilið þig við að prófa gildi sem voru hlaðin áður en breytingin var gerð.

# stoppaðu núverandi dev server, ræstu hann svo aftur
npm run dev

Staðfestu einnig að umhverfisskráin sé í möppunni sem Vite er stillt til að nota. Sjálfgefið envDir er rót verkefnisins. Ef verkefnið þitt hefur sérsniðna root eða envDir, getur rétt nefnd breyta í rangri möppu enn birst sem undefined.

4. Staðfestu niðurstöðuna áður en þú breytir einhverju öðru

Endurhlaðið forritið og athugaðu vafra stjórnborðið. Upprunalega process is not defined undantekningin ætti að vera horfin. Staðfestu síðan tiltekna hegðun sem fer eftir breytunni – til dæmis ætti API beiðni að miðast við væntanlegan grunn URL.

Fyrir tímabundna greiningu er eðlilegt að logga óviðkvæmt gildi eins og API grunn URL eða ham. Fjarlægðu óþarfa logging síðar, sérstaklega ef það gæti afhjúpað innri stillingaupplýsingar.

Hvað ef villan kemur frá háð?

Ef leit þín finnur enga process tilvísun í source þínum, skoðaðu stakkspóruna. Slóð inni í node_modules þýðir oft að pakki var skrifaður með Node.js forsendum eða rangt pakka entry var valið fyrir vafra notkun.

Öruggasta röðin er að uppfæra háðina, athuga opinber skjölun hennar fyrir vafra stuðning og kjósa vafra samhæft pakka eða export. Almennur polyfill getur látið villuna hverfa en skilið önnur Node-only APIs óleyst, svo það er ekki sjálfkrafa fullkomin lausn.

Ef háðin þarf aðeins eina compile-time fasta, getur define valkostur Vite framkvæmt markvissa heildar staðgengil. Til dæmis er hægt að meðhöndla þrönga samhæfingar kröfu með því að skilgreina nákvæmlega þann identifier sem háðin les frekar en að búa til fullan process hlut:

import { defineConfig } from 'vite'

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

Notaðu þetta aðeins þegar þú skilur hvað háðin búist við. Vite skjalsetur define sem heildar fasta staðgengil sem er tiltækur við þróun og statískt skipt út við byggingu. Ekki nota það til að ýta leyndarmálum inn í vafra kóða.

Hvenær er process.env gilt í Vite verkefni?

Það getur verið gilt í Node-hliðar kóða. Algengt dæmi er vite.config.ts. Hins vegar gerir núverandi stillingaskjölun Vite mikilvægan greinarmun: .env* skrár eru ekki sjálfkrafa innsettar í process.env meðan stillingaskráin er upphaflega metin. Ef þú þarft þessara skrá inni í stillingunum, notaðu loadEnv hjálparfall 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)
    }
  }
})

Tómt forskeyti sem sent er til loadEnv þýðir að stillingin getur lesið öll pöruð gildi. Það afhjúpar þau ekki sjálfkrafa fyrir vafra, en hvert gildi sem þú setur viljandi í define getur orðið hluti af viðskiptis kóða. Aðeins afhjúpaðu það sem er öruggt.

Hvað breytist fyrir SSR?

Vite greinir á milli viðskiptis og server umhverfa. Í dæmigerðri SSR uppsetningu getur server kóði keyrt í Node.js á meðan viðskiptis bundle keyrir í vafra. Það þýðir að process.env tilvísun getur verið fullkomlega gild í server-only einingu og ógild í sameiginlegri einingu sem keyrir einnig á viðskiptis hliðinni.

Ef villan birtist aðeins eftir hydration eða vafra leiðsögn, athugaðu hvort server-orienterð utility var flutt inn í viðskiptis kóða. Notaðu import.meta.env.SSR þar sem við á til að greina keyrsluumhverfi, en haltu einnig leyndarmálum og Node-only APIs utan við viðskiptis aðgengilegar greinar og einingar.

Algengar lagfæringar sem skapa ný vandamál

• Að bæta við window.process = {}: þetta þaggar niður aðeins sumum leitum og getur falið raunverulegt samhæfingar vandamál.
• Að stilla envPrefix á tóman streng: Vite hafnar þessu sérstaklega vegna þess að það gæti afhjúpað hverja einustu umhverfisbreytu fyrir viðskiptis kóða.
• Að endurnefna leyndarmál svo það byrji á VITE_: það gerir leyndarmálið hæft fyrir viðskiptis afhjúpun; færið leyndarmál-háða vinnu yfir á backend í staðinn.
• Að breyta aðeins .env skránni: þú verður einnig að uppfæra kóða tilvísanir frá process.env.NAME yfir í import.meta.env.VITE_NAME og endurræsa Vite.
• Að polyfill-a hverja Node heildarbreytu: þetta getur aukið bundle þyngd og enn mistekist ef háð treystir á óstudd Node modules eða keyrsluhegðun.

Hrað flutnings dæmi

Gerum ráð fyrir að React verkefni hafi áður haft þessa skrá:

REACT_APP_API_URL=https://api.example.com

og þessa component:

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

Í Vite, endurnefndu breytuna:

VITE_API_URL=https://api.example.com

Breyttu síðan componentinu:

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

Endurræstu dev serverinn og prófaðu aftur. Þetta er rétta lausnin þegar gildið er öruggt að afhjúpa fyrir viðskiptis hliðina. Ef gamla breytan inniheldur einkaleyfi, ekki flytja hana á þennan hátt; færið forréttinda aðgerðina aftan við server endpoint.

Lokapróf: hvernig veistu að lagfæringin er fullkomin?

Fullkomin lagfæring hefur fleiri en eitt merki. Vafri tilkynnir ekki lengur process is not defined; væntanlegar viðskiptis öruggar breytur leysast í ætluð gildi; þróunar og framleiðslu hamir hegða sér eins og búist var við; og framleiðslu bygging virkar án þess að kynna nýjar Node-heildar villur.

Keyrðu venjulegu þróunar prófunina þína, búðu síðan til framleiðslu byggingu með byggingar scripti verkefnisins þíns og forsýndu eða deployaðu því í umhverfi sem líkist framleiðslu. Ef bilunin birtist aðeins í framleiðslu, skoðaðu ham-sérstakar .env skrár og háðar kóða slóðir. Ef hún birtist aðeins í einni háð, einbeittu þér að þeirri háð frekar en að bæta við sífellt breiðari shims við allt forritið.

Fyrir flest Vite forrit er varanlega reglan einföld: notaðu import.meta.env fyrir viðskiptis stillingar, haltu leyndarmálum á servernum og geymdu Node heildarbreytur eins og process fyrir kóða sem keyrir raunverulega í Node umhverfi.