修复 Next.js 构建报错 supabaseUrl is required 实战

Next.js 应用在 next build 阶段突然抛出 Error: supabaseUrl is required.，导致整个构建流程中断——这是不少使用 Supabase 的开发者都遇到过的场景，尤其当项目由 AI 编程工具生成时。本文基于一次可复现的实测，拆解错误根因并给出最小修复方案，同时明确哪些结论有测试支撑、哪些尚未验证。

错误现场：构建期间的模块求值失败

在一次合成的小型 Next.js 应用中（未配置 .env 文件，也未设置任何 Supabase 变量），执行 npx next build 得到如下输出：

Collecting page data using 5 workers ...
Error: Failed to collect configuration for /api/waitlist
  [cause]: Error: supabaseUrl is required.
    at module evaluation (app/api/waitlist/route.js:3:7)
> 3 | const supabase = createClient(

退出码为 1。相同的报错文本也出现在公开报告中，例如 vercel/next.js#69095（Vercel 构建环境，Next 14.2.3）。这说明问题并非孤立个案，而是与特定的代码组织方式相关。

测试所用版本组合为：Node.js 20.19.2、npm 11.21.0、next 16.4.2（Turbopack 构建）、react 19.3.1、@supabase/supabase-js 2.109.0，运行于单台 Linux 机器。

模块求值（module evaluation） 是 JavaScript 引擎执行模块顶层代码的过程。ES 模块在被导入时，其顶层语句（import、变量声明、函数调用等）会立即执行一次，结果被缓存供后续导入复用。Next.js 在 next build 的「收集页面数据」阶段会导入每个路由模块，以便静态分析其导出（如 GET、POST、dynamic 配置）。这意味着路由文件的顶层代码在构建期就会被真实执行——而不是等到第一个 HTTP 请求到来。任何依赖运行时环境（环境变量、数据库连接、文件系统）的顶层调用都会在这一刻被求值，缺失依赖即抛错。理解这一点是判断「哪些代码该放在模块顶层、哪些该延迟到函数内」的关键。

根因分析：顶层创建客户端遇上缺失的环境变量

next build 期间，Next.js 会加载路由模块以收集页面数据。如果路由文件在模块作用域顶层执行了 createClient(process.env.NEXT_PUBLIC_SUPABASE_URL, ...)，那么这行代码会在构建阶段就被求值。

此时若环境变量缺失——没写进 .env.local、托管平台未配置、变量名拼写错误，或者变量只作用于 Production 而当前构建的是 Preview 环境——createClient 会直接抛错，整个构建随之失败。

值得留意的是，AI 编程工具大量生成这种顶层实例化模式。它看起来简洁，却把运行时依赖硬编码进了构建期，是典型的"本地能跑、CI 挂掉"诱因。

最小修复：把实例化推迟到请求时

修复思路很直接：将客户端创建移入函数，在请求处理时调用。

修复前（构建失败）：

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

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
);

export async function POST(req) {
  const { email } = await req.json();
  const { error } = await supabase.from("waitlist").insert({ email });
  return Response.json({ ok: !error });
}

修复后（构建通过）：

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

function getSupabase() {
  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
  const key = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
  if (!url || !key) {
    throw new Error("Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY");
  }
  return createClient(url, key);
}

export async function POST(req) {
  try {
    const { email } = await req.json();
    const { error } = await getSupabase().from("waitlist").insert({ email });
    return Response.json({ ok: !error });
  } catch (e) {
    return Response.json({ ok: false, error: e.message }, { status: 500 });
  }
}

这个改动的关键收益有两层：构建不再因环境变量缺失而中断；变量缺失时错误从构建期转移到请求期，并带有明确的缺失变量名，便于排查。

如果使用 AI 编程工具，可以用如下提示词描述改动（注：原文未在任何工具中实际测试该提示词，diff 仍需自行审查）：

My Next.js build fails with "Error: supabaseUrl is required." Find every file that calls createClient from @supabase/supabase-js at the top level of a module. Move each call into a getSupabase() function that reads process.env at request time and throws a clear error naming the missing variable. Don't rename variables, don't print key values, don't change anything else. Show me the diff.

动态路由标记（ƒ） 是 Next.js 构建输出中的一种路由分类。构建结束时，Next.js 会列出所有路由并标注渲染模式：○ 表示静态预渲染，● 表示 SSG，ƒ 表示服务端按请求动态渲染。当路由模块在构建期无法确定输出（例如读取了请求对象、使用了仅在请求时可用的变量），Next.js 会将其归为动态路由，不在构建时生成静态页面。修复后 /api/waitlist 被标记为 ƒ，说明它已从「构建期求值失败」转为「请求期执行」，这正是把 createClient 移入函数后产生的预期效果。若某个路由本应静态化却被标为 ƒ，通常意味着无意中引入了请求期依赖。

验证方式与实测结果

所有运行均在 2026-10-18 完成，未配置 .env 文件，未设置任何 Supabase 变量：

1. 修复前：npx next build 失败并抛出上述错误，退出码 1。
2. 修复后：npx next build 退出码 0，输出中 /api/waitlist 被标记为动态路由（ƒ）。
3. 修复后、运行时缺变量：启动 npx next start 后，向 /api/waitlist 发送带假邮箱的 POST 请求，返回 HTTP/1.1 500 与 {"ok":false,"error":"Missing NEXT_PUBLIC_SUPABASE_URL or NEXT_PUBLIC_SUPABASE_ANON_KEY"}。

需要明确的是，这个修复并不提供密钥本身。它让构建通过，并把失败变成一条清晰的请求期错误。部署后的应用若要用 Supabase，仍需在托管平台设置变量。另外，NEXT_PUBLIC_ 前缀的值会在构建时内联，修改变量后需要重新部署（这是 Next.js 的既有行为，本次未复测）。

NEXT_PUBLIC_ 前缀的构建期内联 是 Next.js 环境变量机制的重要细节。带 NEXT_PUBLIC_ 前缀的变量会在 next build 时被字面替换进客户端 bundle 和引用了它的服务端代码中，而不是在运行时从 process.env 读取。因此一旦构建完成，这些值就「冻结」在产物里：在托管平台修改变量后，必须重新构建并部署，新值才会生效；仅重启服务无效。这也是为什么把 Supabase URL 和 anon key 写成 NEXT_PUBLIC_ 是安全的（它们本就是公开可暴露的），但 service-role 密钥绝不能加该前缀——它会被打进发送到浏览器的 JS 中。

尚未验证的边界

为避免过度外推，以下内容不在本次测试范围内：

• 未连接真实 Supabase 项目，没有执行过成功插入或任何网络请求；
• 未在 Vercel、Netlify 或其他托管构建环境测试；
• 未测试 Lovable、Bolt、Cursor、v0 等 AI 工具的输出，测试应用为手写合成项目；
• 未覆盖其他版本（包括 Next 14）、Pages Router、Vite/React 应用；
• 上述 AI 提示词未在任何工具中运行；
• CI 中使用占位环境变量的变通方案未测试；
• 拼写错误、缺少前缀、缺少 .env.local 等其他同症状原因未复现。

快速排查清单

• 构建通过，线上返回缺失变量错误：在托管平台按精确名称设置变量，然后重新部署。
• 修复后仍报同样错误：检查是否还有其他文件在顶层创建客户端，全局搜索 createClient(。
• 本地正常、托管环境失败：.env.local 通常不会被提交，托管环境看不到它。

安全方面提醒两点：service-role 密钥绝不能放进 NEXT_PUBLIC_ 变量，因为它会随代码发送到每个浏览器；真实密钥也不要粘贴到 AI 对话或公开 issue 中。