Jenkins发布后Nginx页面404与构建OOM解决方案

一、问题描述

1.1 现象

• 正常分支（例如 release-xxx，对应本地某目录如 /path/to/release-project）通过 Jenkins 发布后，所有页面正常显示。
• 异常分支（例如 test、feature-xxx，对应本地某目录如 /path/to/your-project）通过 Jenkins 发布后，所有页面显示 404。
• 访问路径一致，例如：https://<UAT 域名>/<应用路径>/package-community/pages/pgc?id=xxx（如 https://example-uat.com/mini-app-h5/package-community/pages/pgc?id=xxx）。
• 404 页面显示为：404 Not Found nginx/1.29.0（即 nginx 直接返回的 404，非前端渲染的错误页）。

1.2 环境与前提

• 两套发布流程一致（同一 Jenkins Pipeline、同一 Dockerfile 设计）。
• 部署环境一致（同一 UAT 域名、同一访问路径）。
• 异常分支相比正常分支主要多了 新增分包目录（例如 src/package-service/）及相关分包配置。

二、排查过程

2.1 配置与代码对比

结论：路由 base、nginx 配置、依赖一致，不是配置错误导致的 404；两分支的差异主要在业务代码（尤其是新增分包）。

2.2 Jenkins 构建日志对比

• 正常分支构建：分支名如 release-xxx，commit 不同；COPY . . 与 RUN yarn build:dev 多为 CACHED。
• 异常分支构建：分支名如 test、feature-xxx，commit 不同；同样存在 CACHED 情况。

初步怀疑：Docker 层缓存可能导致异常分支镜像使用了“错误历史”的构建产物。
措施：在异常分支流水线中为 docker build 增加 --no-cache。
结果：加 --no-cache 后 404 现象依旧，说明问题不在“误用旧缓存”，而在本次构建产物本身。

2.3 访问路径与 404 类型确认

• 确认两套访问路径一致（同一 URL 格式）。
• 确认 404 为 nginx 直接返回（页面显示 404 Not Found nginx/1.29.0），即 服务端 404，而非前端路由或接口报错后渲染的“404 页”。

结论：问题在 nginx 找不到要响应的资源（缺文件或路径不对），需从镜像内文件和 nginx 配置入手。

2.4 构建产物验收（Dockerfile 内 ls）

在 Dockerfile 的 RUN yarn build:${BUILD_ENV} 后增加“验收”命令，在 Jenkins 构建日志中查看 H5 构建输出目录（如 dist/build/h5/）实际内容：

RUN yarn build:${BUILD_ENV} && \
    echo "==== dist/build/h5 结构 ====" && \
    ls -la /app/dist/build/h5/ && \
    ...

Jenkins 日志结果（举例）：

• dist/build/h5/ 下仅有：若干 .txt、第三方脚本（如 jweixin-xxx.js、vconsole.min.js）、nginx/ 等。
• 没有 index.html，也没有 assets/ 目录。
• 若存在子目录（如 dist/build/h5/<应用路径>/）→ 可根据实际情况判断是否为“子目录导致 COPY 路径错位”；本例中 无此子目录，说明并非路径错位。

结论：构建并未完整完成，镜像里缺少 H5 入口和静态资源，nginx 自然 404。

2.5 构建过程 OOM 与“假成功”

同一段 Jenkins 构建日志中可见：

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

说明 yarn build:dev（或 yarn build:prod）在 Docker 内执行时发生了 Node 堆内存不足（OOM），构建进程崩溃，未生成完整 index.html 和 assets/。

但该次 Jenkins 构建仍然显示 “构建成功”，原因在于：

• OOM 发生在 yarn 启动的子进程（如 node scripts/build.js → uni build）中。
• 子进程异常退出时，退出码有时未正确传递到 yarn，yarn 仍以 0 退出。
• Shell 认为 yarn build:xxx 成功，继续执行后面的 echo、ls 等，整条 RUN 退出码为 0，Docker 构建“成功”，镜像被推送。
• 镜像内实际只有 public 拷贝或部分产物，没有 index.html，部署后 nginx 返回 404。

结论：异常分支因构建时 OOM 导致产物不完整，又因子进程退出码未正确传递而出现“构建成功但镜像缺文件”的假成功。

2.6 为何正常分支正常、异常分支异常

• 正常分支：无新增大型分包，包与代码量较少，构建内存占用在默认 Node 堆上限内，能完整跑完，镜像内存在 index.html 和 assets/，nginx 正常服务。
• 异常分支：新增分包目录（如 src/package-service/）及关联分包，构建时解析、打包、代码分割量明显增加，在 Jenkins Docker 默认内存下更容易触及 Node 默认堆上限（约 1.4～2GB），触发 OOM，导致产物不完整 → 404。

三、根因总结

四、解决方案

4.1 修改内容（Dockerfile）

在项目 Dockerfile 的构建阶段做两处修改：

1. 提高 Node 堆内存上限，避免 OOM

在 RUN yarn build:${BUILD_ENV} 之前增加（数值可按项目规模调整，如 8192 表示 8GB）：

ENV NODE_OPTIONS=--max-old-space-size=8192

使 Node 最多使用 8GB 堆内存，满足含新增分包的构建需求。

2. 构建产物校验，避免推送不完整镜像

在构建命令后增加对 H5 入口文件（如 index.html）的检查，若不存在则令本层失败（路径需与项目实际输出一致，如 dist/build/h5/）：

RUN yarn build:${BUILD_ENV} && \
    echo "==== dist/build/h5 结构 ====" && \
    ls -la /app/dist/build/h5/ && \
    (ls -la /app/dist/build/h5/<应用路径>/ 2>/dev/null || echo "无子目录") && \
    test -f /app/dist/build/h5/index.html || (echo "Build failed: index.html not found (possible OOM)" && exit 1)

这样一旦 OOM 导致未生成 index.html，Docker 构建会失败，不会再把缺页面的镜像推出去。

4.2 Dockerfile 片段（构建阶段）举例

# 构建项目（支持通过 ARG 传递构建环境）
# 提高 Node 堆内存上限，避免 Jenkins 构建时 OOM（分包较多的分支）
ARG BUILD_ENV=prod
ENV NODE_OPTIONS=--max-old-space-size=8192
RUN yarn build:${BUILD_ENV} && \
    echo "==== dist/build/h5 结构 ====" && \
    ls -la /app/dist/build/h5/ && \
    (ls -la /app/dist/build/h5/mini-app-h5/ 2>/dev/null || echo "无 mini-app-h5 子目录") && \
    test -f /app/dist/build/h5/index.html || (echo "Build failed: index.html not found (possible OOM)" && exit 1)

（上述 mini-app-h5、dist/build/h5 等请按项目实际 应用路径 和 构建输出目录 替换。）

4.3 若仍 OOM 可进一步

• 将 8192 调整为 12288（12GB）或按机器能力适当提高。
• 为 Jenkins 执行 Docker 的节点/容器增加内存。
• 确认构建环境使用 Node 14+，且无其他进程占用过多内存。

五、验证与后续建议

5.1 验证步骤

1. 提交并推送上述 Dockerfile 修改，使用 异常分支（如 test、feature-xxx）触发 Jenkins 构建。
2. 查看构建日志：
   • 若构建成功，应能看到 ==== dist/build/h5 结构 ==== 下列出 index.html 和 assets/。
   • 若仍 OOM，会先出现 FATAL ERROR: ... heap out of memory，随后 test -f ... index.html 失败，构建失败，不会推送镜像。
3. 对成功构建的镜像进行部署，再次访问 实际访问地址（如 https://<UAT 域名>/<应用路径>/package-community/pages/pgc?id=xxx），确认页面正常、无 nginx 404。

5.2 后续建议

• 保留构建产物验收：便于日后排查类似“构建假成功”问题；若不再需要，可去掉 echo/ls，仅保留 test -f ... index.html || exit 1。
• 区分 404 类型：线上遇 404 时，用浏览器 DevTools → Network 看入口 HTML 的 HTTP 状态码；若为 200 而页面仍显示 404，多为前端或接口逻辑，与本次 nginx/镜像问题无关。
• 大分支构建：新增大型分包或大量页面时，可提前在 Dockerfile 中适当提高 NODE_OPTIONS=--max-old-space-size，避免再次 OOM。

六、时间线与关键结论速查

到此这篇关于Jenkins发布后Nginx页面404与构建OOM解决方案的文章就介绍到这了,更多相关Jenkins发布后页面404内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！