Next.js 14 Docker多阶段构建后无法访问localhost问题排查

我按照Next.js 14的Docker多阶段构建教程操作，甚至克隆官方仓库确认配置无误，但构建后的应用无法在浏览器访问。执行docker ps可见容器映射了3000端口，Docker Desktop也显示容器正常运行，且能通过docker exec进入容器，但访问http://localhost:3000时提示无法连接。已排除WSL2问题（我的Laravel容器可正常访问），以下是我的Dockerfile和docker-compose.yml配置，请问我遗漏了什么？

Dockerfile #

# 1. Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat

WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i; \
  else echo "Lockfile not found." && exit 1; \
  fi

# 2. Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# This will do the trick, use the corresponding env file for each environment.
# COPY .env.development.sample .env.production
RUN yarn build

# 3. Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001

COPY --from=builder /app/public ./public

# FROM https://dev.to/francescoxx/wtfnextjs-app-deployed-with-docker-4h3m
# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
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
ENV HOSTNAME localhost

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

docker-compose.yml #

services:
  app:
    container_name: 'lux-fe-tstw'
    image: luxfetstw
    build:
      context: ../../
      dockerfile: docker/development/Dockerfile
    ports:
      - '3000:3000'

解决方案 #

你的配置里有三个关键问题导致无法访问：

1. 未指定基础镜像 #

Dockerfile开头的FROM base AS deps中，base是未定义的镜像别名，Docker无法识别要使用的Node.js基础环境。需要在Dockerfile最顶部添加具体的Node.js基础镜像定义，替换所有FROM base的引用：

# 添加在Dockerfile最顶部
FROM node:20-alpine AS base

# 后续的deps、builder、runner阶段都使用这个base
FROM base AS deps
# ... 其余代码不变

2. 应用绑定地址错误 #

容器内设置ENV HOSTNAME localhost会让Next.js仅监听容器内部的127.0.0.1接口，外部通过端口映射无法访问。需要修改为监听所有网络接口：

# 替换原HOSTNAME配置
ENV HOSTNAME 0.0.0.0

3. 缺少Next.js Standalone模式配置 #

使用/.next/standalone目录需要在项目的next.config.js中开启独立输出模式，否则构建时不会生成可直接运行的server.js文件。在项目根目录的next.config.js中添加以下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig

验证步骤 #

修改完成后，重新构建并启动容器：

docker-compose down && docker-compose up --build

可先进入容器执行curl http://localhost:3000验证应用内部是否正常响应，再测试外部浏览器访问。

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