Як виправити помилку 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, ознайомтеся з офіційною документацією Node.js щодо process.

Чому Vite повідомляє про помилку “process is not defined”?

У браузері немає вбудованого глобального об'єкта process з Node.js. Документація Node.js описує 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* зупиніть сервер розробки та запустіть його знову. Одне лише оновлення браузера може залишити вас тестувати значення, які були завантажені до зміни.

# зупиніть поточний сервер розробки, потім запустіть його знову
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.