Next.js项目Jenkins+Docker构建失败（退出码1）本地构建正常

核心问题定位 #

本地构建正常，但Jenkins+Docker环境下yarn build在生成静态页面阶段退出码1，问题大概率出在环境差异或构建过程中缺失的依赖/配置。

排查步骤与解决方案 #

1. 抓取完整构建日志，定位具体错误 #

当前报错信息过于笼统，必须拿到yarn build阶段的完整输出：

• 修改Jenkins配置，确保捕获Docker构建的所有stdout/stderr内容
• 或者在Dockerfile中替换构建命令为RUN yarn build --verbose，强制输出详细日志，以此确定是哪个页面/组件触发的失败

2. 严格对齐Node.js和Yarn版本 #

本地与Docker环境的Node/Yarn版本必须完全一致：

• 在Dockerfile开头明确指定基础镜像，锁定Node版本：

  FROM node:16.18.1
  

• 同步Yarn版本到本地的1.22.19，在Dockerfile中添加：

  RUN npm install -g yarn@1.22.19
  

3. 检查环境变量完整性 #

Next.js构建依赖的环境变量（如API地址、i18n配置等）在CI环境中可能缺失：

• 确认本地.env中的所有变量都通过Jenkins注入到了Docker构建环境
• 可在Dockerfile中添加RUN printenv命令，验证变量是否正常加载

4. 排查静态页面生成的资源/路径问题 #

本地与CI环境的路径差异常导致此类问题：

• 检查项目中是否存在硬编码的本地路径（如/Users/xxx/...），这类路径在Docker环境中不存在
• 确认所有静态资源（图片、字体等）都放在public目录下，引用路径遵循Next.js规范
• 检查next.config.js中的exportPathMap、getStaticProps/getStaticPaths逻辑，是否因CI环境数据缺失导致页面生成失败

5. 优化依赖安装与缓存策略 #

当前Dockerfile的清理步骤不够高效，且可能存在依赖安装不稳定问题：

• 调整Dockerfile步骤，利用Docker缓存提升构建稳定性：

  COPY package.json yarn.lock ./
  RUN yarn install --frozen-lockfile  # 锁定依赖版本，避免安装不一致的包
  COPY . .
  RUN rm -rf .next build
  RUN yarn build
  

• 若Jenkins网络不稳定，配置Yarn国内镜像源：

  RUN yarn config set registry https://registry.npmmirror.com
  

6. 修复依赖版本兼容性冲突 #

Next.js v10.1.3与部分依赖可能存在版本不兼容：

• 避免同时使用fast-sass-loader和sass-loader，两者存在冲突，建议只保留sass-loader，且降级到10.x版本（当前13.0.0版本与Next.js 10.1.3兼容性较差）
• 确认next-i18next@8.6.0与Next.js 10.1.3的兼容性，该版本组合本身无问题，但可尝试锁定更精确的版本号

7. 本地模拟CI构建流程 #

在本地模拟Docker的无缓存构建，排查是否是本地缓存掩盖了问题：

• 执行命令：rm -rf node_modules .next build && yarn cache clean --all && yarn install && yarn build
• 若本地也失败，说明问题出在项目本身；若本地正常，继续聚焦环境差异排查

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