Как да поправите грешката „Supabase API Key Not Found“ в променливите на средата

Последна проверка: 11 септември 2026 г. Добавяте вашия Supabase URL и API ключ във файл .env, рестартирате приложението и все още получавате грешка като “Supabase API key not found” или собствената грешка на Supabase supabaseKey is required. В повечето случаи ключът съществува някъде, но кодът, който извиква createClient(), получава undefined или празен низ.

Има и важна промяна в имената от 2026 г., която стои зад много объркващи ръководства. Supabase премахва поддръжката на наследените anon и service_role API ключове до края на 2026 г. и вече препоръчва publishable ключове за публичен/клиентски код и secret ключове за доверен сървърен код. Съществуващите наследени ключове могат да продължат да работят по време на миграцията, докато не ги деактивирате, но името на променливата на средата и вашият код все още трябва да съвпадат точно.

Текущата документация на Supabase използва стойности като sb_publishable_... и sb_secret_.... Вижте официалното ръководство за API ключове на Supabase и ръководството за миграция към publishable и secret ключове.

Бързо поправяне: направете имената на променливите да съвпадат с фреймуърка и кода

За текущ Next.js браузър клиент, официалното бързо начало на Supabase използва:

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

и:

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)

За текущ Vite/React браузър клиент, официалното React бързо начало на Supabase използва:

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

и ги четете с:

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

За код само за сървър, който наистина се нуждае от повишен достъп, ръководството за API ключове на Supabase показва модел като:

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

Никога не слагайте sb_secret_... в променлива, която е намерено изложена на браузър код, като Vite VITE_* променлива или Next.js NEXT_PUBLIC_* променлива. Supabase казва, че secret ключовете заобикалят Row Level Security и трябва да останат в backend компоненти, контролирани от разработчика.

Стъпка 1: потвърдете, че стойността наистина липсва по време на изпълнение

Не започвайте с регенериране на ключове или преинсталиране на пакети. Първо докажете какво получава вашето приложение.

Текущият @supabase/supabase-js клиент проверява втория аргумент, предаден на конструктора на клиента, и хвърля supabaseKey is required., когато тази стойност е false. Можете да видите това поведение в официалния изходен код на supabase-js.

Добавете временна защита преди 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 използвайте същата идея с import.meta.env.

Не принтирайте целия secret ключ. За дебъгване, булева стойност или очакван префикс са достатъчни. Publishable ключът е предназначен за публични компоненти, но логването на пълни удостоверения все още е ненужно; secret ключът никога не трябва да се излага в клиентски логове.

Също така обърнете внимание, че TypeScript синтаксис като process.env.MY_KEY! или process.env.MY_KEY as string не създава липсваща стойност по време на изпълнение. Той само променя това, което TypeScript вярва за типа. Ако променливата на средата отсъства, Supabase все още получава undefined.

Самопроверка: ако булевата стойност за ключа е false, спрете дебъгването на Supabase разрешения, автентикация или Row Level Security. Приложението все още не е заредило конфигурацията.

Стъпка 2: използвайте текущия тип ключ—и направете старите и новите имена последователни

Отворете диалога Connect на вашия Supabase проект или отидете на Settings → API Keys. Текущата документация на Supabase изрично посочва Settings → API Keys като мястото за преглед на всички API ключове на проекта.

За код, който се доставя на браузъра на потребителя, мобилно приложение, десктоп приложение или друг публичен компонент, използвайте publishable ключ. Supabase казва, че publishable ключът е безопасен за излагане, защото достъпът до базата данни все още се контролира от grants и Row Level Security. За backend компоненти, които контролирате напълно, secret ключът осигурява повишен достъп и заобикаля Row Level Security.

Миграцията от наследени ключове е честа причина за грешка „not found“, защото следващите комбинации не са еквивалентни като имена на променливи на средата:

Стара променлива като NEXT_PUBLIC_SUPABASE_ANON_KEY не е автоматично невалидна. Ако вашият проект все още има активен наследен anon ключ и кодът ви чете точно тази променлива, тя може да продължи да работи по време на периода на миграция на Supabase. Проблемът е копирането на нов publishable ключ в едно име на променлива, докато кодът все още чете друга.

Самопроверка: потърсете във вашия проект SUPABASE_. Сравнете всяко име на променлива в кода с точните имена във вашите env файлове и настройки за деплоймент. Не разчитайте на паметта.

Стъпка 3: поставете .env файла там, където фреймуъркът всъщност го зарежда

Правилен ключ на грешно местоположение на файла е ефективно липсващ ключ.

Next.js: дръжте .env файловете в корена на проекта

Next.js има вградена поддръжка за .env* файлове. Текущото му ръководство за променливи на средата казва, че ако използвате /src директория, env файловете все още принадлежат в корена на проекта, а не вътре в /src. Вижте официалното ръководство за променливи на средата на Next.js.

Типичен layout е:

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

За код от страна на браузъра, Next.js излага само променливи, които използват префикса NEXT_PUBLIC_. Тези стойности се вграждат в браузърния bundle по време на build.

Vite: използвайте VITE_ и import.meta.env

Vite излага клиентски променливи на средата чрез import.meta.env. По подразбиране само имената с префикс VITE_ се излагат на клиентския код. Официалното ръководство за Env променливи и режими на Vite документира това директно.

Това ще работи във 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

Това обикновено ще бъде undefined във Vite браузър код:

const key = import.meta.env.SUPABASE_PUBLISHABLE_KEY

защото му липсва префиксът за излагане по подразбиране VITE_.

Node/сървърен код: не копирайте браузърни префикси сляпо

Сървърният код обикновено чете от process.env. Ако ключът не трябва да е наличен в браузъра, не добавяйте публичен префикс само за да го направите видим. Supabase специфично предупреждава, че secret ключовете са само за backend.

Самопроверка: проверете три неща заедно: env файлът е в корена на приложението, името на променливата използва правилния префикс на фреймуърка и кодът използва правилния достъп на фреймуърка—process.env за Next.js/Node или import.meta.env за Vite клиентски код.

Стъпка 4: рестартирайте сървъра за разработка след промяна на env файловете

Променливите на средата обикновено се зареждат, когато процесът за разработка стартира. Vite изрично документира, че .env файловете се зареждат при стартиране и че трябва да рестартирате сървъра след промени.

Спрете текущия процес и го стартирайте отново:

# Next.js
npm run dev

# Vite
npm run dev

Ако грешката се появи само след като сте създали env файла, докато сървърът вече е работил, рестартът може да е цялото поправяне.

Самопроверка: пуснете отново временните булеви проверки. Ако стойностите сега са заредени, премахнете ненужния дебъг изход и продължете към нормална Supabase операция.

Използвайте runtime защита вместо да скриете проблема с TypeScript

Полезен production модел е да се провалите с ясно съобщение за конфигурация преди извикването на 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)

Това е по-добро от:

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

когато дебъгвате, защото non-null assertion може да скрие TypeScript предупреждението, без да променя стойността по време на изпълнение.

Ако работи локално, но се проваля след деплоймент

Това обикновено е проблем с средата за деплоймент, а не с Supabase проекта.

Локалните .env.local файлове обикновено не се комитват в Git—и не трябва да се третират като механизъм за доставка на production тайни. Конфигурирайте същите имена на променливи в настройките на проекта на вашия хостинг доставчик.

Например, Vercel документира отделни Production, Preview и Development среди. Също така посочва, че промените в променливите на средата се прилагат само към нови деплойменти, така че трябва да предеплойнете след добавяне или промяна на тях. Вижте официалното ръководство на Vercel за управление на променливи на средата.

Проверете:

• Дефинирана ли е променливата за Production, а не само за Preview?
• Съвпада ли името точно с кода?
• Създаден ли е нов деплоймент след добавянето на променливата?
• Налична ли е публичната променлива, когато клиентският bundle е бил построен?

Next.js публичните променливи са стойности по време на build

Next.js документира, че NEXT_PUBLIC_* променливите се вграждат в браузърния JavaScript по време на build. След като приложението е построено, промяната на средата за изпълнение не презаписва тези стойности в съществуващия клиентски bundle. Ако построите Docker образ без NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY и по-късно го инжектирате само когато контейнерът стартира, браузърният код все още може да съдържа липсващата стойност от build-а.

Поправяне: предоставете публичните Supabase стойности по време на build-а, който произвежда клиентския bundle, или redesign-вайте приложението, за да предоставя конфигурация по време на изпълнение чрез механизъм, контролиран от сървъра.

Vite също замества клиентски env стойности по време на build

Документацията на Vite казва, че import.meta.env константите се заместват статично по време на bundling. Следователно, ако локалната разработка работи, но production bundle-ът не, проверете дали VITE_SUPABASE_URL и VITE_SUPABASE_PUBLISHABLE_KEY са съществували в build средата—а не само на машината, която по-късно обслужва статичните файлове.

Monorepos: проверете коя директория всъщност е коренът на приложението

Един monorepo може да съдържа:

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

Ако Next.js или Vite командата се изпълнява с apps/web като корен на приложението, env файл, поставен само в repo/.env.local, може да не е файлът, който фреймуъркът зарежда. envDir на Vite по подразбиране е коренът на проекта, а Next.js очаква своите .env* файлове в корена на Next.js проекта.

Поправяне: идентифицирайте директорията, съдържаща package.json и конфигурацията на фреймуърка на приложението, след което поставете env файла там, където това приложение го очаква, или експлицитно конфигурирайте директорията на средата, когато фреймуъркът поддържа това.

Supabase Edge Functions използват различни текущи имена на променливи по подразбиране

Ако грешката е вътре в Supabase Edge Function, не копирайте сляпо Next.js или Vite пример.

Текущата документация за променливи на средата на Edge Functions на Supabase изброява тези secrets по подразбиране, между други:

• SUPABASE_URL
• SUPABASE_DB_URL
• SUPABASE_PUBLISHABLE_KEYS
• SUPABASE_SECRET_KEYS
• SUPABASE_JWKS

Забележете, че SUPABASE_PUBLISHABLE_KEYS и SUPABASE_SECRET_KEYS са в множествено число. Ръководството за миграция на Supabase обяснява, че тези нови променливи съдържат JSON обекти, ключирани по името на API ключа. За secret ключ по подразбиране:

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

По време на миграцията, наследени Edge Function променливи като SUPABASE_ANON_KEY и SUPABASE_SERVICE_ROLE_KEY могат да съществуват заедно с новите речници на ключове. Не предполагайте, че името на променливата от стар урок за функции съвпада с новия тип ключ, който току-що сте създали.

Не решавайте грешката, като излагате secret ключ

Изкушаващо „поправяне“ е да добавите NEXT_PUBLIC_ или VITE_ към сървърен secret, за да може браузърът най-накрая да го прочете. Това може да елиминира грешката за липсваща променлива, като създаде проблем със сигурността.

Текущото ръководство за API ключове на Supabase е изрично:

• Publishable ключ: предназначен за публични компоненти като браузър и мобилни приложения.
• Secret ключ: предназначен само за backend компоненти, които контролирате; той заобикаля Row Level Security.

Ако secret ключ е бил изложен в source code, публичен bundle, екранна снимка или repository, премахнете или ротирайте го през настройките на API Keys на Supabase, вместо просто да преименувате променливата на средата.

Чести симптоми и най-бързата проверка

Финална самопроверка: потвърдете конфигурацията в правилния ред

Преди да обявите проблема за поправен, изпълнете този чеклист:

1. Потвърдете, че Supabase Project URL идва от проекта, който всъщност възнамерявате да използвате.
2. За браузър/клиентски код, потвърдете, че използвате текущ publishable ключ или все още активен наследен anon ключ—а не secret ключ.
3. Потвърдете, че кодът и env файлът използват едни и същи имена на променливи.
4. За Next.js клиентски код, използвайте NEXT_PUBLIC_* и директни process.env.VARIABLE_NAME препратки.
5. За Vite клиентски код, използвайте VITE_* и import.meta.env.VARIABLE_NAME.
6. Дръжте .env.local в корена на приложението, а не вътре в /src.
7. Рестартирайте сървъра за разработка след редактиране на env файловете.
8. За production, задайте стойностите в правилната среда за деплоймент и rebuild/redeploy.
9. Не логвайте или излагайте sb_secret_... ключове.
10. Премахнете временните debug логове, след като конфигурацията е потвърдена.

Когато createClient() се инициализира без грешката за липсващ ключ, проблемът с променливите на средата е разрешен. Ако следващата Supabase заявка върне грешка за авторизация, Row Level Security или разрешение за таблица, третирайте това като отделен проблем. Валиден API ключ не гарантира, че извикващият е разрешен да чете или модифицира всеки ред; Supabase намерено разделя идентификацията на API ключа от автентикацията на потребителя и авторизацията на базата данни.

Трайното поправяне не е „преименувайте ключа, докато работи“. То е да подравните четири неща: текущия тип Supabase ключ, името на променливата на средата, правилата за излагане на фреймуърка и средата, в която приложението всъщност се изгражда или изпълнява. След като тези съвпаднат, Supabase клиентът получава реален ключ вместо undefined, и объркващият цикъл на конфигурация приключва.