Kaip išspręsti Supabase API rakto neradimo aplinkos kintamuosiuose klaidą

Paskutinį kartą patikrinta: 2026 m. rugsėjo 11 d. Pridedate savo Supabase URL ir API raktą į .env failą, paleidžiate programą iš naujo, bet vis tiek gaunate klaidą, pvz., “Supabase API key not found” arba pačios Supabase klaidą supabaseKey is required. Daugeliu atvejų raktas egzistuoja kažkur, tačiau kodas, kviečiantis createClient(), gauna undefined arba tuščią eilutę.

Už daugelio painių vadovėlių slypi svarbus 2026 m. pavadinimų pakeitimas. Supabase iki 2026 m. pabaigos atsisako senų anon ir service_role API raktų ir dabar rekomenduoja naudoti publishable (viešai prieinamus) raktus viešajam/kliento kodui bei secret (slaptus) raktus patikimam serverio kodui. Esami seni raktai gali toliau veikti migracijos laikotarpiu, kol jų neįjungiate, tačiau jūsų aplinkos kintamojo pavadinimas ir kodas vis tiek turi tiksliai sutapti.

Dabartinė Supabase dokumentacija naudoja tokias reikšmes kaip sb_publishable_... ir sb_secret_.... Peržiūrėkite oficialų Supabase API raktų vadovą ir migracijos vadovą į viešai prieinamus ir slaptus raktus.

Greitas sprendimas: suderinkite kintamųjų pavadinimus su karkasu ir kodu

Dabartiniam Next.js naršyklės klientui oficialus Supabase greitas paleidimas naudoja:

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

ir:

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)

Dabartiniam Vite/React naršyklės klientui oficialus Supabase React greitas paleidimas naudoja:

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

ir skaitote juos taip:

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

Tik serveriui skirtam kodui, kuriam iš tikrųjų reikia padidintų prieigos teisių, Supabase API raktų vadovas rodo tokį pavyzdį:

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

Niekada nedėkite sb_secret_... į kintamąjį, kuris yra sąmoningai atskleidžiamas naršyklės kodui, pvz., Vite VITE_* kintamąjį arba Next.js NEXT_PUBLIC_* kintamąjį. Supabase teigia, kad slapti raktai apeina eilučių lygio saugą (Row Level Security) ir turi likti kūrėjo valdomuose backend komponentuose.

1 žingsnis: patvirtinkite, kad reikšmė iš tikrųjų trūksta vykdymo metu

Nesiraskite naujų raktų ar neperdiekite paketų. Pirmiausia įrodykite, ką gauna jūsų programa.

Dabartinis @supabase/supabase-js klientas tikrina antrąjį argumentą, perduotą jo kliento konstruktoriui, ir meta klaidą supabaseKey is required., kai ši reikšmė yra klaidinga (falsy). Šį elgesį galite pamatyti oficialiame supabase-js šaltinyje.

Prieš createClient() pridėkite laikiną apsaugą:

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 atveju naudokite tą pačią idėją su import.meta.env.

Nespausdinkite viso slapto rakto. Derinimo metu pakanka loginės reikšmės arba tikėtino prefikso. Viešai prieinamas raktas yra skirtas viešiems komponentams, tačiau vis tiek nereikalinga loginti pilnus kredencialus; slaptas raktas niekada neturi būti atskleistas kliento žurnaluose.

Taip pat atkreipkite dėmesį, kad TypeScript sintaksė, tokia kaip process.env.MY_KEY! arba process.env.MY_KEY as string, nesukuria trūkstamos reikšmės vykdymo metu. Ji tik pakeičia tai, ką TypeScript mano apie tipą. Jei aplinkos kintamasis yra neegzistuojantis, Supabase vis tiek gauna undefined.

Savikontrolė: jei rakto loginė reikšmė yra false, nustokite derinti Supabase leidimus, autentifikaciją ar eilučių lygio saugą. Programa dar neįkėlė konfigūracijos.

2 žingsnis: naudokite dabartinį rakto tipą – ir suderinkite senus bei naujus pavadinimus

Atidarykite savo Supabase projekto Connect dialogą arba eikite į Settings → API Keys. Dabartinė Supabase dokumentacija aiškiai nurodo Settings → API Keys kaip vietą, kurioje galima peržiūrėti visus projekto API raktus.

Kodui, kuris siunčiamas į vartotojo naršyklę, mobilųją programą, darbalaukio programą ar kitą viešą komponentą, naudokite publishable (viešai prieinamą) raktą. Supabase teigia, kad viešai prieinamas raktas yra saugus atskleisti, nes duomenų bazės prieiga vis tiek valdoma per leidimus ir eilučių lygio saugą. Backend komponentams, kuriuos visiškai kontroliuojate, secret (slaptas) raktas suteikia padidintas prieigos teises ir apeina eilučių lygio saugą.

Migracija nuo senų raktų yra dažna „nerasta“ klaidos priežastis, nes šie deriniai kaip aplinkos kintamųjų pavadinimai nėra ekvivalentiški:

Senesnis kintamasis, pvz., NEXT_PUBLIC_SUPABASE_ANON_KEY, nėra automatiškai negaliojantis. Jei jūsų projekte vis dar yra aktyvus senas anon raktas ir jūsų kodas skaito būtent tą kintamąjį, jis gali toliau veikti Supabase migracijos laikotarpiu. Problema yra naujo viešai prieinamo rakto kopijavimas į vieną kintamojo pavadinimą, kai kodas vis dar skaito kitą.

Savikontrolė: ieškokite savo projekte SUPABASE_. Palyginkite kiekvieną kintamojo pavadinimą kode su tiksliais pavadinimais jūsų aplinkos failuose ir diegimo nustatymuose. Nesikliaukite atmintimi.

3 žingsnis: įdėkite .env failą ten, kur jūsų karkasas jį iš tikrųjų įkelia

Teisingas raktas neteisingoje failo vietoje yra praktiškai trūkstamas raktas.

Next.js: laikykite .env failus projekto šaknyje

Next.js turi integruotą palaikymą .env* failams. Jo dabartinis aplinkos kintamųjų vadovas teigia, kad jei naudojate /src katalogą, aplinkos failai vis tiek turi būti projekto šaknyje, o ne /src viduje. Peržiūrėkite oficialų Next.js aplinkos kintamųjų vadovą.

Tipiškas išdėstymas yra:

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

Naršyklės pusės kodui Next.js atskleidžia tik tuos kintamuosius, kurie naudoja NEXT_PUBLIC_ prefiksą. Šios reikšmės yra įterpiamos į naršyklės paketą kūrimo metu.

Vite: naudokite VITE_ ir import.meta.env

Vite atskleidžia kliento aplinkos kintamuosius per import.meta.env. Pagal nutylėjimą kliento kodui atskleidžiami tik tie pavadinimai, kurie prasideda VITE_. Oficialus Vite aplinkos kintamųjų ir režimų vadovas tai tiesiogiai dokumentuoja.

Tai veiks Vite kliente:

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

Tai paprastai bus undefined Vite naršyklės kode:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

nes jam trūksta numatytojo VITE_ atskleidimo prefikso.

Node/serverio kodas: nekopijuokite naršyklės prefiksų aklai

Serverio kodas paprastai skaito iš process.env. Jei raktui nereikia būti prieinamam naršyklėje, nepridėkite viešo prefikso tik tam, kad jis būtų matomas. Supabase konkrečiai įspėja, kad slapti raktai yra skirti tik backend.

Savikontrolė: patikrinkite tris dalykus kartu: aplinkos failas yra programos šaknyje, kintamojo pavadinimas naudoja teisingą karkaso prefiksą, o kodas naudoja teisingą karkaso prieigos būdą – process.env Next.js/Node arba import.meta.env Vite kliento kodui.

4 žingsnis: paleiskite kūrimo serverį iš naujo po aplinkos failų keitimo

Aplinkos kintamieji dažniausiai įkeliami, kai prasideda kūrimo procesas. Vite aiškiai dokumentuoja, kad .env failai įkeliami paleidimo metu ir kad po pakeitimų turėtumėte paleisti serverį iš naujo.

Sustabdykite dabartinį procesą ir paleiskite jį iš naujo:

# Next.js
npm run dev

# Vite
npm run dev

Jei klaida atsirado tik tada, kai sukūrėte aplinkos failą, kai serveris jau veikė, paleidimas iš naujo gali būti visas sprendimas.

Savikontrolė: pakartokite laikinus loginius patikrinimus. Jei reikšmės dabar įkeltos, pašalinkite nereikalingą derinimo išvestį ir tęskite įprastą Supabase veikimą.

Naudokite vykdymo metu veikiančią apsaugą vietoj problemos slėpimo su TypeScript

Naudinga gamybos aplinkos praktika yra sugriauti su aiškiu konfigūracijos pranešimu prieš kviečiant 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)

Tai yra geriau nei:

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

kai derinate, nes ne-null asercija gali paslėpti TypeScript įspėjimą nepakeisdama vykdymo metu gaunamos reikšmės.

Jei veikia lokaliai, bet nepavyksta po diegimo

Tai paprastai yra diegimo aplinkos problema, o ne Supabase projekto problema.

Local .env.local failai paprastai nėra įtraukiami į Git – ir neturėtų būti laikomi gamybos slaptažodžių perdavimo mechanizmu. Sukonfigūruokite tuos pačius kintamųjų pavadinimus savo hostingo teikėjo projekto nustatymuose.

Pavyzdžiui, Vercel dokumentuoja atskiras Production, Preview ir Development aplinkas. Taip pat nurodoma, kad aplinkos kintamųjų pakeitimai taikomi tik naujiems diegimams, todėl po jų pridėjimo ar keitimo turite perkrauti diegimą. Peržiūrėkite oficialų Vercel aplinkos kintamųjų valdymo vadovą.

Patikrinkite:

• Ar kintamasis apibrėžtas Production aplinkoje, o ne tik Preview?
• Ar pavadinimas tiksliai atitinka kodą?
• Ar buvo sukurtas naujas diegimas po kintamojo pridėjimo?
• Ar viešasis kintamasis egzistavo, kai buvo sukurtas kliento paketas?

Next.js viešieji kintamieji yra kūrimo metu nustatomos reikšmės

Next.js dokumentuoja, kad NEXT_PUBLIC_* kintamieji yra įterpiami į naršyklės JavaScript kūrimo metu. Po to, kai programa sukuriama, vykdymo aplinkos keitimas neperrašo tų reikšmių esamame kliento pakete. Jei sukuriate Docker atvaizdą be NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY ir vėliau jį įterpiate tik paleidus konteinerį, naršyklės kodas vis tiek gali turėti trūkstamą kūrimo metu nustatytą reikšmę.

Sprendimas: pateikite viešąsias Supabase reikšmes kūrimo metu, kuris sukuria kliento paketą, arba perprojektuokite programą, kad ji teiktų vykdymo metu konfigūraciją per serverio valdomą mechanizmą.

Vite taip pat pakeičia kliento aplinkos reikšmes kūrimo metu

Vite dokumentacija teigia, kad import.meta.env konstantos yra statiškai pakeičiamos supakuojant. Todėl, jei lokalus kūrimas veikia, bet gamybos paketas neveikia, įsitikinkite, kad VITE_SUPABASE_URL ir VITE_SUPABASE_PUBLISHABLE_KEY egzistavo kūrimo aplinkoje – o ne tik mašinoje, kuri vėliau aptarnauja statinius failus.

Monorepos: patikrinkite, kuris katalogas iš tikrųjų yra programos šaknis

Monorepo gali turėti:

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

Jei Next.js arba Vite komanda vykdoma su apps/web kaip programos šaknimi, aplinkos failas, padėtas tik repo/.env.local, gali būti ne tas failas, kurį karkasas įkelia. Vite envDir pagal nutylėjimą yra projekto šaknis, o Next.js tikisi savo .env* failų Next.js projekto šaknyje.

Sprendimas: nustatykite katalogą, kuriame yra programos package.json ir karkaso konfigūracija, tada padėkite aplinkos failą ten, kur to tikisi ta programa, arba aiškiai sukonfigūruokite aplinkos katalogą, jei karkasas tai palaiko.

Supabase Edge Functions naudoja kitus dabartinius numatytuosius kintamųjų pavadinimus

Jei klaida yra Supabase Edge Function viduje, nekopijuokite aklai Next.js ar Vite pavyzdžio.

Dabartinis Supabase Edge Functions aplinkos kintamųjų dokumentacija išvardija šiuos numatytuosius slaptažodžius, tarp kitų:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Atkreipkite dėmesį, kad SUPABASE_PUBLISHABLE_KEYS ir SUPABASE_SECRET_KEYS yra daugiskaitos formos. Supabase migracijos vadovas paaiškina, kad šie nauji kintamieji laiko JSON objektus, susietus su API rakto pavadinimu. Numatytajam slaptažodžiui:

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

Migracijos metu seni Edge Function kintamieji, tokie kaip SUPABASE_ANON_KEY ir SUPABASE_SERVICE_ROLE_KEY, gali egzistuoti šalia naujų raktų žodynų. Nelaikykite savaime suprantamu, kad kintamojo pavadinimas iš seno funkcijos vadovėlio atitinka naują raktų tipą, ką tik sukūrėte.

Nespręskite klaidos atskleisdami slaptažodį

Gundantis „sprendimas“ yra pridėti NEXT_PUBLIC_ arba VITE_ prie serverio slaptažodžio, kad naršyklė galėtų jį pagaliau perskaityti. Tai gali pašalinti trūkstamo kintamojo klaidą, bet sukurti saugumo problemą.

Dabartinis Supabase API raktų vadovas yra aiškus:

• Publishable raktas: skirtas viešiems komponentams, tokiems kaip naršyklės ir mobiliosios programos.
• Secret raktas: skirtas tik backend komponentams, kuriuos kontroliuojate; jis apeina eilučių lygio saugą.

Jei slaptažodis buvo atskleistas šaltinio kode, viešame pakete, ekrano kopijoje ar saugykloje, pašalinkite arba pakeiskite jį per Supabase API Keys nustatymus, o ne tik pervardykite aplinkos kintamąjį.

Dažni simptomai ir greičiausias patikrinimas

Galutinė savikontrolė: patikrinkite konfigūraciją teisinga tvarka

Prieš skelbdami, kad problema išspręsta, atlikite šį sąrašą:

1. Patvirtinkite, kad Supabase Project URL yra iš projekto, kurį iš tikrųjų ketinate naudoti.
2. Naršyklės/kliento kodui patvirtinkite, kad naudojate dabartinį publishable raktą arba vis dar aktyvų seną anon raktą – ne slaptažodį.
3. Patvirtinkite, kad kodas ir aplinkos failas naudoja tuos pačius kintamųjų pavadinimus.
4. Next.js kliento kodui naudokite NEXT_PUBLIC_* ir tiesiogines process.env.VARIABLE_NAME nuorodas.
5. Vite kliento kodui naudokite VITE_* ir import.meta.env.VARIABLE_NAME.
6. Laikykite .env.local programos šaknyje, o ne /src viduje.
7. Paleiskite kūrimo serverį iš naujo po aplinkos failų redagavimo.
8. Gamybai nustatykite reikšmes teisingoje diegimo aplinkoje ir perkurkite/perkraukite diegimą.
9. Neloginkite ir neatskleiskite sb_secret_... raktų.
10. Pašalinkite laikinus derinimo žurnalus, kai konfigūracija patvirtinta.

Kai createClient() inicijuojasi be trūkstamo rakto klaidos, aplinkos kintamųjų problema yra išspręsta. Jei kitas Supabase užklausos atsakymas grąžina autorizacijos, eilučių lygio saugos ar lentelės leidimo klaidą, traktuokite tai kaip atskirą problemą. Galiojantis API raktas negarantuoja, kad kvietėjas turi teisę skaityti ar keisti kiekvieną eilutę; Supabase sąmoningai atskiria API rakto identifikavimą nuo vartotojo autentifikacijos ir duomenų bazės autorizacijos.

Patvarus sprendimas nėra „pervardyti raktą, kol jis veiks“. Tai yra keturių dalykų suderinimas: dabartinio Supabase rakto tipo, aplinkos kintamojo pavadinimo, karkaso atskleidimo taisyklių ir aplinkos, kurioje programa iš tikrųjų sukurta arba vykdoma. Kai šie sutampa, Supabase klientas gauna tikrą raktą vietoj undefined, ir klaidinga konfigūracijos kilpa baigiasi.