Näin korjaat Supabase API-avaimen puuttumisen ympäristömuuttujista

Viimeksi varmistettu: 11. syyskuuta 2026. Lisäät Supabase URL-osoitteen ja API-avaimen .env-tiedostoon, käynnistät sovelluksen uudelleen ja saat silti virheen, kuten “Supabase API key not found” tai Supabasen oman virheen supabaseKey is required. Useimmissa tapauksissa avain on olemassa jossakin, mutta koodi, joka kutsuu createClient()-funktiota, saa vastaan undefined-arvon tai tyhjän merkkijonon.

Monien hämmentävien opastusten taustalla on myös tärkeä nimeämismuutos vuodelle 2026. Supabase lopettaa vanhojen anon- ja service_role-API-avainten käytön vuoden 2026 loppuun mennessä ja suosittelee nyt publishable (julkaistavia) avaimia julkiselle/asiakaspuolen koodille ja secret (salaisia) avaimia luotettavalle palvelinkoodille. Olemassa olevat vanhat avaimet voivat jatkaa toimintaansa migraation aikana, kunnes poistat ne käytöstä, mutta ympäristömuuttujan nimen ja koodin on edelleen vastattava toisiaan täsmälleen.

Nykyinen Supabasen dokumentaatio käyttää arvoja, kuten sb_publishable_... ja sb_secret_.... Katso virallinen Supabase API-avainten opas ja migraatio-opas julkaistaviin ja salaisiin avaimiin.

Nopea korjaus: varmista, että muuttujien nimet vastaavat kehyskehystä ja koodia

Nykyiselle Next.js-selainasiakkaalle Supabasen virallinen pikakäynnistys käyttää:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

ja:

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

if (!supabaseUrl || !supabaseKey) {
  throw new Error('Supabase environment variables are missing')
}

export const supabase = createClient(supabaseUrl, supabaseKey)

Nykyiselle Vite/React-selainasiakkaalle Supabasen virallinen React-pikakäynnistys käyttää:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

ja luet ne seuraavasti:

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

Palvelinpuolen koodille, joka todella tarvitsee laajennettuja oikeuksia, Supabasen API-avainten opas näyttää kuvion, kuten:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=sb_secret_...

Älä koskaan laita sb_secret_...-avainta muuttujaan, joka on tarkoituksellisesti altistettu selaimen koodille, kuten Vitessä VITE_*-muuttujaan tai Next.js:ssä NEXT_PUBLIC_*-muuttujaan. Supabase sanoo, että salaiset avaimet ohittavat rivitason tietoturvan (Row Level Security) ja niiden on pysyttävä kehittäjän hallinnoimissa backend-komponenteissa.

Vaihe 1: vahvista, että arvo todella puuttuu suorituksen aikana

Älä aloita avainten uudelleenluomisella tai pakettien uudelleenasentamisella. Todista ensin, mitä sovelluksesi vastaanottaa.

Nykyinen @supabase/supabase-js-asiakas tarkistaa asiakasrakentajalle annetun toisen argumentin ja heittää virheen supabaseKey is required., kun arvo on epätosi (falsy). Voit nähdä tämän toiminnan virallisesta supabase-js-lähdekoodista.

Lisää väliaikainen suojakoodi ennen createClient()-kutsua:

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

console.log('Supabase URL loaded:', Boolean(supabaseUrl))
console.log('Supabase key loaded:', Boolean(supabaseKey))
console.log(
  'Key type:',
  supabaseKey?.startsWith('sb_publishable_') ? 'publishable' : 'other/missing'
)

if (!supabaseUrl || !supabaseKey) {
  throw new Error('Supabase environment variables are missing')
}

Vitessä käytä samaa ideaa import.meta.env:n kanssa.

Älä tulosta koko salaista avainta. Virheenkorjauksessa boolean-arvo tai odotettu etuliite riittää. Julkaistava avain on suunniteltu julkisiin komponentteihin, mutta täydellisten tunnusten lokitus on silti tarpeetonta; salaista avainta ei saa koskaan altistaa asiakaslokeissa.

Huomaa myös, että TypeScript-syntaksi, kuten process.env.MY_KEY! tai process.env.MY_KEY as string, ei luo puuttuvaa arvoa suorituksen aikana. Se muuttaa vain sitä, mitä TypeScript uskoo tyypistä. Jos ympäristömuuttuja puuttuu, Supabase saa edelleen undefined-arvon.

Itsetarkistus: jos avaimen boolean-arvo on false, lopeta Supabasen käyttöoikeuksien, todennuksen tai rivitason tietoturvan virheenkorjaus. Sovellus ei ole vielä ladannut määrityksiä.

Vaihe 2: käytä nykyistä avaintyyppiä – ja tee vanhoista ja uusista nimistä johdonmukaisia

Avaa Supabase-projektisi Connect-valintaikkuna tai siirry kohtaan Settings → API Keys. Supabasen nykyinen dokumentaatio tunnistaa nimenomaisesti Settings → API Keys -kohdan paikaksi, jossa voit tarkastella kaikkia projektin API-avaimia.

Koodille, joka lähetetään käyttäjän selaimeen, mobiilisovellukseen, työpöytäsovellukseen tai muuhun julkiseen komponenttiin, käytä publishable (julkaistavaa) avainta. Supabasen mukaan julkaistava avain on turvallinen altistaa, koska tietokantapääsyä hallitaan edelleen käyttöoikeuksilla ja rivitason tietoturvalla. Backend-komponenteille, joita hallitset täysin, secret (salainen) avain tarjoaa laajennetut oikeudet ja ohittaa rivitason tietoturvan.

Migraatio vanhoista avaimista on yleinen syy "not found" -virheeseen, koska seuraavat yhdistelmät eivät ole ekvivalentteja ympäristömuuttujien niminä:

Vanha muuttuja, kuten NEXT_PUBLIC_SUPABASE_ANON_KEY, ei automaattisesti ole virheellinen. Jos projektissasi on edelleen aktiivinen vanha anon-avain ja koodisi lukee juuri tuota muuttujaa, se voi jatkaa toimintaansa Supabasen migraatiojakson aikana. Ongelma on siinä, että kopioit uuden julkaistavan avaimen yhteen muuttujanimeen, kun koodi lukee edelleen toista.

Itsetarkistus: etsi projektistasi SUPABASE_. Vertaa jokaista muuttujanimeä koodissa ympäristötiedostojesi ja käyttöönottoasetustesi tarkkoihin nimiin. Älä luota muistiin.

Vaihe 3: laita .env-tiedosto siihen paikkaan, josta kehyskehys todella lataa sen

Oikea avain väärässä tiedostosijainnissa on käytännössä puuttuva avain.

Next.js: pidä .env-tiedostot projektin juuressa

Next.js tukee natiivisti .env*-tiedostoja. Sen nykyinen ympäristömuuttujien opas sanoo, että jos käytät /src-hakemistoa, ympäristötiedostot kuuluvat edelleen projektin juureen, eivät /src-hakemiston sisään. Katso virallinen Next.js-ympäristömuuttujien opas.

Tyypillinen rakenne on:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # jos käytössä

Selainpuolen koodille Next.js altistaa vain muuttujat, joissa on NEXT_PUBLIC_-etuliite. Nämä arvot upotetaan selaimen pakettiin käännösaikana.

Vite: käytä VITE_-etuliitettä ja import.meta.env

Vite altistaa asiakasympäristömuuttujat import.meta.env:n kautta. Oletuksena vain VITE_-etuliitteellä varustetut nimet altistetaan asiakaskoodille. Virallinen Vite Env Variables and Modes -opas dokumentoi tämän suoraan.

Tämä toimii Vite-asiakkaassa:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

const url = import.meta.env.VITE_SUPABASE_URL
const key = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY

Tämä on normaalisti undefined Vite-selainkoodissa:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

koska siitä puuttuu oletusarvoinen VITE_-altistus etuliite.

Node/palvelinkoodi: älä kopioi selaimen etuliitteitä sokeasti

Palvelinkoodi lukee normaalisti process.env:stä. Jos avaimen ei tarvitse olla saatavilla selaimessa, älä lisää julkista etuliitettä vain sen näkyvyyden vuoksi. Supabase varoittaa nimenomaisesti, että salaiset avaimet ovat vain backend-käyttöön.

Itsetarkistus: varmista kolme asiaa yhdessä: env-tiedosto on sovelluksen juuressa, muuttujan nimi käyttää oikeaa kehyskehyksen etuliitettä ja koodi käyttää kehyskehyksen oikeaa pääsyfunktiota – process.env Next.js/Node.js:lle tai import.meta.env Vite-asiakaskoodille.

Vaihe 4: käynnistä kehityspalvelin uudelleen ympäristötiedostojen muuttamisen jälkeen

Ympäristömuuttujat ladataan yleensä, kun kehitysprosessi käynnistyy. Vite dokumentoi nimenomaisesti, että .env-tiedostot ladataan käynnistyksessä ja että palvelin tulisi käynnistää uudelleen muutosten jälkeen.

Pysäytä nykyinen prosessi ja käynnistä se uudelleen:

# Next.js
npm run dev

# Vite
npm run dev

Jos virhe ilmestyi vasta sen jälkeen, kun loit ympäristötiedoston palvelimen ollessa jo käynnissä, uudelleenkäynnistys voi olla koko korjaus.

Itsetarkistus: suorita väliaikaiset boolean-tarkistukset uudelleen. Jos arvot ovat nyt ladattu, poista tarpeeton virheenkorjaustuloste ja jatka normaalia Supabasen toimintaa.

Käytä suorituksen aikaista suojakoodia ongelman piilottamisen sijaan TypeScriptillä

Hyödyllinen tuotantokuvio on epäonnistua selkeällä konfiguraatioviestillä ennen Supabasen kutsumista:

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

if (!supabaseUrl) {
  throw new Error('NEXT_PUBLIC_SUPABASE_URL is missing')
}

if (!supabaseKey) {
  throw new Error('NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY is missing')
}

export const supabase = createClient(supabaseUrl, supabaseKey)

Tämä on parempi kuin:

createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
)

kun etsit vikoja, koska ei-null-assertio voi piilottaa TypeScript-varoituksen muuttamatta suorituksen aikaista arvoa.

Jos se toimii paikallisesti mutta epäonnistuu käyttöönoton jälkeen

Tämä on yleensä käyttöönottoympäristön ongelma, ei Supabase-projektin ongelma.

Paikallisia .env.local-tiedostoja ei yleensä lähetetä Git:iin – eikä niitä tulisi pitää tuotannon salaisuuksien toimittusmekanismina. Määritä samat muuttujanimet hosting-palveluntarjoajasi projektiasetuksissa.

Esimerkiksi Vercel dokumentoi erilliset Production, Preview ja Development -ympäristöt. Se toteaa myös, että muutokset ympäristömuuttujiin koskevat vain uusia käyttöönottoja, joten sinun on otettava sovellus uudelleen käyttöön niiden lisäämisen tai muuttamisen jälkeen. Katso Vercelin virallinen ympäristömuuttujien hallintaopas.

Tarkista:

• Onko muuttuja määritelty Production-ympäristölle, ei vain Preview:lle?
• Vastaako nimi täsmälleen koodia?
• Luotiinko uusi käyttöönotto muuttujan lisäämisen jälkeen?
• Oliko julkinen muuttuja olemassa, kun asiakaspaketti käännettiin?

Next.js:n julkiset muuttujat ovat käännösaikaisia arvoja

Next.js dokumentoi, että NEXT_PUBLIC_*-muuttujat upotetaan selaimeen JavaScriptiin käännösaikana. Kun sovellus on käännetty, suoritusympäristön muuttaminen ei uudelleenkirjoita näitä arvoja olemassa olevassa asiakaspaketissa. Jos käännet Docker-kuvan ilman NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY-muuttujaa ja injektoidaan se vasta, kun kontti käynnistyy, selaimen koodi voi edelleen sisältää puuttuvan käännösaikaisen arvon.

Korjaus: anna julkiset Supabase-arvot käännöksen aikana, joka tuottaa asiakaspaketin, tai suunnittele sovellus uudelleen tarjoamaan suorituksen aikainen konfiguraatio palvelinohjatun mekanismin kautta.

Vite korvaa myös asiakasympäristön arvot käännöksen aikana

Viten dokumentaatio sanoo, että import.meta.env-vakiot korvataan staattisesti paketoinnin aikana. Siksi, jos paikallinen kehitys toimii mutta tuotantopaketti ei, varmista, että VITE_SUPABASE_URL ja VITE_SUPABASE_PUBLISHABLE_KEY olivat olemassa käännösympäristössä – ei vain koneella, joka myöhemmin palvelee staattisia tiedostoja.

Monorepot: tarkista, mikä hakemisto on todellisuudessa sovelluksen juuri

Monorepo voi sisältää:

repo/
  package.json
  apps/
    web/
      package.json
      .env.local
      app/
  packages/
    ui/

Jos Next.js- tai Vite-komento suoritetaan apps/web:n ollessa sovelluksen juuri, ympäristötiedosto, joka on sijoitettu vain repo/.env.local:iin, ei välttämättä ole se tiedosto, jonka kehyskehys lataa. Vitessä envDir oletusarvoisesti projektin juuri, ja Next.js odottaa .env*-tiedostojaan Next.js-projektin juuressa.

Korjaus: tunnistaa hakemisto, joka sisältää sovelluksen package.json-tiedoston ja kehyskehyksen konfiguraation, ja laita env-tiedosto siihen paikkaan, jossa sovellus odottaa sitä, tai määritä ympäristöhakemisto nimenomaisesti, jos kehyskehys tukee sitä.

Supabase Edge Functions käyttää eri nykyisiä oletusmuuttujan nimiä

Jos virhe on Supabase Edge Function -toiminnon sisällä, älä kopioi sokeasti Next.js- tai Vite-esimerkkiä.

Supabasen nykyinen Edge Functions -ympäristömuuttujien dokumentaatio listaa näitä oletussalaisuuksia, muiden muassa:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Huomaa, että SUPABASE_PUBLISHABLE_KEYS ja SUPABASE_SECRET_KEYS ovat monikossa. Supabasen migraatio-opas selittää, että nämä uudet muuttujat sisältävät JSON-objekteja, jotka on avain API-avaimen nimellä. Oletussalaiselle avaimelle:

const secretKeys = JSON.parse(
  Deno.env.get('SUPABASE_SECRET_KEYS') ?? '{}'
)

const secretKey = secretKeys['default']

if (!secretKey) {
  throw new Error('Default Supabase secret key is missing')
}

Migraation aikana vanhat Edge Function -muuttujat, kuten SUPABASE_ANON_KEY ja SUPABASE_SERVICE_ROLE_KEY, voivat olla olemassa uusien avainsanakirjojen rinnalla. Älä oleta, että vanhan toiminto-opastuksen muuttujan nimi vastaa juuri luomaasi uutta avaintyyppiä.

Älä ratkaise virhettä altistamalla salaista avainta

Kiusallinen "korjaus" on lisätä NEXT_PUBLIC_ tai VITE_ palvelinsalaiseen, jotta selain voi lopulta lukea sen. Se voi poistaa puuttuvan muuttujan virheen luoden samalla tietoturvaongelman.

Supabasen nykyinen API-avainten opas on selkeä:

• Publishable key: tarkoitettu julkisiin komponentteihin, kuten selaimeen ja mobiilisovelluksiin.
• Secret key: tarkoitettu vain backend-komponentteihin, joita hallitset; se ohittaa rivitason tietoturvan.

Jos salainen avain on altistettu lähdekoodissa, julkisessa paketissa, kuvakaappauksessa tai repositoriossa, poista tai kierrätä se Supabasen API Keys -asetusten kautta pelkän ympäristömuuttujan nimen muuttamisen sijaan.

Yleiset oireet ja nopein tarkistus

Lopullinen itsetarkistus: varmista konfiguraatio oikeassa järjestyksessä

Ennen kuin julistat ongelman korjatuksi, suorita tämä tarkistuslista:

1. Vahvista, että Supabasen Project URL tulee projektista, jota todella aiot käyttää.
2. Selain/asiakaskoodille, vahvista, että käytät nykyistä publishable (julkaistavaa) avainta tai edelleen aktiivista vanhaa anon-avainta – et salaista avainta.
3. Vahvista, että koodi ja ympäristötiedosto käyttävät samoja muuttujan nimiä.
4. Next.js-asiakaskoodille, käytä NEXT_PUBLIC_* ja suoraa process.env.VARIABLE_NAME-viittausta.
5. Vite-asiakaskoodille, käytä VITE_* ja import.meta.env.VARIABLE_NAME.
6. Pidä .env.local sovelluksen juuressa äläkä /src-hakemiston sisällä.
7. Käynnistä kehityspalvelin uudelleen ympäristötiedostojen muokkaamisen jälkeen.
8. Tuotannossa, aseta arvot oikeaan käyttöönottoympäristöön ja käännä/ota uudelleen käyttöön.
9. Älä lokita tai altista sb_secret_...-avaimia.
10. Poista väliaikaiset debug-lokit, kun konfiguraatio on vahvistettu.

Kun createClient() alustuu ilman puuttuvan avaimen virhettä, ympäristömuuttujaongelma on ratkaistu. Jos seuraava Supabase-pyyntö palauttaa valtuutus-, rivitason tietoturva- tai taulun käyttöoikeusvirheen, käsittele se erillisenä ongelmana. Voimassa oleva API-avain ei takaa, että kutsujalla on oikeus lukea tai muokata jokaista riviä; Supabase erottaa nimenomaisesti API-avaimen tunnistuksen käyttäjän todennuksesta ja tietokannan valtuutuksesta.

Kestävä korjaus ei ole "nimeä avain uudelleen, kunnes se toimii". Se on neljän asian linjaaminen: nykyinen Supabase-avaintyyppi, ympäristömuuttujan nimi, kehyskehyksen altistussäännöt ja ympäristö, jossa sovellus todella käännetään tai suoritetaan. Kun nämä ovat yhteneväiset, Supabase-asiakas saa todellisen avaimen undefined-arvon sijaan, ja harhaanjohtava konfiguraatiosilmukka päättyy.