Hvernig á að laga Supabase API-lykil sem finnst ekki í umhverfisbreytum

Síðast staðfest: 11. september 2026. Þú bætir Supabase URL og API-lykli við í .env skrá, endurræsir forritið og fær samt villu eins og “Supabase API key not found” eða Supabase eigin supabaseKey is required. Í flestum tilfellum er lykillinn til einhvers staðar, en kóðinn sem kallar á createClient() fær undefined eða tóman streng.

Það er einnig mikilvæg nafnbreyting árið 2026 sem liggur að baki mörgum ruglingslegum leiðbeiningum. Supabase er að fasa út eldri anon og service_role API-lykla fyrir árslok 2026 og mælir nú með publishable (útgáfu) lyklum fyrir opinbera/kóða á vafra og secret (leyndar) lyklum fyrir traustan þjónakóða. Eldri lyklar geta haldið áfram að virka meðan á yfirsöfnun stendur þar til þú óvirkjar þá, en nafnið á umhverfisbreytunni þinni og kóðinn þinn verða samt að passa nákvæmlega saman.

Núverandi Supabase skjölun notar gildi eins og sb_publishable_... og sb_secret_.... Sjá opinbera Supabase API-lykla leiðbeiningar og yfirsöfnunarleiðbeiningar fyrir publishable og secret lykla.

Hraðlagning: Passaðu að breytuheiti passi við rammaverkið og kóðann

Fyrir núverandi Next.js vafra viðtakanda notar opinber Supabase flýtistilling:

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

og:

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)

Fyrir núverandi Vite/React vafra viðtakanda notar opinber Supabase React flýtistilling:

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

og þú lest þau með:

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

Fyrir þjónakóða einungis sem þarf raunverulega aukinn aðgang, sýnir Supabase API-lykla leiðbeiningar mynstur eins og:

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

Settu aldrei sb_secret_... í breytu sem er viljandi sýnd í vafra kóða, eins og Vite VITE_* breytu eða Next.js NEXT_PUBLIC_* breytu. Supabase segir að leyndar lyklar fari framhjá Row Level Security (raðaröryggisreglum) og verði að vera í bakenda hlutum sem þú stjórnar.

Skref 1: Staðfestu að gildið vanti raunverulega í keyrslutíma

Byrjaðu ekki á að endurgera lykla eða endursetja pakka. Sannaðu fyrst hvað forritið þitt fær.

Núverandi @supabase/supabase-js viðtakandi athugar annað argumentið sem sent er til viðtakanda smiðsins og kastar supabaseKey is required. þegar gildið er falskt. Þú sérð þessa hegðun í opinberu supabase-js upprunakóða.

Bættu tímabundinni vörn fyrir 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')
}

Fyrir Vite, notaðu sömu hugmynd með import.meta.env.

Ekki prenta allan leyndar lykilinn. Fyrir villuleit er boolean eða væntur forskeyti nægilegt. Publishable lykill er hannaður fyrir opinbera hluti, en að skrá fullar auðkennisupplýsingar er samt óþarfi; leyndar lykill má aldrei birtast í vafra loggum.

Taktu einnig eftir að TypeScript setningafræði eins og process.env.MY_KEY! eða process.env.MY_KEY as string býr ekki til vantið gildi í keyrslutíma. Það breytir aðeins því hvað TypeScript heldur um tegundina. Ef umhverfisbreytan er ekki til, fær Supabase samt undefined.

Sjálfpróf: Ef boolean fyrir lykilinn er false, hættu að leita að Supabase heimildum, auðkenningu eða Row Level Security. Forritið hefur ekki hlaðið upp stillingunum ennþá.

Skref 2: Notaðu núverandi lyklagerð—og gerðu gömul og ný heiti samræmd

Opnaðu Connect gluggann í Supabase verkefninu þínu, eða farðu í Settings → API Keys. Núverandi Supabase skjölun nefnir skýrt Settings → API Keys sem staðinn til að skoða alla verkefnis API-lykla.

Fyrir kóða sem fer til vafra notanda, farsímaforrits, skjáborðsforrits eða annars opinbers hluta, notaðu publishable lykil. Supabase segir að publishable lykill sé öruggur að birta því aðgangur að gagnagrunni er enn stjórnað af heimildum og Row Level Security. Fyrir bakenda hluti sem þú stjórnar að fullu, veitir leyndar lykill aukinn aðgang og fer framhjá Row Level Security.

Yfirsöfnun frá eldri lyklum er algeng ástæða fyrir “not found” villu því eftirfarandi samsetningar eru ekki jafngildar sem umhverfisbreytuheiti:

Eldri breyta eins og NEXT_PUBLIC_SUPABASE_ANON_KEY er ekki sjálfkrafa ógild. Ef verkefnið þitt hefur enn virkan eldri anon lykil og kóðinn þinn les nákvæmlega þá breytu, getur hún haldið áfram að virka meðan á yfirsöfnunartímabil Supabase stendur. Vandamálið er að afrita nýjan publishable lykil í eitt breytuheiti á meðan kóðinn les ennþá annað.

Sjálfpróf: Leitaðu í verkefninu þínu að SUPABASE_. Berðu saman hvert breytuheiti í kóðanum við nákvæm heiti í umhverfisskránum þínum og útfærslustillingum. Ekki treysta á minnið.

Skref 3: Settu .env skrána þar sem rammaverkið þitt hleður hana raunverulega

Réttur lykill í rangri staðsetningu skráar er í raun vantar lykill.

Next.js: Haltu .env skrám í rót verkefnisins

Next.js hefur innbyggða stuðning fyrir .env* skrár. Núverandi umhverfisbreytuleiðbeiningar þess segja að ef þú notar /src möppu, tilheyra umhverfisskrárnar ennþá rót verkefnisins, ekki inni í /src. Sjá opinberar Next.js umhverfisbreytuleiðbeiningar.

Dæmigerð uppsetning er:

my-app/
  .env.local
  package.json
  next.config.js
  app/
  src/        # ef notað

Fyrir kóða á vafrahlið, Next.js birtir aðeins breytur sem nota NEXT_PUBLIC_ forskeytið. Þau gildi eru innfelld í vafra bundle við byggingartíma.

Vite: Notaðu VITE_ og import.meta.env

Vite birtir viðtakanda umhverfisbreytur í gegnum import.meta.env. Sjálfgefið eru aðeins heiti með VITE_ forskeyti sýnd í viðtakanda kóða. Opinbera Vite Env Variables and Modes leiðbeiningar skjalfesta þetta beint.

Þetta virkar í Vite viðtakanda:

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

Þetta verður venjulega undefined í Vite vafra kóða:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

vegna þess að það vantar sjálfgefna VITE_ birtuforskeytið.

Node/þjónakóði: Ekki afrita vafra forskeyti blindlega

Þjónakóði les venjulega úr process.env. Ef lykill þarf ekki að vera tiltækur í vafra, ekki bæta við opinberu forskeyti bara til að gera hann sýnilegan. Supabase varar sérstaklega við að leyndar lyklar séu einungis fyrir bakenda.

Sjálfpróf: Staðfestu þrjú hluti saman: env skráin er í rót forritsins, breytuheitið notar rétt rammaverk forskeyti, og kóðinn notar réttan aðgangsaðila rammaverksins—process.env fyrir Next.js/Node eða import.meta.env fyrir Vite viðtakanda kóða.

Skref 4: Endurræstu þróunarþjóninn eftir breytingar á umhverfisskrám

Umhverfisbreytur eru oftast hlaðnar þegar þróunarferlið hefst. Vite skjalfestir sérstaklega að .env skrár séu hlaðnar við ræsingu og að þú ættir að endurræsa þjóninn eftir breytingar.

Stöðvaðu núverandi ferli og ræstu það aftur:

# Next.js
npm run dev

# Vite
npm run dev

Ef villan kom fram aðeins eftir að þú bjóst til umhverfisskrána á meðan þjónninn var nú þegar keyrandi, gæti endurræsing verið alltaf lausnin.

Sjálfpróf: Keyrðu tímabundnu boolean prófin aftur. Ef gildin eru nú hlaðin, fjarlægðu óþarfa villuleitarúttak og haltu áfram í eðlilega Supabase aðgerð.

Notaðu keyrslutíma vörn í stað þess að fela vandamálið með TypeScript

Nytlegt framleiðslumynstur er að mistakast með skýra stillingaskilaboð áður en Supabase er kallað:

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)

Þetta er betra en:

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

þegar þú ert að leita að villum, vegna þess að non-null fullyrðingin getur falið TypeScript viðvörunina án þess að breyta keyrslutímagildinu.

Ef það virkar staðbundið en mistekst eftir útfærslu

Þetta er yfirleitt vandamál í útfærsluumhverfinu, ekki í Supabase verkefninu.

Staðbundnar .env.local skrár eru venjulega ekki settar í Git—og ættu ekki að vera treated sem framleiðslu leyndarafhendingarkerfi. Stilltu sömu breytuheiti í stillingum hýsingarveitunnar þinnar.

Til dæmis, Vercel skjalfestir aðskildar Production, Preview og Development umhverfi. Það segir einnig að breytingar á umhverfisbreytum gildi aðeins fyrir nýjar útfærslur, svo þú verður að endurútfæra eftir að þú bætir við eða breytir þeim. Sjá opinberar Vercel umhverfisbreytustjórnunarleiðbeiningar.

Athugaðu:

• Er breytan skilgreind fyrir Production, ekki bara Preview?
• Passar heitið nákvæmlega við kóðann?
• Var ný útfærsla búin til eftir að breytan var bætt við?
• Var opinbera breytan til staðar þegar viðtakanda bundle var byggt?

Next.js opinberar breytur eru byggingartímagildi

Next.js skjalfestir að NEXT_PUBLIC_* breytur séu innfelldar í vafra JavaScript við byggingartíma. Eftir að appið er byggt, að breyta keyrsluumhverfinu endurskrifar ekki þau gildi í núverandi viðtakanda bundle. Ef þú byggir Docker mynd án NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY og sprautar því síðar inn aðeins þegar ílátinu er ræst, getur vafra kóðinn enn innihaldið vantið byggingartímagildið.

Lagning: Veittu opinber Supabase gildi við bygginguna sem framleiðir viðtakanda bundle, eða endurhannaðu forritið til að veita keyrslutíma stillingar í gegnum þjónastýrt kerfi.

Vite skiptir einnig út viðtakanda env gildum við byggingu

Skjölun Vite segir að import.meta.env fastar séu staðbundið skiptir út við bundling. Þess vegna, ef staðbundin þróun virkar en framleiðslu bundle virkar ekki, staðfestu að VITE_SUPABASE_URL og VITE_SUPABASE_PUBLISHABLE_KEY hafi verið til staðar í byggingarumhverfinu—ekki bara á vélinni sem síðar þjónar statískum skrám.

Monorepos: Athugaðu hvaða mappa er raunverulega app rótin

Monorepo getur innihaldið:

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

Ef Next.js eða Vite skipunin keyrir með apps/web sem forritsrót, getur umhverfisskrá sett aðeins í repo/.env.local ekki verið skráin sem rammaverkið hleður. Vite envDir er sjálfgefið rót verkefnisins, og Next.js búist við .env* skrám sínum í rót Next.js verkefnisins.

Lagning: Auðkennaðu möppuna sem inniheldur package.json forritsins og rammaverk stillingar, settu síðan env skrána þar sem appið búist við henni eða stilltu umhverfismöppuna skýrt þegar rammaverkið styður það.

Supabase Edge Functions nota önnur núverandi sjálfgefin breytuheiti

Ef villan er inni í Supabase Edge Function, ekki afrita blindlega Next.js eða Vite dæmi.

Núverandi Supabase Edge Functions umhverfisbreytuskjölun listar þessa sjálfgefna leyndar, meðal annars:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Taktu eftir að SUPABASE_PUBLISHABLE_KEYS og SUPABASE_SECRET_KEYS eru í fleirtölu. Yfirsöfnunarleiðbeiningar Supabase útskýra að þessar nýju breytur innihalda JSON hluti lyklaðir eftir API-lykla heiti. Fyrir sjálfgefinn leyndar lykil:

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

Meðan á yfirsöfnun stendur, geta eldri Edge Function breytur eins og SUPABASE_ANON_KEY og SUPABASE_SERVICE_ROLE_KEY verið til staðar við hliðina á nýju lyklaborðunum. Ekki gera ráð fyrir að breytuheitið úr gamalli function leiðbeiningum passi við nýju lyklagerðina sem þú bjóst nýlega til.

Ekki leysa villuna með því að birta leyndar lykil

Freistandi “lagning” er að bæta NEXT_PUBLIC_ eða VITE_ við þjónaleyndar svo vafrið geti loksins lesið hann. Það getur eytt vantar breytu villunni en búið til öryggisvandamál.

Núverandi Supabase API-lykla leiðbeiningar eru skýrar:

• Publishable lykill: ætlaður fyrir opinbera hluti eins og vafra og farsímaforrit.
• Leyndar lykill: ætlaður einungis fyrir bakenda hluti sem þú stjórnar; hann fer framhjá Row Level Security.

Ef leyndar lykill hefur verið birtur í upprunakóða, opinberum bundle, skjámynd eða repository, fjarlægðu eða snúðu honum í gegnum Supabase API Keys stillingar í stað þess að aðeins endurnefna umhverfisbreytuna.

Algeng einkenni og hraðasta athugunin

Loka sjálfpróf: Staðfestu stillingarnar í réttri röð

Áður en þú lýsir málinu leystu, keyrðu þessa athugunarlista:

1. Staðfestu að Supabase Project URL komi frá verkefninu sem þú ætlar raunverulega að nota.
2. Fyrir vafra/viðtakanda kóða, staðfestu að þú sért að nota núverandi publishable lykil eða enn virkan eldri anon lykil—ekki leyndar lykil.
3. Staðfestu að kóðinn og umhverfisskráin noti sömu breytuheiti.
4. Fyrir Next.js viðtakanda kóða, notaðu NEXT_PUBLIC_* og beinar process.env.VARIABLE_NAME tilvísanir.
5. Fyrir Vite viðtakanda kóða, notaðu VITE_* og import.meta.env.VARIABLE_NAME.
6. Haltu .env.local í rót forritsins frekar en inni í /src.
7. Endurræstu þróunarþjóninn eftir að hafa breytt umhverfisskrám.
8. Fyrir framleiðslu, stilltu gildin í rétta útfærsluumhverfið og endurbyggðu/endurútfærðu.
9. Ekki skrá eða birta sb_secret_... lykla.
10. Fjarlægðu tímabundna villuleitar logga þegar stillingarnar eru staðfestar.

Þegar createClient() frumstillist án vantar lykil villu, er umhverfisbreytu vandamálið leyst. Ef næsta Supabase beiðni skilar auðkenningar, Row Level Security, eða töfluheimildavillu, meðhöndlaðu það sem sérstakt mál. Gildur API-lykill tryggir ekki að kallandinn megi lesa eða breyta hverri röð; Supabase aðskilur meðvitað API-lykla auðkenningu frá notandaauðkenningu og gagnagrunnsheimildum.

Varanlega lagningin er ekki “endurnefna lykilinn þar til hann virkar.” Hún er að samræma fjóra hluti: núverandi Supabase lyklagerð, umhverfisbreytuheitið, birtureglur rammaverksins, og umhverfið þar sem appið er raunverulega byggt eða keyrt. Þegar þessir hlutir passa saman, fær Supabase viðtakandinn raunverulegan lykil í stað undefined, og villandi stillingaloopinn endar.