Kako popraviti napako "Supabase API Key Not Found" v spremenljivkah okolja

Zadnjič preverjeno: 11. september 2026. Dodate URL Supabase in ključ API v datoteko .env, znova zaženete aplikacijo in še vedno prejmete napako, kot je “Supabase API key not found” ali Supabasejeva lastna supabaseKey is required. V večini primerov ključ nekje obstaja, vendar koda, ki kliče createClient(), prejme undefined ali prazen niz.

Za mnogimi zmedeni tutoriali stoji tudi pomembna sprememba poimenovanja iz leta 2026. Supabase do konca leta 2026 ukinja zapuščinske ključe API anon in service_role ter zdaj priporoča publishable (javne) ključe za javno/klientsko kodo in secret (skrivne) ključe za zaupanja vredno strežniško kodo. Obstoječi zapuščinski ključi lahko med migracijo še naprej delujejo, dokler jih ne onemogočite, vendar se ime spremenljivke okolja in vaša koda še vedno morata natančno ujemati.

Trenutna dokumentacija Supabase uporablja vrednosti, kot so sb_publishable_... in sb_secret_.... Glejte uradni vodnik za ključe API Supabase in vodnik za migracijo na javne in skrivne ključe.

Hitra rešitev: uskladite imena spremenljivk s ogrodjem in kodo

Za trenutni Next.js brskalnik uradni hitri začetek Supabase uporablja:

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

in:

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)

Za trenutni Vite/React brskalnik uradni hitri začetek React Supabase uporablja:

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

in jih preberete z:

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

Za kodo samo na strežniku, ki resnično potrebuje povišan dostop, vodnik za ključe API Supabase prikazuje vzorec, kot je:

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

Nikoli ne postavite sb_secret_... v spremenljivko, ki je namenoma izpostavljena brskalniku, kot je spremenljivka Vite VITE_* ali spremenljivka Next.js NEXT_PUBLIC_*. Supabase pravi, da skrivni ključi zaobidejo varnost na ravni vrstic (Row Level Security) in morajo ostati v komponentah zaledja, ki jih nadzorujejo razvijalci.

Korak 1: potrdite, da vrednost dejansko manjka ob izvajanju

Ne začnite z regeneracijo ključev ali ponovno namestitvijo paketov. Najprej dokažite, kaj vaša aplikacija prejema.

Trenutni odjemalec @supabase/supabase-js preveri drugi argument, posredovan konstruktorskemu funkciji odjemalca, in vrže supabaseKey is required., ko je ta vrednost lažna (falsy). To obnašanje lahko vidite v uradni izvorni kodi supabase-js.

Dodajte začasno zaščito pred createClient():

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

Za Vite uporabite isto idejo z import.meta.env.

Ne izpisujte celotnega skrivnega ključa. Za odpravljanje napak je dovolj boolean ali pričakovana predpona. Javni ključ je zasnovan za javne komponente, vendar je beleženje celotnih poverilnic še vedno nepotrebno; skrivni ključ nikoli ne sme biti izpostavljen v dnevnikih odjemalca.

Upoštevajte tudi, da sintaksa TypeScript, kot je process.env.MY_KEY! ali process.env.MY_KEY as string, ne ustvari manjkajoče vrednosti ob izvajanju. Spremeni le to, kaj TypeScript verjame o tipu. Če spremenljivka okolja ni prisotna, Supabase še vedno prejme undefined.

Samopreverjanje: če je boolean za ključ false, prenehate z odpravljanjem napak dovoljenj Supabase, preverjanja pristnosti ali varnosti na ravni vrstic. Aplikacija še ni naložila konfiguracije.

Korak 2: uporabite trenutno vrsto ključa – in uskladite stara in nova imena

Odprite pogovorno okno Connect vašega projekta Supabase ali pojdite na Settings → API Keys. Trenutna dokumentacija Supabase izrecno navaja Settings → API Keys kot mesto za ogled vseh ključev API projekta.

Za kodo, ki se dostavi v uporabnikov brskalnik, mobilno aplikacijo, namizno aplikacijo ali drugo javno komponento, uporabite javni ključ (publishable key). Supabase pravi, da je javni ključ varno izpostaviti, ker je dostop do baze še vedno nadzorovan z dovoljenji in varnostjo na ravni vrstic. Za komponente zaledja, ki jih v celoti nadzorujete, skrivni ključ zagotavlja povišan dostop in zaobide varnost na ravni vrstic.

Migracija iz zapuščinskih ključev je pogost vir napake “not found”, ker naslednje kombinacije niso enakovredne kot imena spremenljivk okolja:

Starejša spremenljivka, kot je NEXT_PUBLIC_SUPABASE_ANON_KEY, ni samodejno neveljavna. Če ima vaš projekt še vedno aktiven zapuščinski ključ anon in vaša koda bere točno to spremenljivko, lahko še naprej deluje med obdobjem migracije Supabase. Težava je kopiranje novega javnega ključa v eno ime spremenljivke, medtem ko koda še vedno bere drugo.

Samopreverjanje: poiščite v svojem projektu SUPABASE_. Primerjajte vsako ime spremenljivke v kodi z natančnimi imeni v datotekah okolja in nastavitvah namestitve. Ne zanašajte se na spomin.

Korak 3: postavite datoteko .env tja, kjer jo vaše ogrodje dejansko naloži

Pravilen ključ na napačni lokaciji datoteke je dejansko manjkajoč ključ.

Next.js: ohranite datoteke .env v korenu projekta

Next.js ima vgrajeno podporo za datoteke .env*. Trenutni vodnik za spremenljivke okolja pravi, da če uporabljate imenik /src, datoteke okolja še vedno spadajo v koren projekta, ne v /src. Glejte uradni vodnik Next.js za spremenljivke okolja.

Tipična postavitev je:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # if used

Za kodo na strani brskalnika Next.js izpostavi samo spremenljivke, ki uporabljajo predpono NEXT_PUBLIC_. Te vrednosti so vgrajene v sveženj brskalnika ob gradnji.

Vite: uporabite VITE_ in import.meta.env

Vite izpostavi spremenljivke okolja odjemalca prek import.meta.env. Privzeto so klientski kodi izpostavljena samo imena s predpono VITE_. To neposredno dokumentira uradni vodnik Vite za spremenljivke okolja in načine.

To bo delovalo v odjemalcu Vite:

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

To bo običajno undefined v kodi brskalnika Vite:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

ker manjka privzeta predpona za izpostavljanje VITE_.

Koda Node/strežnik: ne kopirajte slepo predpon brskalnika

Strežniška koda običajno bere iz process.env. Če ključ ne mora biti na voljo v brskalniku, ne dodajajte javne predpone samo zato, da bi bil viden. Supabase izrecno opozarja, da so skrivni ključi samo za zaledje.

Samopreverjanje: preverite tri stvari hkrati: datoteka env je v korenu aplikacije, ime spremenljivke uporablja pravilno predpono ogrodja in koda uporablja pravilen dostopnik ogrodja – process.env za Next.js/Node ali import.meta.env za kodo odjemalca Vite.

Korak 4: znova zaženite razvojni strežnik po spremembi datotek okolja

Spremenljivke okolja se običajno naložijo ob zagonu razvojnega procesa. Vite izrecno dokumentira, da se datoteke .env naložijo ob zagonu in da morate po spremembah znova zagnati strežnik.

Ustavite trenutni proces in ga znova zaženite:

# Next.js
npm run dev

# Vite
npm run dev

Če se je napaka pojavila šele potem, ko ste ustvarili datoteko okolja, medtem ko je strežnik že tekel, je lahko ponovni zagon celotna rešitev.

Samopreverjanje: znova zaženite začasne preglede boolean. Če so vrednosti zdaj naložene, odstranite nepotrebne izpise za odpravljanje napak in nadaljujte z normalnim delovanjem Supabase.

Uporabite zaščito ob izvajanju namesto skrivanja problema s TypeScript

Koristen vzorec za produkcijo je, da ne uspe z jasnim sporočilom o konfiguraciji pred klicem Supabase:

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)

To je bolje kot:

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

ko odpravljate težave, ker lahko trditev o ne-ničnosti skrije opozorilo TypeScript, ne da bi spremenila vrednost ob izvajanju.

Če deluje lokalno, a ne uspe po namestitvi

To je običajno težava okolja namestitve, ne težava projekta Supabase.

Lokalne datoteke .env.local običajno niso oddane v Git – in jih ne smete obravnavati kot mehanizem za dostavo skrivnosti v produkciji. Konfigurirajte ista imena spremenljivk v nastavitvah projekta vašega gostiteljskega ponudnika.

Na primer, Vercel dokumentira ločena okolja Production, Preview in Development. Prav tako navaja, da se spremembe spremenljivk okolja uporabijo samo za nove namestitve, zato morate po dodajanju ali spreminjanju znova namestiti. Glejte uradni vodnik Vercel za upravljanje spremenljivk okolja.

Preverite:

• Ali je spremenljivka definirana za Production, ne samo za Preview?
• Ali se ime natančno ujema s kodo?
• Ali je bila po dodajanju spremenljivke ustvarjena nova namestitev?
• Ali je bila javna spremenljivka prisotna ob gradnji svežnja odjemalca?

Javne spremenljivke Next.js so vrednosti ob gradnji

Next.js dokumentira, da so spremenljivke NEXT_PUBLIC_* vgrajene v JavaScript brskalnika ob gradnji. Po zgradbi aplikacije sprememba okolja ob izvajanju ne prepiše teh vrednosti v obstoječem svežnju odjemalca. Če zgradite sliko Docker brez NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY in jo kasneje vstavite šele ob zagonu kontejnerja, lahko koda brskalnika še vedno vsebuje manjkajočo vrednost ob gradnji.

Popravek: zagotovite javne vrednosti Supabase med gradnjo, ki proizvaja sveženj odjemalca, ali preoblikujte aplikacijo, da zagotovi konfiguracijo ob izvajanju prek mehanizma, ki ga nadzoruje strežnik.

Vite tudi zamenja vrednosti okolja odjemalca med gradnjo

Dokumentacija Vite pravi, da so konstante import.meta.env statično zamenjane med združevanjem. Zato, če lokalni razvoj deluje, a produkcijski sveženj ne, preverite, ali sta VITE_SUPABASE_URL in VITE_SUPABASE_PUBLISHABLE_KEY obstajala v okolju gradnje – ne samo na stroju, ki kasneje streže statične datoteke.

Monorepos: preverite, kateri imenik je dejansko koren aplikacije

Monorepo lahko vsebuje:

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

Če se ukaz Next.js ali Vite izvaja z apps/web kot korenom aplikacije, datoteka okolja, postavljena samo na repo/.env.local, morda ni datoteka, ki jo naloži ogrodje. Privzeta vrednost envDir za Vite je koren projekta, Next.js pa pričakuje svoje datoteke .env* v korenu projekta Next.js.

Popravek: identificirajte imenik, ki vsebuje package.json aplikacije in konfiguracijo ogrodja, nato postavite datoteko env tja, kjer jo pričakuje ta aplikacija, ali izrecno konfigurirajte imenik okolja, če to podpira ogrodje.

Funkcije Edge Supabase uporabljajo drugačna trenutna privzeta imena spremenljivk

Če je napaka znotraj funkcije Edge Supabase, ne kopirajte slepo primera Next.js ali Vite.

Trenutna dokumentacija Supabase za spremenljivke okolja funkcij Edge med drugim navaja te privzete skrivnosti:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Opazite, da sta SUPABASE_PUBLISHABLE_KEYS in SUPABASE_SECRET_KEYS v množini. Vodnik za migracijo Supabase pojasnjuje, da te nove spremenljivke vsebujejo predmete JSON, indeksirane z imenom ključa API. Za privzeti skrivni ključ:

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

Med migracijo lahko starejše spremenljivke funkcij Edge, kot sta SUPABASE_ANON_KEY in SUPABASE_SERVICE_ROLE_KEY, obstajajo poleg novih slovarjev ključev. Ne predpostavljajte, da se ime spremenljivke iz starega tutoriala za funkcije ujema z novo vrsto ključa, ki ste jo pravkar ustvarili.

Ne rešite napake z izpostavitvijo skrivnega ključa

Pričak “popravek” je dodati NEXT_PUBLIC_ ali VITE_ strežniški skrivnosti, da jo lahko brskalnik končno prebere. To lahko odpravi napako manjkajoče spremenljivke, hkrati pa ustvari varnostno težavo.

Trenutni vodnik za ključe API Supabase je jasen:

• Javni ključ (Publishable key): namenjen javnim komponentam, kot so aplikacije za brskalnik in mobilne naprave.
• Skrivni ključ (Secret key): namenjen samo komponentam zaledja, ki jih nadzorujete; zaobide varnost na ravni vrstic.

Če je bil skrivni ključ izpostavljen v izvorni kodi, javnem svežnju, posnetku zaslona ali repozitoriju, ga odstranite ali zamenjajte prek nastavitev API Keys v Supabase, namesto da bi samo preimenovali spremenljivko okolja.

Pogosti simptomi in najhitrejši pregled

Končno samopreverjanje: preverite konfiguracijo v pravilnem vrstnem redu

Preden razglasite težavo za odpravljeno, izvedite ta seznam:

1. Potrdite, da URL projekta Supabase prihaja iz projekta, ki ga dejansko nameravate uporabljati.
2. Za kodo brskalnika/odjemalca potrdite, da uporabljate trenutni javni ključ ali še vedno aktiven zapuščinski ključ anon – ne skrivnega ključa.
3. Potrdite, da koda in datoteka okolja uporabljata ista imena spremenljivk.
4. Za kodo odjemalca Next.js uporabite NEXT_PUBLIC_* in neposredne reference process.env.VARIABLE_NAME.
5. Za kodo odjemalca Vite uporabite VITE_* in import.meta.env.VARIABLE_NAME.
6. Ohranite .env.local v korenu aplikacije, ne znotraj /src.
7. Znova zaženite razvojni strežnik po urejanju datotek okolja.
8. Za produkcijo nastavite vrednosti v pravilnem okolju namestitve in ponovno zgradite/ponovno namestite.
9. Ne beležite ali izpostavljajte ključev sb_secret_....
10. Odstranite začasne dnevnike za odpravljanje napak, ko je konfiguracija potrjena.

Ko se createClient() inicializira brez napake manjkajočega ključa, je težava s spremenljivkami okolja rešena. Če naslednja zahteva Supabase vrne napako pooblastila, varnosti na ravni vrstic ali dovoljenja za tabelo, to obravnavajte kot ločeno težavo. Veljaven ključ API ne zagotavlja, da je klicatelju dovoljeno brati ali spreminjati vsako vrstico; Supabase namerno loči identifikacijo ključa API od preverjanja pristnosti uporabnika in pooblastila baze podatkov.

Trajna rešitev ni “preimenuj ključ, dokler ne deluje”. Je uskladitev štirih stvari: trenutne vrste ključa Supabase, imena spremenljivke okolja, pravil izpostavljanja ogrodja in okolja, v katerem je aplikacija dejansko zgrajena ali izvedena. Ko se te strinjajo, odjemalec Supabase prejme pravi ključ namesto undefined in zavajajoča zanka konfiguracije se konča.