Next.js环境变量无法访问致Supabase客户端创建失败

问题场景 #

使用Next.js和Supabase开发应用时，在/utils/supabase-client.js中通过环境变量创建Supabase客户端，抛出错误Error: supabaseUrl is required.：

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

const supabaseUrl = process.env.SUPABASE_PROJECT_URL
const supabaseAnonKey = process.env.SUPABASE_ANON_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

• .env文件已正确配置变量：

  SUPABASE_PROJECT_URL=myRealSupabaseProjectUrl
  SUPABASE_ANON_KEY=myRealSupabaseAnonKey
  

• 其他环境变量（如Contentful API密钥）可正常使用，在/utils/supabase-client.js中打印supabaseUrl和supabaseAnonKey能得到正确值
• 将环境变量替换为硬编码值后，代码完全正常运行
• 在模板页面中导入客户端并使用：

  import { supabase } from '../lib/supabase-client'
  

可能原因及解决方案 #

1. 模块顶层初始化时机问题 #

Next.js在某些场景（如静态生成、服务器组件初始化阶段）下，环境变量可能未完全加载完成，导致模块顶层执行createClient时变量为undefined。

解决方法：延迟初始化客户端，封装成函数按需调用
修改/utils/supabase-client.js：

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

let supabaseInstance = null

export const getSupabase = () => {
  if (!supabaseInstance) {
    const supabaseUrl = process.env.SUPABASE_PROJECT_URL
    const supabaseAnonKey = process.env.SUPABASE_ANON_KEY
    
    if (!supabaseUrl || !supabaseAnonKey) {
      throw new Error('Supabase环境变量未配置')
    }
    
    supabaseInstance = createClient(supabaseUrl, supabaseAnonKey)
  }
  return supabaseInstance
}

在组件中使用时，按需获取客户端实例：

import { getSupabase } from '../lib/supabase-client'

const handleViews = useCallback(async () => {
  const supabase = getSupabase()
  try {
    const { data } = await supabase
      .from('Page Views')
      .select()
      .eq('slug', query)
    
    try {
      if (!data || data.length < 1) {
        return await supabase
          .from('Page Views')
          .insert({ slug: query, views: 1 })
      } else {
        const views = data[0]?.views
        return await supabase
          .from('Page Views')
          .update({ slug: query, views: views + 1 })
      }
    } catch (err) {
      console.log(err, 'error')
    }
  } catch (err) {
    console.log(err, 'error')
  }
}, [query])

2. 导入路径错误 #

检查模板页面中的导入路径：代码中导入的是../lib/supabase-client，但客户端文件实际在/utils/supabase-client.js目录下，可能存在路径不匹配，导致导入了未正确配置的其他客户端文件。

解决方法：修正导入路径，确保指向正确的supabase-client.js文件

3. 环境变量加载优先级问题（Next.js 13+ App Router） #

在App Router模式下，环境变量的加载逻辑可能与Pages Router不同，可手动触发环境变量加载。

解决方法：在supabase-client.js顶部添加环境变量加载逻辑

import { loadEnvConfig } from '@next/env'
import { createClient } from '@supabase/supabase-js'

// 手动加载项目根目录的环境变量
const projectDir = process.cwd()
loadEnvConfig(projectDir)

const supabaseUrl = process.env.SUPABASE_PROJECT_URL
const supabaseAnonKey = process.env.SUPABASE_ANON_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

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