Next.js 12.1部署后客户端环境变量未定义问题求助

我使用Next.js 12.1版本，本地通过.env.local定义环境变量时运行正常，但部署至服务器后，客户端中的环境变量显示undefined（服务器终端可正常读取）。浏览器控制台输出undefined，服务器日志显示正常，附上相关代码请求排查。

next.config.js #

/** @type {import('next').NextConfig} */

const nextConfig = {
  experimental: {
    outputStandalone: true,
  },
  compiler: { styledComponents: true },
  env: {
     NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
  },
};

module.exports = nextConfig;

Dockerfile #

FROM node:16-alpine AS deps

ENV http_proxy=http://fodev.org:8118
ENV https_proxy=http://fodev.org:8118

RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json ./ 
RUN npm install --force

# If using yarn with a `yarn.lock` comment out above and use below instead
# COPY package.json yarn.lock ./
# RUN yarn install --frozen-lockfile

FROM node:16-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED 1

RUN npm run build

# If using yarn comment out above and use below instead
# RUN yarn build

FROM node:16-alpine AS runner
WORKDIR /app

ENV NODE_ENV production

ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./package.json

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

CMD ["node", "server.js"]

Footer组件代码 #

import React from "react";
import Link from "next/link";

const Footer = () => {
  console.log(process.env.NEXT_PUBLIC_COMPANY_NAME );
  return (
    <footer
      className="md:px-10 lg:p-14 text-gray-600 relative flex flex-wrap justify-center mx-auto "
      style={{ background: "var(--gray)" }}
      dir="rtl"
    >
     <div>{process.env.NEXT_PUBLIC_COMPANY_NAME || "CmpName"} </div>
    </footer>
  );
};

export default Footer;

现象 #

• 浏览器控制台：输出undefined
• 服务器日志：可正常读取环境变量

排查与解决 #

核心问题 #

Next.js中带NEXT_PUBLIC_前缀的环境变量，必须在构建阶段存在才能被注入到客户端代码。你的Docker构建流程中，builder阶段未传入目标环境变量，导致构建时无法将变量打包进客户端代码，最终浏览器端读取到undefined。另外，next.config.js仅声明了NEXT_PUBLIC_SITE_URL，但代码中使用的是NEXT_PUBLIC_COMPANY_NAME，存在配置遗漏。

解决步骤 #

1. 在Docker构建的builder阶段传入环境变量
   推荐通过构建参数传递（灵活适配不同环境），修改builder阶段的Dockerfile：

   FROM node:16-alpine AS builder
   WORKDIR /app
   COPY --from=deps /app/node_modules ./node_modules
   COPY . .
   
   # 接收构建参数并设置为环境变量
   ARG NEXT_PUBLIC_COMPANY_NAME
   ENV NEXT_PUBLIC_COMPANY_NAME=$NEXT_PUBLIC_COMPANY_NAME
   # 若有其他NEXT_PUBLIC_变量，同理添加
   ARG NEXT_PUBLIC_SITE_URL
   ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
   
   ENV NEXT_TELEMETRY_DISABLED 1
   # 可选：添加echo命令验证环境变量是否传入
   RUN echo "NEXT_PUBLIC_COMPANY_NAME: $NEXT_PUBLIC_COMPANY_NAME"
   RUN npm run build
   

   构建镜像时传递参数：

   docker build --build-arg NEXT_PUBLIC_COMPANY_NAME="你的公司名称" --build-arg NEXT_PUBLIC_SITE_URL="你的站点URL" .
   

2. 简化next.config.js配置
   Next.js 12会自动注入所有带NEXT_PUBLIC_前缀的环境变量，无需在next.config.js中显式声明，删除env配置块即可：

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     experimental: {
       outputStandalone: true,
     },
     compiler: { styledComponents: true },
   };
   
   module.exports = nextConfig;
   

3. 确认运行阶段无需传递客户端环境变量
   客户端环境变量已在构建阶段打包进代码，服务器运行阶段不需要再设置这些变量，runner阶段保持原有配置即可。

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