Πώς να διορθώσετε το σφάλμα Uncaught ReferenceError: process is not defined στο Vite

Η πιο σημαντική διόρθωση είναι απλή: εάν το σφάλμα προέρχεται από τον κώδικα Vite που εκτελείται στον browser, αντικαταστήστε το process.env με το API import.meta.env του Vite. Το αντικείμενο process ανήκει στο Node.js, ενώ μια κανονική εφαρμογή-πελάτης του Vite εκτελείται στον browser. Το Vite εκθέτει σκόπιμα τις μεταβλητές περιβάλλοντος που είναι ασφαλείς για τον πελάτη μέσω του import.meta.env.

Για παράδειγμα, κώδικας που έχει μεταφερθεί από άλλη εργαλειοθήκη μπορεί να περιέχει process.env.REACT_APP_API_URL. Στο Vite, μια τυπική αντικατάσταση είναι το import.meta.env.VITE_API_URL, με το VITE_API_URL να ορίζεται σε ένα αρχείο .env. Εάν το σφάλμα προέρχεται από πακέτο τρίτων και όχι από τον δικό σας πηγαίο κώδικα, η καλύτερη διόρθωση μπορεί να είναι η ενημέρωση, η αντικατάσταση ή η ρύθμιση του συγκεκριμένου πακέτου, αντί να προσθέσετε ένα γενικό polyfill για το Node.js.

Αυτές οι οδηγίες ακολουθούν την τρέχουσα τεκμηρίωση του Vite που ήταν διαθέσιμη στις 11 Σεπτεμβρίου 2026. Οι επίσημες αναφορές είναι η τεκμηρίωση για τις Μεταβλητές Περιβάλλοντος και τις Λειτουργίες του Vite, η τεκμηρίωση για τις Κοινές Επιλογές και ο οδηγός SSR. Για τη διάκριση μεταξύ κώδικα browser και APIs χρόνου εκτέλεσης Node.js, δείτε την επίσημη τεκμηρίωση για το process του Node.js.

Γιατί το Vite εμφανίζει το μήνυμα “process is not defined”;

Ο browser δεν διαθέτει ενσωματωμένο global process του Node.js. Η τεκμηρίωση του Node περιγράφει το process ως ένα αντικείμενο που παρέχει πληροφορίες και έλεγχο για την τρέχουσα διαδικασία Node.js. Εάν κώδικας που αναμένει αυτό το αντικείμενο Node φτάσει σε bundle browser, μια αναφορά όπως 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 στον κώδικα browser

Ξεκινήστε αναζητώντας στον κατάλογο πηγών σας για process.env και γυμνές αναφορές στο process. Εάν η αναφορά βρίσκεται σε κώδικα που παραδίδεται στον browser, μετατρέψτε τη στο 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')
}

Εάν χρειάζεστε το ακριβές όνομα της λειτουργίας (mode) αντί για ένα boolean ανάπτυξης/παραγωγής, χρησιμοποιήστε το 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 προειδοποιεί ρητά ότι οι τιμές με πρόθεμα ενσωματώνονται στον κώδικα πλευράς πελάτη. Οποιοδήποτε δεδομένο παραδίδεται σε έναν browser πρέπει να θεωρείται αναγνώσιμο από τον χρήστη. Τα μυστικά API, τα ιδιωτικά κλειδιά υπογραφής, οι κωδικοί πρόσβασης βάσεων δεδομένων και παρόμοια διαπιστευτήρια ανήκουν σε έναν διακομιστή, όχι σε ένα bundle πελάτη του Vite.

Το Vite φορτώνει τα .env και .env.local, καθώς και αρχεία συγκεκριμένα για τη λειτουργία (mode) όπως .env.production ή .env.staging. Οι τιμές συγκεκριμένες για τη λειτουργία έχουν προτεραιότητα έναντι των γενικών αρχείων, ενώ οι μεταβλητές που υπάρχουν ήδη στο περιβάλλον όταν ξεκινά το Vite έχουν υψηλότερη προτεραιότητα από τις τιμές των αρχείων.

3. Κάντε επανεκκίνηση του Vite μετά την αλλαγή αρχείων .env

Το Vite φορτώνει τα αρχεία περιβάλλοντος κατά την εκκίνηση. Αφού προσθέσετε, μετονομάσετε ή επεξεργαστείτε μια τιμή σε ένα αρχείο .env*, σταματήστε τον διακομιστή ανάπτυξης και ξεκινήστε τον ξανά. Μια απλή ανανέωση του browser μπορεί να σας αφήσει να δοκιμάζετε τιμές που φορτώθηκαν πριν από την αλλαγή.

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

Επιβεβαιώστε επίσης ότι το αρχείο περιβάλλοντος βρίσκεται στον κατάλογο που έχει ρυθμιστεί να χρησιμοποιεί το Vite. Η προεπιλεγμένη τιμή envDir είναι η ρίζα του έργου. Εάν το έργο σας έχει προσαρμοσμένο root ή envDir, μια σωστά ονομασμένη μεταβλητή στον λάθος κατάλογο μπορεί ακόμα να εμφανίζεται ως undefined.

4. Επαληθεύστε το αποτέλεσμα πριν αλλάξετε οτιδήποτε άλλο

Φορτώστε ξανά την εφαρμογή και ελέγξτε την κονσόλα του browser. Η αρχική εξαίρεση process is not defined πρέπει να έχει εξαφανιστεί. Στη συνέχεια, επαληθεύστε τη συγκεκριμένη συμπεριφορά που εξαρτάται από τη μεταβλητή—for παράδειγμα, ένα αίτημα API πρέπει να στοχεύει στο αναμενόμενο base URL.

Για προσωρινή διάγνωση, είναι λογικό να καταγράψετε μια μη ευαίσθητη τιμή όπως το base URL του API ή η λειτουργία (mode). Αφαιρέστε την περιττή καταγραφή στη συνέχεια, ειδικά εάν θα μπορούσε να αποκαλύψει λεπτομέρειες εσωτερικής ρύθμισης παραμέτρων.

Τι γίνεται εάν το σφάλμα προέρχεται από μια εξάρτηση;

Εάν η αναζήτησή σας δεν βρίσκει καμία αναφορά process στην πηγή σας, επιθεωρήστε το stack trace. Μια διαδρομή μέσα στο node_modules σημαίνει συχνά ότι ένα πακέτο γράφτηκε με παραδοχές Node.js ή ότι επιλέχθηκε η λάθος καταχώρηση πακέτου για χρήση σε browser.

Η ασφαλέστερη σειρά ενεργειών είναι να ενημερώσετε την εξάρτηση, να ελέγξετε την επίσημη τεκμηρίωσή της για υποστήριξη browser και να προτιμήσετε ένα πακέτο ή εξαγωγή συμβατή με browser. Ένα γενικό polyfill μπορεί να κάνει το σφάλμα να εξαφανιστεί αφήνοντας άλλα APIs αποκλειστικά για Node μη επιλυμένα, οπότε δεν είναι αυτόματα μια πλήρης διόρθωση.

Εάν μια εξάρτηση χρειάζεται μόνο μια σταθερά χρόνου μεταγλώττισης, η επιλογή define του Vite μπορεί να εκτελέσει μια στοχευμένη αντικατάσταση global. Για παράδειγμα, μια narrowly scoped απαίτηση συμβατότητας μπορεί να χειριστεί ορίζοντας τον ακριβή αναγνωριστικό που διαβάζει η εξάρτηση αντί να κατασκευάσετε ένα πλήρες αντικείμενο process:

import { defineConfig } from 'vite'

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

Χρησιμοποιήστε το μόνο όταν κατανοείτε τι αναμένει η εξάρτηση. Το Vite τεκμηριώνει το define ως μια αντικατάσταση global σταθεράς που είναι διαθέσιμη κατά την ανάπτυξη και αντικαθίσταται στατικά κατά την κατασκευή (build). Μην το χρησιμοποιείτε για να σπρώξετε μυστικά στον κώδικα browser.

Πότε είναι έγκυρο το process.env σε ένα έργο Vite;

Μπορεί να είναι έγκυρο σε κώδικα πλευράς Node. Ένα κοινό παράδειγμα είναι το vite.config.ts. Ωστόσο, η τρέχουσα τεκμηρίωση ρύθμισης παραμέτρων του Vite κάνει μια σημαντική διάκριση: τα αρχεία .env* δεν εγχέονται αυτόματα στο process.env ενώ το αρχείο ρύθμισης παραμέτρων αξιολογείται αρχικά. Εάν χρειάζεστε αυτά τα αρχεία μέσα στη ρύθμιση παραμέτρων, χρησιμοποιήστε το helper 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 σημαίνει ότι η ρύθμιση παραμέτρων μπορεί να διαβάσει όλες τις τιμές που ταιριάζουν. Αυτό δεν τις εκθέτει αυτόματα στον browser, αλλά οποιαδήποτε τιμή τοποθετήσετε σκόπιμα στο define μπορεί να γίνει μέρος του κώδικα πελάτη. Εκθέστε μόνο ό,τι είναι ασφαλές.

Τι αλλάζει για το SSR;

Το Vite διακρίνει τα περιβάλλοντα πελάτη και διακομιστή. Σε μια τυπική ρύθμιση SSR, ο κώδικας διακομιστή μπορεί να εκτελείται σε Node.js ενώ το bundle πελάτη εκτελείται στον browser. Αυτό σημαίνει ότι μια αναφορά process.env μπορεί να είναι απολύτως έγκυρη σε μια μονάδα αποκλειστικά για διακομιστή και μη έγκυρη σε μια κοινόχρηστη μονάδα που εκτελείται επίσης στον πελάτη.

Εάν το σφάλμα εμφανίζεται μόνο μετά την υδρατμοποίηση (hydration) ή την πλοήγηση στον browser, ελέγξτε εάν ένα εργαλείο προσανατολισμένο στον διακομιστή εισήχθη στον κώδικα πελάτη. Χρησιμοποιήστε το import.meta.env.SSR όπου είναι κατάλληλο για να ξεχωρίσετε τα πλαίσια εκτέλεσης, αλλά κρατήστε επίσης τα μυστικά και τα APIs αποκλειστικά για Node μακριά από κλάδους και μονάδες προσβάσιμους από τον πελάτη.

Συχνές διορθώσεις που δημιουργούν νέα προβλήματα

• Προσθήκη window.process = {}: αυτό καταστέλλει μόνο ορισμένες αναζητήσεις και μπορεί να κρύψει το πραγματικό πρόβλημα συμβατότητας.
• Ορισμός envPrefix σε κενή συμβολοσειρά: το Vite απορρίπτει ρητά αυτό επειδή θα μπορούσε να εκθέσει κάθε μεταβλητή περιβάλλοντος στον κώδικα πελάτη.
• Μετονομασία ενός μυστικού ώστε να ξεκινά με VITE_: αυτό καθιστά το μυστικό επιλέξιμο για έκθεση στον πελάτη· μεταφέρετε την εργασία που εξαρτάται από μυστικά σε ένα backend αντίθετα.
• Αλλαγή μόνο του αρχείου .env: πρέπει επίσης να ενημερώσετε τις αναφορές κώδικα από process.env.NAME σε import.meta.env.VITE_NAME και να κάνετε επανεκκίνηση του Vite.
• Polyfilling κάθε global του Node: αυτό μπορεί να προσθέσει βάρος στο bundle και να αποτύχει ακόμα εάν μια εξάρτηση βασίζεται σε μη υποστηριζόμενες μονάδες Node ή συμπεριφορά χρόνου εκτέλεσης.

Ένα γρήγορο παράδειγμα μετανάστευσης

Υποθέστε ότι ένα έργο React είχε προηγουμένως αυτό το αρχείο:

REACT_APP_API_URL=https://api.example.com

και αυτό το component:

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

Στο Vite, μετονομάστε τη μεταβλητή:

VITE_API_URL=https://api.example.com

Στη συνέχεια, αλλάξτε το component:

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

Κάντε επανεκκίνηση του διακομιστή ανάπτυξης και δοκιμάστε ξανά. Αυτή είναι η σωστή λύση όταν η τιμή είναι ασφαλής για έκθεση στον πελάτη. Εάν η παλιά μεταβλητή περιέχει ένα ιδιωτικό διαπιστευτήριο, μην τη μεταφέρετε με αυτόν τον τρόπο· μετακινήστε την προνομιακή λειτουργία πίσω από ένα endpoint διακομιστή.

Τελικός έλεγχος: πώς ξέρετε ότι η διόρθωση είναι ολοκληρωμένη;

Μια ολοκληρωμένη διόρθωση έχει περισσότερα από ένα σημάδια. Ο browser δεν αναφέρει πλέον process is not defined· οι αναμενόμενες μεταβλητές ασφαλείς για τον πελάτη επιλύονται στις επιθυμητές τιμές· οι λειτουργίες ανάπτυξης και παραγωγής συμπεριφέρονται όπως αναμένεται· και μια κατασκευή παραγωγής λειτουργεί χωρίς να εισάγει νέα σφάλματα globals του Node.

Εκτελέστε την κανονική δοκιμή ανάπτυξής σας, στη συνέχεια δημιουργήστε μια κατασκευή παραγωγής με το σενάριο build του έργου σας και κάντε προεπισκόπηση ή ανάπτυξή της σε ένα περιβάλλον που μοιάζει με την παραγωγή. Εάν η αποτυχία εμφανίζεται μόνο στην παραγωγή, επιθεωρήστε τα αρχεία .env συγκεκριμένα για τη λειτουργία και τα μονοπάτια κώδικα των εξαρτήσεων. Εάν εμφανίζεται μόνο σε μία εξάρτηση, εστιάστε σε αυτήν την εξάρτηση αντί να προσθέσετε ολοένα και πιο ευρείς shims σε ολόκληρη την εφαρμογή.

Για τις περισσότερες εφαρμογές Vite, ο διαρκής κανόνας είναι απλός: χρησιμοποιήστε το import.meta.env για τη ρύθμιση παραμέτρων του πελάτη, κρατήστε τα μυστικά στον διακομιστή και κρατήστε τα globals του Node όπως το process για κώδικα που πραγματικά εκτελείται σε περιβάλλον Node.