Next.js环境变量可打印但执行时无法使用问题求助

问题 #

打印process.env.SUPABASE_SERVICE_ROLE_KEY时显示该变量已定义，但代码执行时却提示缺失；硬编码服务角色密钥后代码运行正常。相关代码如下：

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

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

export const supabasePublic = createClient(
  supabaseUrl,
  supabaseAnonKey
);

console.log("supabaseServiceKey: ", supabaseServiceKey);

if (!supabaseServiceKey) {
  throw new Error("Missing SUPABASE_SERVICE_ROLE_KEY");
}

export const supabasePrivate = createClient(
  supabaseUrl,
  supabaseServiceKey
);

在Next.js项目中用npm run dev启动，刷新页面时supabaseServiceKey能正常打印，但随后会触发Missing SUPABASE_SERVICE_ROLE_KEY错误。

执行路径如下：

/pages/checkout (客户端)  
/src/services/balance (客户端)  
/pages/api/get-balance (服务端)  
/src/utils/supabase/fetch-row (服务端，因被导入到API路由)  
/src/utils/supabase/create-client (服务端，因被导入到API路由)

更奇怪的是，错误抛出后还有日志暗示Supabase客户端已创建成功。

解决方案 #

1. 明确环境变量作用域 #

SUPABASE_SERVICE_ROLE_KEY是服务端专用变量，Next.js不会将不带NEXT_PUBLIC_前缀的环境变量暴露给客户端。你的代码同时被客户端和服务端导入，服务端渲染时能打印变量值，但客户端执行时该变量会变为undefined，进而触发错误。

2. 拆分客户端与服务端的Supabase客户端逻辑 #

将服务端专用的客户端创建代码单独隔离，避免被客户端代码导入：

服务端专用客户端文件（src/utils/supabase/server-client.js）

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

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

if (!supabaseServiceKey) {
  throw new Error("Missing SUPABASE_SERVICE_ROLE_KEY");
}

export const supabasePrivate = createClient(
  supabaseUrl,
  supabaseServiceKey
);

客户端专用客户端文件（src/utils/supabase/client-client.js）

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 supabasePublic = createClient(
  supabaseUrl,
  supabaseAnonKey
);

3. 检查环境变量配置与加载 #

• 确认.env.local文件中SUPABASE_SERVICE_ROLE_KEY拼写无误，无多余空格或格式错误。
• 重启npm run dev服务，确保环境变量重新加载生效。

4. 验证导入路径 #

确保服务端API路由仅导入服务端专用的supabasePrivate，客户端代码仅导入supabasePublic，彻底避免跨环境导入导致的变量缺失问题。

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