Docker构建Next.js应用失败（本地正常）：含循环JSON等报错求助

问题情况 #

本地构建Next.js应用完全正常，但Docker里构建失败。已在next.config.js中配置output: 'standalone'，使用yarn管理依赖，Dockerfile和.dockerignore直接复用Next.js官方示例。

构建错误信息 #

构建过程先出现ESLint缺失提示，随后核心报错为循环引用结构无法转JSON，最终导致构建重试次数耗尽：

#13 1.544 error - ESLint must be installed in order to run during builds: yarn add --dev eslint
...
#13 11.45 TypeError: Converting circular structure to JSON
#13 11.45     --> starting at object with constructor 'Socket'
#13 11.45     |     property '_httpMessage' -> object with constructor 'ClientRequest'
#13 11.45     --- property 'socket' closes the circle
...
#13 13.31 Error: Call retries were exceeded

解决步骤 #

1. 处理ESLint缺失问题 #

官方Docker构建流程默认会执行ESLint检查，但项目可能本地未安装ESLint，或.dockerignore忽略了node_modules导致Docker环境无此依赖，二选一解决：

• 安装ESLint到开发依赖：

  yarn add --dev eslint
  

  提交package.json和yarn.lock后重新构建镜像。
• 禁用构建时的ESLint检查：
  修改package.json中的build命令：

  "scripts": {
    "build": "next build --no-lint"
  }
  

2. 解决循环引用JSON序列化错误 #

该错误出现在页面数据收集阶段，大概率是getStaticProps/getServerSideProps返回的props中存在循环引用对象，或包含Socket、HTTP请求/响应这类无法序列化的实例：

• 排查所有页面的getStaticProps/getServerSideProps函数，确保返回的props无循环引用，也不包含无法序列化的对象实例。
• 本地构建正常但Docker失败，可能是本地有缓存干扰，试试本地执行next build --no-cache，复现问题方便排查。

3. 可选：优化Dockerfile构建逻辑 #

若上述步骤未解决问题，调整Dockerfile确保构建阶段获取完整依赖：

# 安装依赖阶段
FROM node:18-alpine AS deps
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

# 构建应用阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN yarn build

# 运行环境阶段
FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

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

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