Как да поправите грешката Uncaught ReferenceError: process is not defined във Vite

Най-важното поправка е проста: ако грешката идва от вашия код от страната на клиента във Vite, заменете process.env с API-то import.meta.env на Vite. Обектът process принадлежи на Node.js, докато нормално клиентско приложение на Vite работи в браузъра. Vite умишлено предоставя безопасни за клиента променливи на средата чрез import.meta.env.

Например, код, мигриран от друга инструментална верига, може да съдържа process.env.REACT_APP_API_URL. Във Vite типичната замяна е import.meta.env.VITE_API_URL, като VITE_API_URL е дефинирана във файл .env. Ако грешката идва от пакет на трета страна, а не от вашия собствен изходен код, най-добрата поправка може да бъде актуализирането, замяната или конфигурирането на този пакет, вместо да добавяте общ полифил за Node.js.

Това ръководство следва текущата документация на Vite, налична към 11 септември 2026 г. Авторитетните препратки са документацията на Vite за Променливи на средата и режими, документацията за Споделени опции и Ръководството за SSR. За разликата между браузърния код и API-тата на изпълнителната среда на Node.js, вижте официалната документация за process в Node.js.

Защо Vite показва „process is not defined“?

Браузърът няма вграден глобален обект process на Node.js. Документацията на Node описва process като обект, който предоставя информация за и контрол върху текущия процес на Node.js. Ако код, който очаква този обект на Node, достигне до браузърния пакет, препратка като process.env.API_URL може да се провали по време на изпълнение с ReferenceError: process is not defined.

Моделът на клиента на Vite е различен. Неговото официално API за среда предоставя стойности под import.meta.env. Vite също така предоставя вградени стойности като import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD, import.meta.env.BASE_URL и import.meta.env.SSR.

Коя поправка се прилага за вашия проект?

1. Заменете process.env в браузърния код

Започнете, като потърсите във вашата директория с изходен код за process.env и голи препратки към process. Ако препратката е в код, който се доставя на браузъра, конвертирайте го към API-то за среда на Vite.

Преди:

const apiUrl = process.env.REACT_APP_API_URL

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

След:

const apiUrl = import.meta.env.VITE_API_URL

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

Ако имате нужда от точното име на режима, а не от булева стойност за разработка/производство, използвайте import.meta.env.MODE. Vite документира режимите и NODE_ENV като свързани, но отделни концепции, затова не предполагайте, че персонализиран режим като staging е еквивалентен на промяната на NODE_ENV.

2. Преименувайте променливите на средата за клиента с префикс VITE_

По подразбиране Vite предоставя на клиентския изходен код само променливите на средата, чиито имена започват с VITE_. Това е граница на сигурност, предназначена да намали случайното разкриване на сървърни тайни.

Файл .env на ниво проект може да съдържа:

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

Клиентският код може да чете import.meta.env.VITE_API_URL и import.meta.env.VITE_APP_NAME. Променливата DB_PASSWORD без префикс не се предоставя чрез import.meta.env по подразбиране.

Не разглеждайте префикса VITE_ като хранилище за тайни. Vite изрично предупреждава, че стойностите с префикс се включват в клиентския код. Всичко, което се доставя на браузъра, трябва да се счита за четимо от потребителя. API тайните, частните ключове за подписване, паролите за бази данни и подобни удостоверения принадлежат на сървъра, а не в клиентския пакет на Vite.

Vite зарежда .env и .env.local, както и специфични за режима файлове като .env.production или .env.staging. Стойностите, специфични за режима, имат приоритет пред общите файлове, докато променливите, вече налични в средата, когато Vite стартира, имат по-висок приоритет от стойностите от файловете.

3. Рестартирайте Vite след промяна на файловете .env

Vite зарежда файловете със среда, когато стартира. След като добавите, преименувате или редактирате стойност във файл .env*, спрете сървъра за разработка и го стартирайте отново. Само презареждането на браузъра може да ви остави да тествате стойности, заредени преди промяната.

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

Също така потвърдете, че файлът със среда е в директорията, която Vite е конфигуриран да използва. По подразбиране envDir е коренът на проекта. Ако вашият проект има персонализиран root или envDir, правилно именувана променлива в грешната директория все още може да се появи като undefined.

4. Проверете резултата, преди да промените нещо друго

Презаредете приложението и проверете браузърната конзола. Първоначалното изключение process is not defined трябва да е изчезнало. След това проверете конкретното поведение, което зависи от променливата – например, заявката към API трябва да сочи към очаквания базов URL.

За временна диагностика е разумно да логнете стойност, която не е тайна, като базовия URL на API или режима. Премахнете ненужното логиране след това, особено ако то може да разкрие детайли от вътрешната конфигурация.

Какво ако грешката идва от зависимост?

Ако търсенето ви не открива препратка към process във вашия изходен код, инспектирайте стека на грешката. Път вътре в node_modules често означава, че пакетът е написан с предположения за Node.js или е избран грешният вход на пакета за използване в браузъра.

Най-безопасният ред е да актуализирате зависимостта, да проверите официалната ѝ документация за поддръжка на браузъри и да предпочетете пакет или експорт, съвместим с браузъри. Общ полифил може да накара грешката да изчезне, докато оставя други API-та, предназначени само за Node, неразрешени, затова той не е автоматично пълна поправка.

Ако зависимостта има нужда само от една константа по време на компилиране, опцията define на Vite може да извърши целево глобално заместване. Например, тясно обхванато изискване за съвместимост може да бъде обработено чрез дефиниране на точния идентификатор, който зависимостта чете, вместо да се измисля пълен обект process:

import { defineConfig } from 'vite'

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

Използвайте това само когато разбирате какво очаква зависимостта. Vite документира define като глобално заместване на константи, което е налично по време на разработка и статично замествано по време на билд. Не го използвайте, за да поставяте тайни в браузърния код.

Кога process.env е валиден във Vite проект?

Може да е валиден в код от страната на Node. Чест пример е vite.config.ts. Въпреки това, текущата документация за конфигурация на Vite прави важно разграничение: файловете .env* не се инжектират автоматично в process.env, докато конфигурационният файл първоначално се оценява. Ако имате нужда от тези файлове вътре в конфигурацията, използвайте помощника loadEnv на 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)
    }
  }
})

Празният префикс, предаден на loadEnv, означава, че конфигурацията може да чете всички съвпадащи стойности. Това не ги разкрива автоматично на браузъра, но всяка стойност, която умишлено поставите в define, може да стане част от клиентския код. Разкривайте само това, което е безопасно.

Какво се променя за SSR?

Vite разграничава клиентска и сървърна среда. В типична SSR конфигурация сървърният код може да работи в Node.js, докато клиентският пакет работи в браузъра. Това означава, че препратка към process.env може да е напълно валидна в модул, предназначен само за сървъра, и невалидна в споделен модул, който също се изпълнява на клиента.

Ако грешката се появява само след хидратиране или браузърна навигация, проверете дали сървърна помощна функция не е импортирана в клиентския код. Използвайте import.meta.env.SSR, където е подходящо, за да разграничите контекстите на изпълнение, но също така дръжте тайните и API-тата, предназначени само за Node, извън клоните и модулите, достъпни от клиента.

Чести поправки, които създават нови проблеми

• Добавяне на window.process = {}: това потиска само някои търсения и може да скрие истинския проблем със съвместимостта.
• Задаване на envPrefix на празен низ: Vite изрично отхвърля това, защото би могло да разкрие всяка променлива на средата на клиентския код.
• Преименуване на тайна, за да започва с VITE_: това я прави подходяща за разкриване на клиента; преместете работата, зависеща от тайната, на бекенда вместо това.
• Промяна само на файла .env: трябва също да актуализирате препратките в кода от process.env.NAME на import.meta.env.VITE_NAME и да рестартирате Vite.
• Полифилиране на всеки глобален обект на Node: това може да добави тегло към пакета и все пак да се провали, ако зависимостта разчита на неподдържани модули на Node или поведение на изпълнителната среда.

Бърз пример за миграция

Да предположим, че React проект преди това е имал този файл:

REACT_APP_API_URL=https://api.example.com

и този компонент:

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

Във Vite преименувайте променливата:

VITE_API_URL=https://api.example.com

След това променете компонента:

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

Рестартирайте сървъра за разработка и тествайте отново. Това е правилното решение, когато стойността е безопасна за разкриване на клиента. Ако старата променлива съдържа частно удостоверение, не я мигрирайте по този начин; преместете привилегированата операция зад сървърен крайна точка.

Финална проверка: как разбирате, че поправката е завършена?

Пълната поправка има повече от един признак. Браузърът вече не докладва process is not defined; очакваните ви безопасни за клиента променливи се разрешават до желаните стойности; режимите за разработка и производство се държат както се очаква; и производственият билд работи без въвеждане на нови грешки с глобални обекти на Node.

Изпълнете вашия нормален тест за разработка, след това създайте производствен билд със скрипта за билд на вашия проект и го прегледайте или внедрете в среда, която наподобява производство. Ако провалът се появява само в производство, инспектирайте специфичните за режима файлове .env и кодовите пътища на зависимостите. Ако се появява само в една зависимост, фокусирайте се върху тази зависимост, вместо да добавяте все по-широки шимове към цялото приложение.

За повечето приложения на Vite, трайното правило е ясно: използвайте import.meta.env за клиентска конфигурация, дръжте тайните на сървъра и запазете глобалните обекти на Node като process за код, който наистина се изпълнява в среда на Node.