Kā novērst Supabase API atslēgas neatradīšanu vides mainīgajos

Pēdējoreiz pārbaudīts: 2026. gada 11. septembrī. Jūs pievienojat savu Supabase URL un API atslēgu .env failam, restartējat lietotni, bet joprojām saņemat kļūdu, piemēram, “Supabase API key not found” vai Supabase pašu kļūdu supabaseKey is required. Vairumā gadījumu atslēga kaut kur eksistē, bet kods, kas izsauc createClient(), saņem undefined vai tukšu virkni.

Aiz daudziem mulsinošiem apmācību materiāliem slēpjas arī svarīga 2026. gada nosaukumu maiņa. Supabase līdz 2026. gada beigām atsakās no vecajām anon un service_role API atslēgām un tagad iesaka izmantot publicējamas (publishable) atslēgas publiskam/klienta kodam un secret atslēgas uzticamam servera kodam. Esošās vecās atslēgas var turpināt darboties migrācijas laikā, līdz tās tiek atspējotas, taču jūsu vides mainīgā nosaukumam un kodam joprojām ir precīzi jāsakrīt.

Pašreizējā Supabase dokumentācija izmanto vērtības, piemēram, sb_publishable_... un sb_secret_.... Skatiet oficiālo Supabase API atslēgu rokasgrāmatu un migrācijas rokasgrāmatu par publicējamām un secret atslēgām.

Ātrs risinājums: padariet mainīgo nosaukumus saderīgus ar ietvaru un kodu

Pašreizējam Next.js pārlūka klientam Supabase oficiālajā ātrajā sākumā tiek izmantots:

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

un:

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)

Pašreizējam Vite/React pārlūka klientam Supabase oficiālajā React ātrajā sākumā tiek izmantots:

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

un jūs tos nolasāt ar:

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

Tikai servera kodam, kam patiešām ir nepieciešama paaugstināta piekļuve, Supabase API atslēgu rokasgrāmata parāda tādu modeli kā:

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

Nekad nelieciet sb_secret_... mainīgajā, kas ir apzināti pakļauts pārlūka kodam, piemēram, Vite VITE_* mainīgajā vai Next.js NEXT_PUBLIC_* mainīgajā. Supabase norāda, ka secret atslēgas apiet Rindas līmeņa drošību (Row Level Security) un tām ir jāpaliek izstrādātāja kontrolētos aizmugurējās sistēmas komponentos.

1. solis: pārliecinieties, ka vērtība patiešām trūkst izpildes laikā

Nesāciet ar atslēgu reģenerēšanu vai pakotņu pārinstalēšanu. Vispirms pierādiet, ko jūsu lietotne saņem.

Pašreizējais @supabase/supabase-js klients pārbauda otro argumentu, kas nodots tā klienta konstruktoram, un izmet supabaseKey is required., ja šī vērtība ir falsy. Šo uzvedību var redzēt oficiālajā supabase-js avota kodā.

Pievienojiet pagaidu aizsardzību pirms 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')
}

Vite izmantojiet to pašu ideju ar import.meta.env.

Nedrīkst izdrukāt visu secret atslēgu. Atkļūdošanai pietiek ar boolean vērtību vai paredzēto prefiksu. Publicējamā atslēga ir paredzēta publiskiem komponentiem, taču pilnīgu akreditācijas datu reģistrēšana joprojām ir nevajadzīga; secret atslēga nekad nedrīkst tikt atklāta klienta žurnālos.

Ņemiet vērā arī to, ka TypeScript sintakse, piemēram, process.env.MY_KEY! vai process.env.MY_KEY as string, neizveido trūkstošu vērtību izpildes laikā. Tā maina tikai to, ko TypeScript uzskata par tipu. Ja vides mainīgais nav pieejams, Supabase joprojām saņem undefined.

Pašpārbaude: ja atslēgas boolean vērtība ir false, pārtrauciet Supabase atļauju, autentifikācijas vai Rindas līmeņa drošības atkļūdošanu. Lietotne vēl nav ielādējusi konfigurāciju.

2. solis: izmantojiet pašreizējo atslēgas tipu un nodrošiniet veco un jauno nosaukumu saderību

Atveriet sava Supabase projekta Connect dialogu vai dodieties uz Settings → API Keys. Supabase pašreizējā dokumentācija skaidri norāda Settings → API Keys kā vietu, kur skatīt visas projekta API atslēgas.

Kodam, kas tiek piegādāts lietotāja pārlūkā, mobilajā lietotnē, darbvirsmas lietotnē vai citā publiskā komponentā, izmantojiet publicējamu atslēgu. Supabase norāda, ka publicējamo atslēgu ir droši atklāt, jo datubāzes piekļuve joprojām tiek kontrolēta ar grants un Rindas līmeņa drošību. Aizmugurējās sistēmas komponentiem, kurus jūs pilnībā kontrolējat, secret atslēga nodrošina paaugstinātu piekļuvi un apiet Rindas līmeņa drošību.

Migrācija no vecajām atslēgām ir bieža “neatrasts” kļūdu cēlonis, jo šādas kombinācijas nav ekvivalentas kā vides mainīgo nosaukumi:

Vecāks mainīgais, piemēram, NEXT_PUBLIC_SUPABASE_ANON_KEY, nav automātiski nederīgs. Ja jūsu projektā joprojām ir aktīva vecā anon atslēga un jūsu kods nolasa tieši šo mainīgo, tas var turpināt darboties Supabase migrācijas periodā. Problēma ir jaunas publicējamas atslēgas kopēšana vienā mainīgā nosaukumā, kamēr kods joprojām nolasa citu.

Pašpārbaude: meklējiet projektā SUPABASE_. Salīdziniet katru mainīgā nosaukumu kodā ar precīziem nosaukumiem jūsu vides failos un izvietošanas iestatījumos. Neuzticieties atmiņai.

3. solis: novietojiet .env failu tur, kur jūsu ietvars to patiešām ielādē

Pareiza atslēga nepareizā faila atrašanās vietā ir efektīvi trūkstoša atslēga.

Next.js: turiet .env failus projekta saknē

Next.js ir iebūvēts atbalsts .env* failiem. Tā pašreizējā vides mainīgo rokasgrāmata nosaka, ka, ja izmantojat /src direktoriju, vides faili joprojām pieder projekta saknē, nevis /src iekšienē. Skatiet oficiālo Next.js vides mainīgo rokasgrāmatu.

Tipisks izkārtojums ir:

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

Pārlūka puses kodam Next.js pakļauj tikai mainīgos, kas izmanto NEXT_PUBLIC_ prefiksu. Šīs vērtības tiek iekļautas pārlūka bundlī būvēšanas laikā.

Vite: izmantojiet VITE_ un import.meta.env

Vite pakļauj klienta vides mainīgos caur import.meta.env. Pēc noklusējuma klienta kodam tiek pakļauti tikai nosaukumi ar VITE_ prefiksu. Oficiālā Vite Env Variables and Modes rokasgrāmata to dokumentē tieši.

Tas darbosies Vite klientā:

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

Tas parasti būs undefined Vite pārlūka kodā:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

jo tam trūkst noklusējuma VITE_ pakļaušanas prefiksa.

Node/servera kods: nekopējiet pārlūka prefiksus aklām

Servera kods parasti nolasa no process.env. Ja atslēgai nav jābūt pieejamai pārlūkā, nepievienojiet publisko prefiksu tikai tāpēc, lai to padarītu redzamu. Supabase īpaši brīdina, ka secret atslēgas ir tikai aizmugurējās sistēmas.

Pašpārbaude: pārbaudiet trīs lietas kopā: vides fails atrodas lietotnes saknē, mainīgā nosaukums izmanto pareizo ietvara prefiksu un kods izmanto ietvara pareizo piekļuves veidu — process.env Next.js/Node vai import.meta.env Vite klienta kodam.

4. solis: restartējiet izstrādes serveri pēc vides failu maiņas

Vides mainīgie parasti tiek ielādēti, sākoties izstrādes procesam. Vite skaidri dokumentē, ka .env faili tiek ielādēti starta laikā un ka pēc izmaiņām serveris ir jārestartē.

Apturiet pašreizējo procesu un sāciet to no jauna:

# Next.js
npm run dev

# Vite
npm run dev

Ja kļūda parādījās tikai pēc tam, kad izveidojāt vides failu, kamēr serveris jau darbojās, restartēšana var būt viss risinājums.

Pašpārbaude: atkārtoti palaidiet pagaidu boolean pārbaudes. Ja vērtības tagad ir ielādētas, noņemiet nevajadzīgo atkļūdošanas izvadi un turpiniet ar parasto Supabase darbību.

Izmantojiet izpildes laika aizsardzību, nevis slēpiet problēmu ar TypeScript

Noderīgs ražošanas modelis ir kļūdas izraisīšana ar skaidru konfigurācijas ziņojumu pirms Supabase izsaukšanas:

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)

Tas ir labāk nekā:

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

atkļūdošanas laikā, jo nenulles apgalvojums var paslēpt TypeScript brīdinājumu, nemainot izpildes laika vērtību.

Ja tas darbojas lokāli, bet neizdodas pēc izvietošanas

Tas parasti ir izvietošanas vides problēma, nevis Supabase projekta problēma.

Lokālie .env.local faili parasti netiek iesniegti Git — un tie nevajadzētu uzskatīt par ražošanas slepeno datu piegādes mehānismu. Konfigurējiet tos pašus mainīgo nosaukumus savā hostinga sniedzēja projekta iestatījumos.

Piemēram, Vercel dokumentē atsevišķas Production, Preview un Development vides. Tas arī norāda, ka izmaiņas vides mainīgajos attiecas tikai uz jauniem izvietošanas gadījumiem, tāpēc pēc to pievienošanas vai maiņas ir jāveic atkārtota izvietošana. Skatiet Vercel oficiālo vides mainīgo pārvaldības rokasgrāmatu.

Pārbaudiet:

• Vai mainīgais ir definēts Production, nevis tikai Preview?
• Vai nosaukums precīzi sakrīt ar kodu?
• Vai pēc mainīgā pievienošanas tika izveidots jauns izvietošanas gadījums?
• Vai publiskais mainīgais bija pieejams, kad tika būvēts klienta bundlis?

Next.js publiskie mainīgie ir būvēšanas laika vērtības

Next.js dokumentē, ka NEXT_PUBLIC_* mainīgie tiek iekļauti pārlūka JavaScript būvēšanas laikā. Pēc lietotnes būvēšanas izpildes vides maiņa nepārraksta šīs vērtības esošajā klienta bundlī. Ja jūs būvējat Docker attēlu bez NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY un vēlāk to ievadāt tikai konteinera starta laikā, pārlūka kods joprojām var saturēt trūkstošo būvēšanas laika vērtību.

Risinājums: nodrošiniet publiskās Supabase vērtības būvēšanas laikā, kas rada klienta bundli, vai pārdizainējiet lietotni, lai nodrošinātu izpildes laika konfigurāciju caur servera kontrolētu mehānismu.

Vite arī aizstāj klienta env vērtības būvēšanas laikā

Vite dokumentācija nosaka, ka import.meta.env konstantes tiek statiski aizstātas bundlēšanas laikā. Tāpēc, ja lokālā izstrāde darbojas, bet ražošanas bundlis nē, pārliecinieties, ka VITE_SUPABASE_URL un VITE_SUPABASE_PUBLISHABLE_KEY eksistēja būvēšanas vidē — nevis tikai mašīnā, kas vēlāk apkalpo statiskos failus.

Monorepo: pārbaudiet, kura direktorija patiešām ir lietotnes sakne

Monorepo var saturēt:

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

Ja Next.js vai Vite komanda tiek palaista ar apps/web kā lietotnes sakni, vides fails, kas novietots tikai repo/.env.local, var nebūt tas fails, ko ietvars ielādē. Vite envDir noklusējums ir projekta sakne, un Next.js sagaida savus .env* failus Next.js projekta saknē.

Risinājums: identificējiet direktoriju, kas satur lietotnes package.json un ietvara konfigurāciju, pēc tam novietojiet env failu tur, kur šī lietotne to sagaida, vai eksplicīti konfigurējiet vides direktoriju, ja ietvars to atbalsta.

Supabase Edge Functions izmanto atšķirīgus pašreizējos noklusējuma mainīgo nosaukumus

Ja kļūda ir Supabase Edge Function iekšienē, nekopējiet aklām Next.js vai Vite piemēru.

Supabase pašreizējā Edge Functions vides mainīgo dokumentācija starp citiem uzskaita šos noklusējuma slepenos datus:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Ievērojiet, ka SUPABASE_PUBLISHABLE_KEYS un SUPABASE_SECRET_KEYS ir daudzskaitlī. Supabase migrācijas rokasgrāmata skaidro, ka šie jaunie mainīgie satur JSON objektus, kas indeksēti pēc API atslēgas nosaukuma. Noklusējuma secret atslēgai:

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

Migrācijas laikā vecās Edge Function mainīgie, piemēram, SUPABASE_ANON_KEY un SUPABASE_SERVICE_ROLE_KEY, var eksistēt līdzās jaunajām atslēgu vārdnīcām. Nepieņemiet, ka mainīgā nosaukums no veca funkcijas apmācību materiāla sakrīt ar tikko izveidoto jauno atslēgas tipu.

Nenovērsiet kļūdu, atklājot secret atslēgu

Pievilinošs “risinājums” ir pievienot NEXT_PUBLIC_ vai VITE_ servera slepenajam datam, lai pārlūks to beidzot varētu nolasīt. Tas var novērst trūkstoša mainīgā kļūdu, radot drošības problēmu.

Supabase pašreizējā API atslēgu rokasgrāmata ir skaidra:

• Publicējamā atslēga: paredzēta publiskiem komponentiem, piemēram, pārlūka un mobilajām lietotnēm.
• Secret atslēga: paredzēta tikai aizmugurējās sistēmas komponentiem, kurus jūs kontrolējat; tā apiet Rindas līmeņa drošību.

Ja secret atslēga ir bijusi atklāta avota kodā, publiskā bundlī, ekrānuzņēmumā vai repozitorijā, noņemiet vai rotējiet to caur Supabase API Keys iestatījumiem, nevis tikai pārdēvējiet vides mainīgo.

Bieži simptomi un ātrākā pārbaude

Galīgā pašpārbaude: pārbaudiet konfigurāciju pareizā secībā

Pirms pasludināt problēmu atrisinātu, izpildiet šo kontrolsarakstu:

1. Pārliecinieties, ka Supabase Project URL nāk no projekta, kuru jūs patiešām domājat izmantot.
2. Pārlūka/klienta kodam pārliecinieties, ka izmantojat pašreizējo publicējamo atslēgu vai joprojām aktīvo veco anon atslēgu — nevis secret atslēgu.
3. Pārliecinieties, ka kods un vides fails izmanto tos pašus mainīgo nosaukumus.
4. Next.js klienta kodam izmantojiet NEXT_PUBLIC_* un tiešas process.env.VARIABLE_NAME atsauces.
5. Vite klienta kodam izmantojiet VITE_* un import.meta.env.VARIABLE_NAME.
6. Turiet .env.local lietotnes saknē, nevis /src iekšienē.
7. Restartējiet izstrādes serveri pēc vides failu rediģēšanas.
8. Ražošanai iestatiet vērtības pareizajā izvietošanas vidē un pārbūvējiet/pārvietojiet.
9. Nereģistrējiet un neatklājiet sb_secret_... atslēgas.
10. Noņemiet pagaidu atkļūdošanas žurnālus, tiklīdz konfigurācija ir apstiprināta.

Kad createClient() inicializējas bez trūkstošas atslēgas kļūdas, vides mainīgā problēma ir atrisināta. Ja nākamais Supabase pieprasījums atgriež autorizācijas, Rindas līmeņa drošības vai tabulas atļauju kļūdu, uzskatiet to par atsevišķu problēmu. Derīga API atslēga negarantē, ka izsaucējam ir atļauts lasīt vai modificēt katru rindu; Supabase apzināti atdala API atslēgas identifikāciju no lietotāja autentifikācijas un datubāzes autorizācijas.

Ilgtspējīgs risinājums nav “pārdēvēt atslēgu, līdz tā strādā”. Tas ir četru lietu saskaņošana: pašreizējais Supabase atslēgas tips, vides mainīgā nosaukums, ietvara pakļaušanas noteikumi un vide, kurā lietotne patiešām tiek būvēta vai izpildīta. Kad šie sakrīt, Supabase klients saņem īstu atslēgu, nevis undefined, un mulsinošais konfigurācijas cikls beidzas.