Hogyan javítsd meg a „Supabase API kulcs nem található a környezeti változókban” hibát

Utolsó ellenőrzés: 2026. szeptember 11. Hozzáadod a Supabase URL-t és az API kulcsot egy .env fájlhoz, újraindítod az alkalmazást, és még mindig olyan hibát kapsz, mint a „Supabase API key not found” vagy a Supabase saját supabaseKey is required. hibaüzenete. Az esetek többségében a kulcs valahol létezik, de a createClient()-t hívó kód undefined értéket vagy üres karakterláncot kap.

Számos zavaros tutorial mögött egy fontos 2026-os elnevezési változás áll. A Supabase 2026 végéig elavulttá teszi a régi anon és service_role API kulcsokat, és most a publishable (publikus) kulcsokat ajánlja nyilvános/ügyféloldali kódhoz, valamint a secret (titkos) kulcsokat megbízható szerveroldali kódhoz. A meglévő régi kulcsok a migráció során továbbra is működhetnek, amíg le nem tiltod őket, de a környezeti változó neve és a kódnak pontosan meg kell egyeznie.

A jelenlegi Supabase dokumentáció olyan értékeket használ, mint a sb_publishable_... és a sb_secret_.... Lásd a hivatalos Supabase API kulcs útmutatót és a migrációs útmutatót a publikus és titkos kulcsokhoz.

Gyors megoldás: győződj meg róla, hogy a változónevek egyeznek a keretrendszerrel és a kóddal

Egy jelenlegi Next.js böngésző kliens esetén a Supabase hivatalos gyorsindítása a következőt használja:

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

és:

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)

Egy jelenlegi Vite/React böngésző kliens esetén a Supabase hivatalos React gyorsindítása a következőt használja:

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

és így olvasod be őket:

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

Szerveroldali kódhoz, amelynek valóban emelt szintű hozzáférésre van szüksége, a Supabase API-kulcs útmutatója olyan mintát mutat, mint:

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

Soha ne tedd az sb_secret_... kulcsot olyan változóba, amely szándékosan ki van téve a böngészőkódoknak, például egy Vite VITE_* változóba vagy egy Next.js NEXT_PUBLIC_* változóba. A Supabase azt mondja, hogy a titkos kulcsok megkerülik a Sor szintű biztonságot (Row Level Security), és fejlesztő által irányított backend komponensekben kell maradniuk.

1. lépés: erősítsd meg, hogy az érték valóban hiányzik futásidőben

Ne kezdj kulcsok újragenerálásával vagy csomagok újratelepítésével. Először bizonyítsd be, mit kap az alkalmazásod.

A jelenlegi @supabase/supabase-js kliens ellenőrzi a kliens konstruktorának átadott második argumentumot, és supabaseKey is required. hibát dob, ha ez az érték hamis (falsy). Ezt a viselkedést a hivatalos supabase-js forráskódban láthatod.

Adj hozzá egy ideiglenes védelmet a createClient() előtt:

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')
}

Vite esetén használd ugyanazt az ötletet az import.meta.env segítségével.

Ne nyomtasd ki a teljes titkos kulcsot. Hibakereséshez elég egy boolean érték vagy a várt előtag. A publikus kulcs nyilvános komponensekhez van tervezve, de a teljes hitelesítő adatok naplózása továbbra is felesleges; a titkos kulcsot soha nem szabad kitenni ügyféloldali naplókban.

Vedd figyelembe azt is, hogy az olyan TypeScript szintaxis, mint a process.env.MY_KEY! vagy a process.env.MY_KEY as string, nem hoz létre hiányzó értéket futásidőben. Csak azt változtatja meg, amit a TypeScript a típusról hisz. Ha a környezeti változó hiányzik, a Supabase továbbra is undefined értéket kap.

Önellenőrzés: ha a kulcs boolean értéke false, állj le a Supabase engedélyek, hitelesítés vagy Sor szintű biztonság hibakeresésével. Az alkalmazás még nem töltötte be a konfigurációt.

2. lépés: használd a jelenlegi kulcstípust – és tedd konzisztenssé a régi és új neveket

Nyisd meg a Supabase projekted Connect párbeszédpanelét, vagy menj a Settings → API Keys menüpontra. A Supabase jelenlegi dokumentációja kifejezetten a Settings → API Keys helyet jelöli meg, ahol az összes projekt API kulcs megtekinthető.

Annak a kódnak, amely a felhasználó böngészőjébe, mobilalkalmazásába, asztali alkalmazásába vagy más nyilvános komponensébe kerül, publishable (publikus) kulcsot használj. A Supabase azt mondja, hogy a publikus kulcs biztonságosan kitett, mert az adatbázis-hozzáférést továbbra is jogosultságok és Sor szintű biztonság szabályozza. Az általad teljesen irányított backend komponensekhez egy secret (titkos) kulcs emelt szintű hozzáférést biztosít és megkerüli a Sor szintű biztonságot.

A régi kulcsokról való átállás gyakori forrása a „not found” hibának, mert a következő kombinációk nem egyenértékűek környezeti változó névként:

Egy régebbi változó, mint a NEXT_PUBLIC_SUPABASE_ANON_KEY, nem automatikusan érvénytelen. Ha a projektedben még mindig van egy aktív régi anon kulcs, és a kódod ezt a pontos változót olvassa, akkor a Supabase migrációs időszakában továbbra is működhet. A probléma az, hogy egy új publikus kulcsot másolunk egy változónévbe, miközben a kód még mindig egy másikat olvas.

Önellenőrzés: keress rá a projektedben a SUPABASE_ szóra. Hasonlítsd össze a kódban lévő minden változónevet a környezeti fájlokban és a telepítési beállításokban lévő pontos nevekkel. Ne bízz a memóriádban.

3. lépés: tedd a .env fájlt oda, ahonnan a keretrendszered valóban betölti

Egy helyes kulcs rossz fájlhelyen gyakorlatilag hiányzó kulcs.

Next.js: tartsd a .env fájlokat a projekt gyökerében

A Next.js beépített támogatást nyújt a .env* fájlokhoz. Jelenlegi környezeti változó útmutatója azt mondja, hogy ha /src könyvtárat használsz, a környezeti fájlok továbbra is a projekt gyökerébe tartoznak, nem a /src mappába. Lásd a hivatalos Next.js környezeti változó útmutatót.

Egy tipikus elrendezés:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # ha használatban van

Böngészőoldali kódhoz a Next.js csak azokat a változókat teszi közzé, amelyek a NEXT_PUBLIC_ előtagot használják. Ezek az értékek beépülnek a böngésző bundle-be fordítási időben.

Vite: használj VITE_ előtagot és import.meta.env-t

A Vite az ügyféloldali környezeti változókat az import.meta.env révén teszi közzé. Alapértelmezés szerint csak a VITE_ előtaggal rendelkező nevek kerülnek ki az ügyfélkódba. A hivatalos Vite Env Variables and Modes útmutató ezt közvetlenül dokumentálja.

Ez működni fog egy Vite kliensben:

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

Ez általában undefined lesz a Vite böngészőkódban:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

mert hiányzik belőle az alapértelmezett VITE_ közzétételi előtag.

Node/szerver kód: ne másold vakon a böngésző előtagokat

A szerverkód általában a process.env-ből olvas. Ha egy kulcsnak nem kell elérhetőnek lennie a böngészőben, ne adj hozzá nyilvános előtagot csak azért, hogy láthatóvá tedd. A Supabase kifejezetten figyelmeztet, hogy a titkos kulcsok csak backendhez valók.

Önellenőrzés: ellenőrizd együtt a három dolgot: az env fájl az alkalmazás gyökerében van, a változónév a helyes keretrendszer előtagot használja, és a kód a keretrendszer helyes hozzáférési módszerét használja – process.env a Next.js/Node esetén vagy import.meta.env a Vite ügyfélkód esetén.

4. lépés: indítsd újra a fejlesztői szervert a környezeti fájlok módosítása után

A környezeti változókat általában a fejlesztési folyamat indításakor töltik be. A Vite kifejezetten dokumentálja, hogy a .env fájlok indításkor töltődnek be, és a változtatások után újra kell indítani a szervert.

Állítsd le a jelenlegi folyamatot, és indítsd újra:

# Next.js
npm run dev

# Vite
npm run dev

Ha a hiba csak akkor jelent meg, amikor létrehoztad a környezeti fájlt, miközben a szerver már futott, akkor az újraindítás lehet a teljes megoldás.

Önellenőrzés: futtasd újra az ideiglenes boolean ellenőrzéseket. Ha az értékek most már betöltődtek, távolítsd el a felesleges hibakeresési kimenetet, és folytasd a normál Supabase művelettel.

Használj futásidőbeli védelmet ahelyett, hogy elrejtenéd a problémát a TypeScripttel

Egy hasznos élesítési minta, hogy egyértelmű konfigurációs üzenettel hibázzunk el, mielőtt meghívnánk a Supabase-t:

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)

Ez jobb, mint:

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

amikor hibát keresel, mert a nem-null assertió elrejtheti a TypeScript figyelmeztetését anélkül, hogy megváltoztatná a futásidőbeli értéket.

Ha helyileg működik, de telepítés után elbukik

Ez általában egy telepítési környezeti probléma, nem egy Supabase projekt probléma.

A helyi .env.local fájlokat általában nem committoljuk a Gitbe – és nem kell őket éles titokszolgáltatási mechanizmusként kezelni. Konfiguráld ugyanazokat a változóneveket a hosting szolgáltató projektbeállításaiban.

Például a Vercel külön Production, Preview és Development környezeteket dokumentál. Azt is állítja, hogy a környezeti változók változtatásai csak új telepítésekre vonatkoznak, ezért újra kell telepítened a hozzáadásuk vagy módosításuk után. Lásd a Vercel hivatalos környezeti változó kezelési útmutatóját.

Ellenőrizd:

• Definiálva van-e a változó a Production környezetben, nem csak a Preview-ben?
• Pontosan egyezik-e a név a kóddal?
• Létrejött-e új telepítés a változó hozzáadása után?
• Jelen volt-e a nyilvános változó, amikor az ügyfél bundle-t felépítették?

A Next.js nyilvános változói fordítási időbeli értékek

A Next.js dokumentálja, hogy a NEXT_PUBLIC_* változók fordítási időben épülnek be a böngésző JavaScriptbe. Miután az alkalmazás felépült, a futásidőbeli környezet megváltoztatása nem írja át ezeket az értékeket a meglévő ügyfél bundle-ben. Ha egy Docker image-et úgy építesz fel, hogy nincs benne NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, és később csak a konténer indításakor injektálod be, a böngészőkód továbbra is tartalmazhatja a hiányzó fordítási időbeli értéket.

Megoldás: biztosítsd a nyilvános Supabase értékeket a kliens bundle-t előállító build során, vagy tervezd át az alkalmazást úgy, hogy futásidőbeli konfigurációt biztosítson egy szerver által irányított mechanizmuson keresztül.

A Vite is helyettesíti az ügyfél env értékeket a build során

A Vite dokumentációja szerint az import.meta.env konstansok statikusan helyettesítésre kerülnek a bundling során. Ezért, ha a helyi fejlesztés működik, de az éles bundle nem, ellenőrizd, hogy a VITE_SUPABASE_URL és a VITE_SUPABASE_PUBLISHABLE_KEY jelen volt-e a build környezetben – nem csak azon a gépen, amely később kiszolgálja a statikus fájlokat.

Monorepók: ellenőrizd, melyik könyvtár az alkalmazás gyökere valójában

Egy monorepo tartalmazhat:

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

Ha a Next.js vagy Vite parancs az apps/web könyvtárat használja alkalmazásgyökérként, egy csak a repo/.env.local helyre helyezett környezeti fájl lehet, hogy nem az a fájl, amelyet a keretrendszer betölt. A Vite envDir alapértelmezése a projekt gyökere, és a Next.js a .env* fájlokat a Next.js projekt gyökerében várja.

Megoldás: azonosítsd azt a könyvtárat, amely tartalmazza az alkalmazás package.json fájlját és a keretrendszer konfigurációját, majd tedd az env fájlt oda, ahonnan az az alkalmazás várja, vagy explicit konfiguráld a környezeti könyvtárat, ha a keretrendszer ezt támogatja.

A Supabase Edge Functions eltérő jelenlegi alapértelmezett változóneveket használ

Ha a hiba egy Supabase Edge Functionön belül van, ne másold vakon egy Next.js vagy Vite példát.

A Supabase jelenlegi Edge Functions környezeti változó dokumentációja többek között ezeket az alapértelmezett titkokat sorolja fel:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Vedd észre, hogy a SUPABASE_PUBLISHABLE_KEYS és a SUPABASE_SECRET_KEYS többes számban van. A Supabase migrációs útmutatója elmagyarázza, hogy ezek az új változók API-kulcs név szerint kulcsolt JSON objektumokat tartalmaznak. Egy alapértelmezett titkos kulcshoz:

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')
}

A migráció során a régi Edge Function változók, mint a SUPABASE_ANON_KEY és a SUPABASE_SERVICE_ROLE_KEY, létezhetnek az új kulcsszótárak mellett. Ne feltételezd, hogy egy régi függvény tutorialból származó változónév egyezik az újonnan létrehozott kulcstípussal.

Ne oldd meg a hibát egy titkos kulcs kitételével

Egy csábító „megoldás”, hogy hozzáadunk NEXT_PUBLIC_ vagy VITE_ előtagot egy szerver titokhoz, hogy a böngésző végre el tudja olvasni. Ez megszüntetheti a hiányzó változó hibát, miközben biztonsági problémát teremt.

A Supabase jelenlegi API-kulcs útmutatója egyértelmű:

• Publikus kulcs: nyilvános komponensekhez szánva, mint a böngésző és mobilalkalmazások.
• Titkos kulcs: csak az általad irányított backend komponensekhez szánva; megkerüli a Sor szintű biztonságot.

Ha egy titkos kulcs kitett forráskódban, nyilvános bundle-ben, képernyőképen vagy repóban, távolítsd el vagy forgasd át a Supabase API Keys beállításaiban, ahelyett, hogy egyszerűen átneveznéd a környezeti változót.

Gyakori tünetek és a leggyorsabb ellenőrzés

Végső önellenőrzés: ellenőrizd a konfigurációt a helyes sorrendben

Mielőtt kijelentenéd, hogy a probléma megoldódott, futtasd végig ezt a listát:

1. Erősítsd meg, hogy a Supabase Project URL abból a projektből származik, amelyet valóban használni szeretnél.
2. Böngésző/ügyfél kódhoz erősítsd meg, hogy jelenlegi publishable kulcsot vagy egy még aktív régi anon kulcsot használsz – nem titkos kulcsot.
3. Erősítsd meg, hogy a kód és a környezeti fájl ugyanazokat a változóneveket használja.
4. Next.js ügyfél kódhoz használj NEXT_PUBLIC_* előtagot és közvetlen process.env.VÁLTOZÓNÉV hivatkozásokat.
5. Vite ügyfél kódhoz használj VITE_* előtagot és import.meta.env.VÁLTOZÓNÉV-et.
6. Tartsd a .env.local fájlt az alkalmazás gyökerében, ne a /src mappában.
7. Indítsd újra a fejlesztői szervert a környezeti fájlok szerkesztése után.
8. Éles környezetben állítsd be az értékeket a helyes telepítési környezetben, és építsd újra/telepítsd újra.
9. Ne naplózz és ne tegyél ki sb_secret_... kulcsokat.
10. Távolítsd el az ideiglenes hibakeresési naplókat, miután a konfiguráció megerősítésre került.

Amikor a createClient() a hiányzó kulcs hiba nélkül inicializálódik, a környezeti változó probléma megoldódott. Ha a következő Supabase kérés engedélyezési, Sor szintű biztonsági vagy tábla engedélyezési hibát ad vissza, azt külön problémaként kezeld. Egy érvényes API kulcs nem garantálja, hogy a hívó engedélyt kap minden sor olvasására vagy módosítására; a Supabase szándékosan szétválasztja az API-kulcs azonosítását a felhasználói hitelesítéstől és az adatbázis engedélyezéstől.

A tartós megoldás nem az, hogy „addig nevezd át a kulcsot, amíg működik”. Az, hogy összehangolsz négy dolgot: a jelenlegi Supabase kulcstípust, a környezeti változó nevét, a keretrendszer közzétételi szabályait, és azt a környezetet, amelyben az alkalmazást valóban felépítik vagy futtatják. Ha ezek megegyeznek, a Supabase kliens valódi kulcsot kap az undefined helyett, és a félrevezető konfigurációs ciklus véget ér.