Vercel: ympäristömuuttujat ilman .env-tiedostoa Gitissä

Tämä opas on tarkoitettu projektille, joka on jo Vercelissä. Tarvitset pääsyn sen asetuksiin ja sinun on tiedettävä, mitä muuttujia sovellus lukee. Alla oleva esimerkki koskee Next.js:ää; toisen kehysympäristön muuttujanimiä ei voi siirtää sellaisenaan. Opas perustuu viralliseen dokumentaatioon, eikä sitä ole testattu oikealla tilillä.

Käytännön tietoa Ailootin käytöstä on dokumentaatiossa.

Miksi .env-tiedostoa ei tarvitse lisätä Gitiin#

Ympäristömuuttuja on asetus, jolla on nimi ja arvo ja jonka sovellus saa lähdekoodistaan erillään. Esimerkiksi nimi SERVICE_API_KEY antaa ohjelmalle pääsyn ulkoisen palvelun avaimen arvoon. Älä lisää itse avainta oppaaseen, keskusteluun agentin kanssa tai tietovarastoon.

Next.js voi ladata muuttujia paikallisista .env*-tiedostoista. Paikallinen tiedosto ja projektin asetukset Vercelissä ovat kuitenkin kaksi eri sijaintia. Jos tiedostoa ei viedä tietovarastoon, aseta arvot erikseen hosting-alustalla. create-next-app-vakiomalli lisää .env-tiedostot .gitignore-tiedostoon; Next.js-dokumentaatiossa varoitetaan, että niitä ei lähes koskaan pidä viedä tietovarastoon.

Jos et vieläkään ole varma, mitä lähdetiedostoihin voi tallentaa, aloita tekoälyllä rakennetun projektin tietoturvatarkistuksesta. Tässä käsitellään rajatumpaa kysymystä: mihin tietyn Vercel-käyttöönoton asetukset määritetään.

Selvitä ensin, mistä sovellus lukee muuttujan#

Ennen arvojen syöttämistä tee luettelo nimistä ilman varsinaisia salaisuuksia. Kunkin nimen osalta on selvitettävä kolme asiaa: mikä ympäristö käyttää sitä, missä muuttujaa lukeva koodi suoritetaan ja milloin arvoa tarvitaan.

Development-ympäristö on tarkoitettu paikalliseen kehitykseen. Preview koskee esikatselukäyttöönottoja ja Production pääasiallista julkaistua versiota. Preview-asetuksia voi määrittää tietylle Git-haaralle: ne ohittavat samannimiset yleiset Preview-asetukset.

Next.js-projektissa muuttujat, joiden nimessä ei ole NEXT_PUBLIC_-etuliitettä, ovat oletusarvoisesti käytettävissä palvelimella. NEXT_PUBLIC_-etuliite sallii arvon upottamisen selaimeen toimitettavaan JavaScript-koodiin. Tämä sopii asetukseen, joka on nimenomaisesti julkinen, kuten ei-salaiseen versiotunnisteeseen, mutta ei yksityiseen API-avaimeen. Etuliitteestä riippumatta sovelluskoodi ei saa palauttaa salaisuutta manuaalisesti asiakkaalle.

Jos et ole vielä tunnistanut kehysympäristöä, pyydä agenttia tunnistamaan se projektitiedostojen perusteella. Astro- ja Next.js-vertailu voi auttaa ymmärtämään niiden eroja; NEXT_PUBLIC_-sääntöä ei voi soveltaa kaikkiin React-sovelluksiin.

Hosting-määritykset ovat yksi tekoälyagentin kanssa sovellusta työstettäessä tehtävistä asioista.

Muuttujan lisääminen Vercel-projektiin#

Tee vaiheet itse virallisessa hallintapaneelissa. Älä anna agentille oikeaa avainta lomakkeen täyttämistä varten äläkä liitä kuvakaappausta, jossa sen arvo näkyy.

1. Avaa Vercelin hallintapaneeli ja valitse oikea projekti. Älä luota pelkästään siihen, että tietovaraston nimi täsmää: tarkista, että määrität sen sovelluksen, jonka aiot avata.
2. Siirry projektin asetusten sivupalkissa kohtaan Environment Variables.
3. Kirjoita kenttään Name nimi, jota sovellus lukee, esimerkiksi SERVICE_API_KEY. Tämä on esimerkkinimi; jos koodi odottaa jotakin muuta nimeä, käytä sitä täsmälleen oikeassa muodossa.
4. Kirjoita kenttään Value arvo tunnistetietovarastostasi. Älä lisää sitä lähdekoodiin, keskusteluun tai tarkistuslokiin.
5. Valitse ympäristö, jossa asetusta tarvitaan. Käytä Preview-ympäristöä esikatseluversion tarkistamiseen ja Production-ympäristöä pääversiota varten. Älä automaattisesti määritä samaa salaisuutta kaikkiin ympäristöihin.
6. Jos Preview-asetus koskee tiettyä haaraa, tarkista valittu haara ja mahdolliset samannimiset ohitusarvot.
7. Napsauta Save.

Vercel asettaa projektimuuttujat saataville sekä koontivaiheessa että Vercel Functions -palvelintoimintojen suorittamisen aikana. Se, että arvo on saatavilla Vercelissä, ei kuitenkaan tarkoita, että sen voi lähettää selaimeen: se riippuu sovelluskoodista ja kehysympäristön säännöistä.

Miksi uusi käyttöönotto tarvitaan Save-painikkeen jälkeen#

Muuttujan tallentaminen ei muuta olemassa olevia käyttöönottoja. Vercelin dokumentaation mukaan projekti on otettava uudelleen käyttöön, jotta uusi asetus tulee käyttämääsi versioon.

Kun käytät Gitiä, voit luoda uuden Production-käyttöönoton puskemalla commitin haaralle, joka on määritetty kohdassa Production Branch, ja Preview-käyttöönoton puskemalla toiseen haaraan. Älä oleta, että päähaaran nimi on aina main: tarkista projektisi asetus. Tämän tulee olla tavanomainen, sovittu projektijulkaisu ilman salaisen tiedoston lisäämistä committiin.

Kun olet käynnistänyt käyttöönoton, odota koonnin valmistumista ja avaa uuden käyttöönoton URL-osoite. Pidä kirjaa sen URL-osoitteesta, ympäristöstä ja haarasta. Jos tarkistat yksittäisen käyttöönoton vanhan URL-osoitteen, uudet asetukset eivät näy siellä.

Next.js:ssä on vielä yksi huomioitava asia: esimerkiksi viittaukset process.env.NEXT_PUBLIC_RELEASE_LABEL korvataan arvoillaan komennon next build aikana. Arvo lukittuu koonnin jälkeen. Jos muutat asetusta käynnistämättä uutta koontia, jo toimitettua asiakaspuolen JavaScript-koodia ei kirjoiteta uudelleen.

Tuloksen tarkistaminen avainta paljastamatta#

Aloita turvallisella esimerkillä: nimenomaisesti ei-salaisella tunnisteella NEXT_PUBLIC_RELEASE_LABEL, jonka arvoksi asetetaan preview-check. Nämä ovat esimerkkejä nimestä ja tekstistä, eivät avain eivätkä tässä suoritettu testi. Jos Next.js-sovellus lukee tämän muuttujan suoraan käyttämällä process.env.NEXT_PUBLIC_RELEASE_LABEL, se voi näyttää tunnisteen käyttöliittymässä tarkoituksenmukaisessa paikassa uuden koonnin jälkeen. Tämä tarkistus vahvistaa vain, että julkinen asetus välitettiin sovellukselle.

Yksityinen avain tarkistetaan eri tavalla. Älä tulosta sen arvoa, osaa siitä, sen pituutta tai koko process.env-sisältöä. Älä luo julkista URL-osoitetta, joka palauttaa muuttujan sisällön. Tarkista ensin palvelimella vain, onko asetus ”olemassa / puuttuu”, ja tarkista sitten erikseen sovellustoiminto, joka käyttää palvelua. Asetuksen olemassaolo ei todista, että avain on kelvollinen tai että sillä on tarvittavat oikeudet.

Voit kirjata tulokset ilman salaisuuksia:

• projekti, ympäristö ja haara vastaavat määrityksessä valittuja;
• tarkistat sellaisen uuden käyttöönoton URL-osoitetta, joka luotiin muuttujan tallentamisen jälkeen;
• koonti on valmis ja tarvittava sovellustoiminto on suoritettu turvallisella testidatalla;
• salaisuus ei paljastu selaimessa, API-vastauksissa, lokeissa tai keskusteluissa.

Jos toiminto suorittaa maksun, lähettää viestin tai tekee jonkin muun seurauksellisen toiminnon, käytä palvelun määrittämää testitilaa. Kokoonpanon tarkistaminen ei itsessään anna lupaa todelliseen toimintaan.

Mitä tarkistaa, jos arvo on edelleen undefined#

undefined tarkoittaa, ettei arvoa saatu kyseisessä kohdassa, jossa sitä käytettiin. Tarkista nimi, ympäristö ja versio järjestyksessä äläkä muuta kaikkia asetuksia kerralla.

Kun olet tarkistanut nimen, ympäristön ja uuden version, toiminnossa ilmenevä virhe ei silti todista, että muuttuja aiheutti sen. Selvitä palvelinpuolen koodin tarkka virhe julkaisematta diagnostisia tietoja, jotka sisältävät salaisuuksia. Tämä opas ei lupaa ratkaista kaikkia HTTP 500 -vastauksia.

Omaan palvelimeen siirtyminen vaatii erilaisen menettelyn: katso opas projektin käyttöönottoon Coolifylla. Vercelin painikkeiden nimet ja määritysvaiheet eivät päde siihen.

Siirry Ailootiin.