如何在Next.js项目中读取Google Cloud Run配置的环境变量

原因1：未按Next.js规则区分服务端/客户端环境变量 #

• Next.js 规定只有前缀为NEXT_PUBLIC_的环境变量会被嵌入到客户端打包产物中，可在客户端组件、浏览器端运行的代码中通过process.env.NEXT_PUBLIC_XXX读取
• 不带此前缀的环境变量仅能在**服务端组件、API路由、服务端执行的函数（比如getServerSideProps、generateMetadata等服务端生命周期）**中读取，如果你在客户端侧代码直接读取非NEXT_PUBLIC_前缀的变量，生产环境必然返回undefined，和部署平台无关

注意：本地开发时如果你在服务端代码中打印非公开环境变量能正常返回，不代表客户端代码也能读取，请先确认你读取变量的代码执行端。

原因2：构建时静态注入了环境变量，运行时Cloud Run注入的变量未生效 #

如果你开启了Next.js的静态生成（SSG）、或者构建时直接把环境变量编译进了静态产物，那么Cloud Run在容器运行时注入的变量不会替换已打包的静态值，需要做如下调整：

• 如果你需要使用运行时注入的变量，对于需要动态读取变量的页面，使用服务端渲染（SSR）或者动态渲染配置，在页面顶部添加配置：

// 页面顶部添加，强制页面动态渲染，每次请求时读取最新运行时环境变量
export const dynamic = 'force-dynamic'

• 如果你使用next.config.js的env配置项硬编码了变量，请删除该配置，改为依赖运行时注入。

原因3：Dockerfile配置错误未传递运行时环境变量 #

大部分部署到Cloud Run的Next.js应用会使用官方推荐的standalone构建模式，若你的Dockerfile配置错误，会导致容器运行时无法接收Cloud Run注入的环境变量，检查以下配置：

• 确保你的Dockerfile运行阶段是从构建产物启动，没有覆盖process.env相关逻辑，官方推荐的精简Dockerfile示例如下：

# 构建阶段
FROM node:18-alpine AS base
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 运行阶段
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000
# 启动命令没有硬编码环境变量，会自动继承Cloud Run注入的系统环境变量
CMD ["node", "server.js"]

• 不要在Dockerfile的CMD或者ENTRYPOINT里手动覆盖process.env的取值，也不要在构建阶段通过--build-arg传递本应该是运行时注入的变量。

验证方法 #

部署后可以先在Cloud Run的服务日志里打印服务端侧的process.env，确认变量是否已经被正确注入到容器运行时：

1. 在任意API路由中添加打印逻辑：

// app/api/test-env/route.ts
export async function GET() {
  console.log('服务端环境变量：', process.env.YOUR_VARIABLE_NAME)
  return Response.json({ envExists: !!process.env.YOUR_VARIABLE_NAME })
}

2. 访问该接口后查看Cloud Run日志，如果日志中能打印出正确的变量值，说明Cloud Run注入正常，问题出在你的代码读取端（比如在客户端读了非公开变量）；如果日志中也没有该变量，检查Cloud Run的环境变量配置是否正确绑定到了当前修订版本，是否填写了正确的变量名（大小写敏感）。

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