Vercel: μεταβλητές περιβάλλοντος χωρίς .env στο Git

Αυτός ο οδηγός αφορά ένα έργο που φιλοξενείται ήδη στο Vercel. Χρειάζεστε πρόσβαση στις ρυθμίσεις του και κατανόηση των μεταβλητών που διαβάζει η εφαρμογή. Το παρακάτω παράδειγμα αφορά το Next.js· τα ονόματα μεταβλητών από άλλο πλαίσιο δεν μπορούν να μεταφερθούν αυτόματα. Ο οδηγός βασίζεται στην επίσημη τεκμηρίωση· δεν έχει δοκιμαστεί σε πραγματικό λογαριασμό.

Πρακτικές πληροφορίες για τη χρήση του Ailoot διατίθενται στην τεκμηρίωση.

Γιατί δεν χρειάζεται να προσθέσετε το .env στο Git#

Μια μεταβλητή περιβάλλοντος είναι μια ρύθμιση με όνομα και τιμή, την οποία λαμβάνει μια εφαρμογή ξεχωριστά από τον πηγαίο κώδικά της. Για παράδειγμα, το όνομα SERVICE_API_KEY επιτρέπει στο πρόγραμμα να αποκτήσει πρόσβαση στην τιμή του κλειδιού μιας εξωτερικής υπηρεσίας. Μην βάλετε το ίδιο το κλειδί στον οδηγό, στη συνομιλία σας με έναν agent ή στο αποθετήριο.

Το Next.js μπορεί να φορτώσει μεταβλητές από τοπικά αρχεία .env*. Ωστόσο, ένα τοπικό αρχείο και οι ρυθμίσεις ενός έργου στο Vercel είναι δύο ξεχωριστές τοποθεσίες. Αν το αρχείο δεν έχει προωθηθεί στο αποθετήριο, ορίστε τις τιμές ξεχωριστά στην πλατφόρμα φιλοξενίας. Το τυπικό πρότυπο create-next-app προσθέτει τα αρχεία .env στο .gitignore· η τεκμηρίωση του Next.js προειδοποιεί ότι σχεδόν ποτέ δεν πρέπει να τα προωθείτε στο αποθετήριο.

Αν εξακολουθείτε να μην είστε βέβαιοι για το τι μπορεί να αποθηκευτεί σε αρχεία πηγαίου κώδικα, ξεκινήστε με τον έλεγχο ασφαλείας για έργο που δημιουργήθηκε με AI. Εδώ εξετάζουμε ένα πιο συγκεκριμένο ερώτημα: πού να ορίσετε τις ρυθμίσεις για μια συγκεκριμένη ανάπτυξη στο Vercel.

Αρχικά, προσδιορίστε από πού διαβάζει την τιμή η εφαρμογή#

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

Το περιβάλλον Development προορίζεται για τοπική ανάπτυξη. Το Preview αφορά τις δοκιμαστικές αναπτύξεις και το Production την κύρια δημοσιευμένη έκδοση. Το Preview μπορεί να έχει ρυθμίσεις για συγκεκριμένο κλάδο Git: αυτές υπερισχύουν των γενικών ρυθμίσεων Preview με τα ίδια ονόματα.

Σε ένα έργο Next.js, οι μεταβλητές χωρίς NEXT_PUBLIC_ είναι διαθέσιμες στον διακομιστή από προεπιλογή. Το πρόθεμα NEXT_PUBLIC_ επιτρέπει να ενσωματωθεί η τιμή στο JavaScript που παραδίδεται στο πρόγραμμα περιήγησης. Αυτό είναι κατάλληλο για μια ρύθμιση που είναι ρητά δημόσια, όπως μια μη μυστική ετικέτα έκδοσης, αλλά όχι για ένα ιδιωτικό κλειδί API. Ακόμη και χωρίς αυτό το πρόθεμα, ο κώδικας της εφαρμογής δεν πρέπει να επιστρέφει χειροκίνητα ένα μυστικό στον πελάτη.

Αν δεν έχετε ακόμη προσδιορίσει το πλαίσιο, ζητήστε από τον agent να το αναγνωρίσει από τα αρχεία του έργου. Η σύγκριση Astro και Next.js μπορεί να σας βοηθήσει να κατανοήσετε τις διαφορές· δεν μπορείτε να εφαρμόσετε τον κανόνα NEXT_PUBLIC_ σε κάθε εφαρμογή React.

Οι ρυθμίσεις φιλοξενίας είναι μία από τις εργασίες που απαιτούνται κατά την εργασία σε μια εφαρμογή με έναν agent AI.

Πώς να προσθέσετε μια μεταβλητή σε έργο Vercel#

Εκτελέστε μόνοι σας τα βήματα στον επίσημο πίνακα ελέγχου. Μη δώσετε στον agent ένα πραγματικό κλειδί για να συμπληρώσει τη φόρμα και μην επισυνάψετε στιγμιότυπο οθόνης που περιέχει την τιμή του.

1. Ανοίξτε τον πίνακα ελέγχου του Vercel και επιλέξτε το σωστό έργο. Μην βασιστείτε μόνο σε ένα όνομα αποθετηρίου που ταιριάζει: ελέγξτε ότι ρυθμίζετε την εφαρμογή που σκοπεύετε να ανοίξετε.
2. Μεταβείτε στο Environment Variables στην πλαϊνή γραμμή των ρυθμίσεων του έργου.
3. Στο Name, καταχωρίστε το όνομα που διαβάζει η εφαρμογή, όπως SERVICE_API_KEY. Αυτό είναι ένα ενδεικτικό όνομα· αν ο κώδικας περιμένει κάποιο άλλο, χρησιμοποιήστε την ακριβή γραφή του.
4. Στο Value, καταχωρίστε την τιμή από το αποθετήριο διαπιστευτηρίων σας. Μην τη βάλετε στον πηγαίο κώδικα, σε συνομιλία ή σε αρχείο καταγραφής επαλήθευσης.
5. Επιλέξτε το περιβάλλον που χρειάζεται αυτή τη ρύθμιση. Χρησιμοποιήστε το Preview για να ελέγξετε μια δοκιμαστική έκδοση και το Production για την κύρια έκδοση. Μην αντιστοιχίζετε αυτόματα ένα μυστικό σε όλα τα περιβάλλοντα.
6. Αν η ρύθμιση Preview ισχύει για συγκεκριμένο κλάδο, ελέγξτε τον επιλεγμένο κλάδο και τυχόν παράκαμψη με το ίδιο όνομα.
7. Κάντε κλικ στο Save.

Το Vercel καθιστά τις μεταβλητές του έργου διαθέσιμες τόσο κατά τη δημιουργία όσο και όταν εκτελούνται οι συναρτήσεις Vercel από την πλευρά του διακομιστή. Ωστόσο, το ότι μια τιμή είναι διαθέσιμη στο Vercel δεν σημαίνει ότι μπορεί να σταλεί στο πρόγραμμα περιήγησης: αυτό εξαρτάται από τον κώδικα της εφαρμογής και τους κανόνες του πλαισίου.

Γιατί χρειάζεστε νέα ανάπτυξη μετά το Save#

Η αποθήκευση μιας μεταβλητής δεν αλλάζει τις υπάρχουσες αναπτύξεις. Η τεκμηρίωση του Vercel απαιτεί να αναπτύξετε ξανά το έργο, ώστε η νέα ρύθμιση να εφαρμοστεί στην έκδοση που χρησιμοποιείτε.

Όταν εργάζεστε μέσω Git, μπορείτε να δημιουργήσετε μια νέα ανάπτυξη Production προωθώντας μια υποβολή στον κλάδο που καθορίζεται στο Production Branch και μια ανάπτυξη Preview προωθώντας μια υποβολή σε άλλον κλάδο. Μην υποθέτετε ότι ο κύριος κλάδος είναι πάντα main: ελέγξτε τη ρύθμιση του έργου σας. Αυτό πρέπει να είναι μια κανονική, συμφωνημένη έκδοση του έργου, χωρίς να προσθέσετε αρχείο μυστικών στην υποβολή.

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

Το Next.js έχει έναν ακόμη όρο: αναφορές όπως process.env.NEXT_PUBLIC_RELEASE_LABEL αντικαθίστανται από τις τιμές τους κατά το next build. Η τιμή καθορίζεται μετά τη δημιουργία. Η αλλαγή της ρύθμισης χωρίς νέα δημιουργία δεν θα ξαναγράψει το JavaScript από την πλευρά του πελάτη που έχει ήδη παραδοθεί.

Πώς να ελέγξετε το αποτέλεσμα χωρίς να εκθέσετε το κλειδί#

Ξεκινήστε με ένα ασφαλές παράδειγμα: μια ρητά μη μυστική ετικέτα με όνομα NEXT_PUBLIC_RELEASE_LABEL και τιμή preview-check. Αυτά είναι ένα ενδεικτικό όνομα και κείμενο, όχι κλειδί ή δοκιμή που πραγματοποιήθηκε εδώ. Αν μια εφαρμογή Next.js διαβάζει αυτή τη μεταβλητή απευθείας μέσω process.env.NEXT_PUBLIC_RELEASE_LABEL, μπορεί να εμφανίσει την ετικέτα στο προβλεπόμενο σημείο της διεπαφής μετά από νέα δημιουργία. Αυτός ο έλεγχος επιβεβαιώνει μόνο ότι η δημόσια ρύθμιση μεταβιβάστηκε.

Ένα ιδιωτικό κλειδί ελέγχεται διαφορετικά. Μην εμφανίζετε την τιμή του, τμήμα της, το μήκος του ή ολόκληρο το process.env. Μη δημιουργείτε δημόσια διεύθυνση URL που επιστρέφει τα περιεχόμενα της μεταβλητής. Αρχικά, ελέγξτε μόνο αν η ρύθμιση είναι «παρούσα / απούσα» στον διακομιστή και, στη συνέχεια, ελέγξτε ξεχωριστά τη λειτουργία της εφαρμογής που χρησιμοποιεί την υπηρεσία. Η παρουσία μιας ρύθμισης δεν αποδεικνύει ότι το κλειδί είναι έγκυρο ή ότι έχει τα απαιτούμενα δικαιώματα.

Μπορείτε να καταγράψετε τα αποτελέσματα χωρίς μυστικά:

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

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

Τι να ελέγξετε αν η τιμή εξακολουθεί να είναι undefined#

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

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

Η μετάβαση στον δικό σας διακομιστή απαιτεί διαφορετική διαδικασία: δείτε τον οδηγό για την ανάπτυξη έργου με Coolify. Τα ονόματα κουμπιών και τα βήματα ρύθμισης του Vercel δεν ισχύουν γι’ αυτό.

Μεταβείτε στο Ailoot.