Next.js集成Supabase遇API Key无效等配置问题求助

1. 环境变量基础检查 #

• 确认根目录环境变量文件命名为.env.local，Next.js仅自动加载该文件，其他命名（如.env）无法被客户端组件读取
• 变量名严格匹配NEXT_PUBLIC_SUPABASE_URL和NEXT_PUBLIC_SUPABASE_ANON_KEY，注意大小写、下划线不能出错，避免多写/漏写字符
• 变量值不要加引号，直接写原始内容（如https://xxx.supabase.co），引号会被当作值的一部分导致密钥无效

2. 验证环境变量加载状态 #

在客户端组件中加入调试代码，确认变量是否被正确读取：

console.log('Supabase URL:', process.env.NEXT_PUBLIC_SUPABASE_URL);
console.log('Supabase Anon Key:', process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY);

• 若打印结果为undefined，需重启开发服务器（执行npm run dev），修改.env.local后必须重启才能生效
• 服务端组件中可直接用process.env访问，但服务端专属密钥（如SUPABASE_SERVICE_ROLE_KEY）不要加NEXT_PUBLIC_前缀，仅客户端用的ANON_KEY需要该前缀

3. 客户端初始化代码校验 #

客户端初始化文件（如utils/supabase/client.ts）需正确引用环境变量：

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;

export const supabase = createClient(supabaseUrl, supabaseAnonKey);

• 禁止将服务端的SUPABASE_SERVICE_ROLE_KEY当作客户端ANON_KEY使用，前者权限极高且会触发"Invalid API Key"错误
• 服务端客户端（如utils/supabase/server.ts）初始化时，服务端密钥不要加NEXT_PUBLIC_前缀：

import { createServerClient, type CookieOptions } from '@supabase/ssr';
import { cookies } from 'next/headers';

export const createSupabaseServerClient = async () => {
  const cookieStore = cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.SUPABASE_SERVICE_ROLE_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value;
        },
        set(name: string, value: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value, ...options });
          } catch (e) {}
        },
        remove(name: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value: '', ...options });
          } catch (e) {}
        },
      },
    }
  );
};

4. 变量值正确性验证 #

• 直接从Supabase控制台复制Project URL和anon public密钥，避免手动输入导致的字符遗漏、拼写错误
• 若密钥包含+、/等特殊字符，无需转义，Next.js会正确处理
• 部署到Vercel等平台时，需在平台的环境变量设置中添加这两个变量，本地.env.local不会被上传至服务器

5. 依赖版本排查 #

执行命令更新Supabase相关依赖至最新稳定版，旧版本可能存在环境变量读取逻辑差异：

npm update @supabase/supabase-js @supabase/ssr

内容的提问来源于stack exchange，提问作者tota2000