Next.js无法读取.env文件变量致Stripe初始化报错如何解决

问题现象 #

运行时触发报错：

Uncaught (in promise) IntegrationError: Please call Stripe() with your publishable key. You used an empty string.

对应初始化代码：

import Stripe from "stripe";

const stripe = new Stripe(process.env.NEXT_PUBLIC_STRIPE_SECRET_KEY);

.env配置：

NEXT_PUBLIC_STRIPE_SECRET_KEY=***

根因是Next.js未正确加载对应环境变量，传入Stripe构造函数的参数为空字符串，同时当前配置存在Stripe密钥混用的安全风险。

排查修复步骤 #

1. 先修正环境变量配置规范 #

• 确认.env文件放在项目根目录，和package.json、next.config.js文件同级，不要放在src、app、pages等子目录下
• 检查.env内变量写法：变量名、等号、值之间不能加空格，错误写法NEXT_PUBLIC_STRIPE_SECRET_KEY = ***会解析失败，正确写法为等号两侧无空格：NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_***
• 修正Stripe密钥混用问题：
  • Stripe的sk_开头的密钥为服务端密钥，绝对不能加NEXT_PUBLIC_前缀暴露到客户端，仅能在API Routes、Server Actions、服务端组件中使用
  • 客户端初始化Stripe必须使用pk_开头的可公开发布密钥（publishable key），对应变量加NEXT_PUBLIC_前缀，和报错提示要求的参数类型匹配

警告：将sk_开头的Stripe密钥配置为NEXT_PUBLIC_前缀会导致密钥泄露，任何人都可以盗用你的Stripe账户发起操作，存在严重安全风险。

2. 重启服务清除构建缓存 #

Next.js仅在服务启动、构建阶段读取.env文件，修改环境变量不会触发热更新：

• 终止当前运行的next dev或next build进程
• 删除项目根目录下的.next缓存文件夹
• 重新执行对应启动命令（npm run dev/pnpm dev/yarn dev）启动服务

3. 排查变量覆盖问题 #

如果重启后变量仍为undefined，按以下点排查：

• 检查项目根目录下是否存在更高优先级的环境变量文件，Next.js环境变量优先级为：.env.local > .env.development/.env.production（匹配当前运行环境） > .env，如果高优先级文件中存在同名变量且值为空，会覆盖.env中的配置
• 如果使用Turbo、Nx等 monorepo 工具，检查根目录配置、工具侧的环境变量透传规则，避免变量被过滤
• 如果使用App Router，在客户端组件顶部必须添加'use client'指令，否则组件在服务端渲染阶段无法正确读取NEXT_PUBLIC_开头的客户端变量
• 可以在代码中临时加打印确认变量值：

  console.log("当前读取到的Stripe公钥：", process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)
  

4. 增加初始化兜底校验 #

在Stripe初始化逻辑前增加空值判断，避免空字符串传入触发无明确提示的报错：

const stripePublishableKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
if (!stripePublishableKey) {
  throw new Error("请在.env文件中配置NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY")
}
const stripe = new Stripe(stripePublishableKey)

内容的提问来源于stack exchange，提问作者Cláudio Vitor Dantas