Next.js集成Clerk遇publishableKey缺失及Vercel 500错误求助

问题场景 #

我在为Next.js应用配置Clerk身份验证时，遇到publishableKey缺失的问题，同时触发了Vercel的500服务器错误。

错误日志 #

Aug 09 04:26:43.49 GET
--- canva-clone-fabricjs.vercel.app / Error: @clerk/nextjs: Missing publishableKey. You can get your key at
(链接已省略) at
(node_modules/@clerk/shared/dist/chunk-T5VTDOY6.mjs:155:0) at
(node_modules/@clerk/nextjs/dist/esm/server/clerkMiddleware.js:29:22)
at (node_modules/@clerk/nextjs/dist/esm/server/utils.js:143:0) at
(node_modules/@clerk/nextjs/dist/esm/server/clerkMiddleware.js:28:0)
at (src/middleware.ts:11:31) at (webpack/bootstrap:21:0) at
(../../src/client/components/static-generation-async-storage-instance.ts:5:2)
at (webpack/runtime/jsonp chunk loading:34:0)

Aug 09 04:26:43.45 GET
500 canva-clone-fabricjs.vercel.app / [GET] [middleware:
"src/middleware"] / reason=EDGE_FUNCTION_INVOCATION_FAILED,
status=500, user_error=true

本地环境变量配置（.env.local） #

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<my_publishable_key>
CLERK_SECRET_KEY=<my_secret_key>
CLERK_PUBLISHABLE_KEY=<my_publishable_key> # required by hono clerk auth

已尝试的操作 #

• 在ClerkProvider中显式传入publishableKey：

  <ClerkProvider afterSignOutUrl="/" publishableKey={process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}>
  

• 在Vercel控制台直接添加NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY环境变量

但错误仍未解决。

排查与解决步骤 #

1. 检查Middleware中Clerk的初始化配置 #

错误堆栈指向src/middleware.ts第11行，说明Clerk中间件在Edge Runtime环境下无法读取到环境变量。

如果你的middleware使用了authMiddleware，需要确保初始化时正确传入publishableKey，或让它从环境变量读取。Edge Runtime中NEXT_PUBLIC_*变量可直接读取，但需确保Vercel环境变量已正确部署并注入。

修改middleware.ts示例：

import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({
  // 显式传入环境变量，确保读取路径正确
  publishableKey: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
  // 其他自定义配置...
});

export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};

2. 确认Vercel环境变量的部署状态 #

• 登录Vercel控制台，进入项目 → Settings → Environment Variables
• 确保NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY和CLERK_SECRET_KEY已添加，且Deployment Preview和Production环境均勾选
• 选择"Redeploy with cache cleared"重新部署，避免缓存导致环境变量未更新

3. 验证环境变量的命名与值的正确性 #

• 确认NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY拼写完全正确（环境变量名区分大小写）
• 检查复制的publishableKey无多余空格或换行，直接从Clerk控制台复制粘贴
• 确保Hono所需的CLERK_PUBLISHABLE_KEY与NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY值一致，且服务器端可正常读取

4. 本地模拟Vercel环境验证 #

运行vercel dev命令模拟Vercel部署环境，在middleware中临时添加日志（注意不要泄露敏感信息）：

// middleware.ts
console.log("Publishable Key preview:", process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.slice(0, 10) + "...");

export default authMiddleware(...);

启动后访问应用，查看终端日志确认变量是否被正确加载。

5. 升级Clerk版本 #

旧版本@clerk/nextjs可能存在环境变量读取bug，执行命令更新：

npm update @clerk/nextjs
# 或
yarn upgrade @clerk/nextjs

6. 检查Edge Runtime配置 #

Next.js Middleware默认使用Edge Runtime，确保middleware.ts中没有错误的运行时声明：

// 注释或删除错误的运行时配置
// export const runtime = 'nodejs'; // 这会导致Edge环境下环境变量读取失败

内容的提问来源于stack exchange，提问作者MInH THiỆn