如何为部署在Dokku上的Next.js应用配置可读取的环境变量？

排查与解决方案 #

1. 先确认应用已重启

执行命令手动重启应用，确保环境变量生效：

dokku ps:restart app_name

重启后重新测试API路由，查看是否能获取到变量。

2. 针对NEXT_PUBLIC_前缀变量的特殊处理

NEXT_PUBLIC_开头的变量会被Next.js在构建阶段静态注入客户端代码，如果你的Dockerfile包含npm run build步骤，需要确保构建阶段能读取到该变量：

方法A：使用Dokku构建环境插件

Dokku默认不会将config:set的变量传递给Dockerfile构建阶段，安装build-env插件解决：

sudo dokku plugin:install https://github.com/dokku/dokku-build-env.git build-env
dokku build-env:set app_name NEXT_PUBLIC_SERVER_URL=https://server_url.com

之后重新推送代码或触发构建。

方法B：修改Dockerfile添加构建参数

在Dockerfile中声明构建参数，确保构建和运行阶段都能访问变量：

# 构建阶段
FROM node:18-alpine AS builder
ARG NEXT_PUBLIC_SERVER_URL
ENV NEXT_PUBLIC_SERVER_URL=$NEXT_PUBLIC_SERVER_URL
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# 运行阶段
FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
EXPOSE 3000
CMD ["npm", "start"]

配置Dokku构建参数：

dokku docker-options:add app_name build "--build-arg NEXT_PUBLIC_SERVER_URL=https://server_url.com"

重新部署应用。

3. 仅服务器端使用时，移除NEXT_PUBLIC_前缀

如果该变量仅在API路由（服务器端）使用，无需客户端访问，直接改用普通环境变量：

dokku config:set app_name SERVER_URL=https://server_url.com

修改API路由代码：

export async function GET() {
  const baseUrl = process.env.SERVER_URL;
  return NextResponse.json({
    baseUrl,
  });
}

普通环境变量会由Dokku在容器运行时自动传递，服务器端代码可直接读取。

4. 验证容器内环境变量

进入容器确认变量是否存在：

dokku enter app_name web
echo $NEXT_PUBLIC_SERVER_URL

如果输出正确值，问题出在Next.js配置；如果为空，检查Dokku应用配置或Dockerfile的启动逻辑。

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