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/）实际内容：

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 构建日志中可见：

说明 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）：

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

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

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

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

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

（上述 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。

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