Näin korjaat virheen Uncaught ReferenceError: process is not defined Vite-projektissa

Tärkein korjaus on yksinkertainen: jos virhe johtuu selaimessa toimivasta Vite-koodista, korvaa process.env Viten import.meta.env-rajapinnalla. process-objekti kuuluu Node.js:ään, kun taas tavallinen Vite-asiakassovellus toimii selaimessa. Vite tarjoaa tarkoituksella selaimelle turvalliset ympäristömuuttujat import.meta.env:n kautta.

Esimerkiksi toisesta työkaluketjusta migroitu koodi voi sisältää process.env.REACT_APP_API_URL-viittauksen. Vite-projektissa tyypillinen korvaaja on import.meta.env.VITE_API_URL, jossa VITE_API_URL on määritelty .env-tiedostossa. Jos virhe johtuu kolmannen osapuolen paketista eikä omasta lähdekoodistasi, paras korjaus voi olla paketin päivittäminen, korvaaminen tai konfigurointi sen sijaan, että lisäät yleisen Node.js-polyfillin.

Nämä ohjeet perustuvat Viten nykyiseen dokumentaatioon, joka oli saatavilla 11. syyskuuta 2026. Luotettavat lähteet ovat Viten Ympäristömuuttujat ja tilat -dokumentaatio, Jaetut asetukset -dokumentaatio ja SSR-opas. Selaimen koodin ja Node.js-aikajärjestelmän API-erojen osalta katso virallinen Node.js process-dokumentaatio.

Miksi Vite ilmoittaa virheestä “process is not defined”?

Selaimessa ei ole sisäänrakennettua Node.js:n process-globaalia. Noden dokumentaatio kuvaa process-objektin tarjoavan tietoa ja hallintaa nykyisestä Node.js-prosessista. Jos koodi, joka odottaa tätä Node-objektia, päätyy selainpakettiin, viittaus kuten process.env.API_URL voi epäonnistua ajonaikana virheellä ReferenceError: process is not defined.

Viten asiakasmalli on erilainen. Sen virallinen ympäristörajapinta paljastaa arvot import.meta.env:n alla. Vite tarjoaa myös sisäänrakennettuja arvoja, kuten import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL ja import.meta.env.SSR.

Mikä korjaus sopii projektiisi?

1. Korvaa process.env selaimen koodissa

Aloita etsimällä lähdehakemistostasi process.env-viittauksia ja pelkkiä process-viittauksia. Jos viittaus on koodissa, joka toimitetaan selaimeen, muunna se Viten ympäristörajapinnaksi.

Ennen:

const apiUrl = process.env.REACT_APP_API_URL

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

Jälkeen:

const apiUrl = import.meta.env.VITE_API_URL

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

Jos tarvitset tarkan tilan nimen kehitys/tuotanto-boolean sijaan, käytä import.meta.env.MODE:ia. Vite dokumentoi tilat ja NODE_ENV:n liittyviksi mutta erillisiksi käsitteiksi, joten älä oleta, että mukautettu tila kuten staging vastaa NODE_ENV:n muuttamista.

2. Nimeä asiakasympäristömuuttujat VITE_-etuliitteellä

Oletuksena Vite paljastaa asiakaskoodille vain ympäristömuuttujat, joiden nimet alkavat VITE_-merkkijonolla. Tämä on turvallisuusraja, jonka tarkoitus on vähentää palvelinpuolen salaisuuksien tahatonta paljastumista.

Projektin .env-tiedosto voi sisältää:

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

Asiakaskoodi voi lukea import.meta.env.VITE_API_URL:n ja import.meta.env.VITE_APP_NAME:n. Etuliitteetön DB_PASSWORD ei ole oletuksena paljastettu import.meta.env:n kautta.

Älä käsittele VITE_-etuliitettä salaisuuksien säilytyspaikkana. Vite varoittaa nimenomaisesti, että etuliitteelliset arvot pakataan asiakaspuolen koodiin. Kaikki selaimeen toimitettava on pidettävä käyttäjän luettavissa olevana. API-avaimet, yksityiset allekirjoitusavaimet, tietokantasalasanat ja vastaavat tunnukset kuuluvat palvelimelle, eivät Vite-asiakaspakettiin.

Vite lataa .env- ja .env.local-tiedostot sekä tilakohtaiset tiedostot kuten .env.production tai .env.staging. Tilakohtaiset arvot korvaavat yleiset tiedostot, kun taas Viten käynnistyessä ympäristössä jo olevilla muuttujilla on korkeampi prioriteetti kuin tiedostoista tulevilla arvoilla.

3. Käynnistä Vite uudelleen .env-tiedostojen muuttamisen jälkeen

Vite lataa ympäristötiedostot käynnistyessään. Kun olet lisännyt, nimennyt uudelleen tai muokannut arvoa .env*-tiedostossa, pysäytä kehityspalvelin ja käynnistä se uudelleen. Pelkkä selaimen päivitys voi jättää sinut testaamaan arvoja, jotka ladattiin ennen muutosta.

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

Varmista myös, että ympäristötiedosto on hakemistossa, jonka Vite on konfiguroitu käyttämään. Oletusarvoinen envDir on projektin juurihakemisto. Jos projektissasi on mukautettu root tai envDir, väärään hakemistoon sijoitettu oikein nimetty muuttuja voi silti näyttää undefined-arvolta.

4. Tarkista tulos ennen muiden muutosten tekemistä

Lataa sovellus uudelleen ja tarkista selaimen konsoli. Alkuperäisen process is not defined -poikkeuksen pitäisi olla poissa. Tarkista sitten muuttujaan perustuva tietty toiminnallisuus – esimerkiksi API-pyynnön pitäisi kohdistua odotettuun perus-URL-osoitteeseen.

Tilapäistä diagnosointia varten on järkevää lokittaa ei-salaisia arvoja, kuten API:n perus-URL-osoite tai tila. Poista tarpeeton lokitus myöhemmin, erityisesti jos se voi paljastaa sisäisiä konfiguraatiotietoja.

Mitä jos virhe johtuu riippuvuudesta?

Jos hakusi ei löydä process-viittausta lähdekoodistasi, tutki pinon seurantaa. Polku node_modules-hakemistossa tarkoittaa usein, että paketti on kirjoitettu Node.js-oletusten pohjalta tai selaimen käyttöön on valittu väärä paketin entry-piste.

Turvallisin järjestys on päivittää riippuvuus, tarkistaa sen virallisesta dokumentaatiosta selainyhteensopivuus ja suosia selainyhteensopivaa pakettia tai exporttia. Yleinen polyfill voi saada virheen katoamaan jättäen muut vain Nodeen tarkoitetut API:t ratkaisematta, joten se ei automaattisesti ole täydellinen korjaus.

Jos riippuvuus tarvitsee vain yhden käännösaikaisen vakion, Viten define-asetus voi suorittaa kohdennetun globaalin korvauksen. Esimerkiksi kapeasti rajattu yhteensopivuusvaatimus voidaan hoitaa määrittelemällä täsmälleen se tunniste, jota riippuvuus lukee, sen sijaan että luotaisiin kokonainen process-objekti:

import { defineConfig } from 'vite'

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

Käytä tätä vain, jos ymmärrät, mitä riippuvuus odottaa. Vite dokumentoi define:n globaaliksi vakionkorvaukseksi, joka on käytettävissä kehitysvaiheessa ja korvataan staattisesti buildin aikana. Älä käytä sitä salaisuuksien työntämiseen selaimen koodiin.

Milloin process.env on kelvollinen Vite-projektissa?

Se voi olla kelvollinen Node-puolen koodissa. Yleinen esimerkki on vite.config.ts. Viten nykyinen konfiguraatiodokumentaatio tekee kuitenkin tärkeän eron: .env*-tiedostoja ei automaattisesti injektoida process.env:iin konfiguraatiotiedoston alustavan arvioinnin aikana. Jos tarvitset näitä tiedostoja konfiguraatiossa, käytä Viten loadEnv-apufunktiota.

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

loadEnv:lle annettu tyhjä etuliite tarkoittaa, että konfiguraatio voi lukea kaikki täsmäävät arvot. Tämä ei automaattisesti paljasta niitä selaimelle, mutta mikä tahansa arvo, jonka tarkoituksella sijoitat define:iin, voi tulla osaksi asiakaskoodia. Paljasta vain se, mikä on turvallista.

Mitä muuttuu SSR:ssä?

Vite erottaa asiakas- ja palvelinympäristöt. Tyypillisessä SSR-konfiguraatiossa palvelinkoodi voi toimia Node.js:ssä, kun taas asiakaspaketti toimii selaimessa. Tämä tarkoittaa, että process.env-viittaus voi olla täysin kelvollinen vain palvelimelle tarkoitetussa moduulissa ja virheellinen jaetussa moduulissa, joka suoritetaan myös asiakkaalla.

Jos virhe ilmenee vasta hydrauksen tai selaimen navigoinnin jälkeen, tarkista, onko palvelimelle tarkoitettu apufunktio tuotu asiakaskoodiin. Käytä import.meta.env.SSR:iä tarvittaessa erottamaan suoritusympäristöt, mutta pidä myös salaisuudet ja vain Nodeen tarkoitetut API:t pois asiakkaan saavutettavissa olevista haaroista ja moduuleista.

Yleiset korjaukset, jotka luovat uusia ongelmia

• window.process = {}:n lisääminen: tämä vaimentaa vain joitakin hakuja ja voi piilottaa todellisen yhteensopivuusongelman.
• envPrefix:n asettaminen tyhjäksi merkkijonoksi: Vite hylkää tämän nimenomaisesti, koska se voisi paljastaa jokaisen ympäristömuuttujan asiakaskoodille.
• Salaisuuden nimeäminen uudelleen alkamaan VITE_:lla: tämä tekee salaisuudesta kelvollisen asiakaspaljastukselle; siirrä salaisuuteen perustuva työ backendiin sen sijaan.
• Vain .env-tiedoston muuttaminen: sinun on myös päivitettävä koodiviittaukset muodosta process.env.NAME muotoon import.meta.env.VITE_NAME ja käynnistettävä Vite uudelleen.
• Kaikkien Node-globaalien polyfillaaminen: tämä voi lisätä paketin kokoa ja silti epäonnistua, jos riippuvuus luottaa ei-tukiin Node-moduuleihin tai ajonaikaiseen käyttäytymiseen.

Nopea migraatioesimerkki

Oletetaan, että React-projektissa oli aiemmin tämä tiedosto:

REACT_APP_API_URL=https://api.example.com

ja tämä komponentti:

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

Vite-projektissa nimeä muuttuja uudelleen:

VITE_API_URL=https://api.example.com

Muuta sitten komponentti:

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

Käynnistä kehityspalvelin uudelleen ja testaa. Tämä on oikea ratkaisu, kun arvo on turvallista paljastaa asiakkaalle. Jos vanha muuttuja sisältää yksityisen tunnuksen, älä migroi sitä tällä tavalla; siirrä etuoikeutettu toiminto palvelinpäätepisteen taakse.

Lopullinen tarkistus: mistä tiedät korjauksen olevan valmis?

Täydellisessä korjauksessa on useampi merkki. Selain ei enää ilmoita virheestä process is not defined; odotetut asiakasturvalliset muuttujat ratkeavat haluttuihin arvoihin; kehitys- ja tuotantotilat toimivat odotetusti; ja tuotantobuild toimii tuomatta uusia Node-globaalivirheitä.

Suorita normaali kehitystesti, luo sitten tuotantobuild projektin build-skriptillä ja esikatsele tai deployaa se ympäristöön, joka muistuttaa tuotantoa. Jos vika ilmenee vain tuotannossa, tutki tilakohtaiset .env-tiedostot ja riippuvuuksien koodipolut. Jos se ilmenee vain yhdessä riippuvuudessa, keskity siihen riippuvuuteen sen sijaan, että lisäisit yhä laajempia sytkiä koko sovellukseen.

Useimmille Vite-sovelluksille kestävä sääntö on suoraviivainen: käytä import.meta.env:iä asiakaskonfiguraatioon, pidä salaisuudet palvelimella ja varaa Node-globaalit kuten process koodille, joka todella toimii Node-ympäristössä.