部署失败别慌：白屏、502、构建报错的排错指南

上线后白屏、502、构建失败、接口全挂怎么排查？按「构建期还是运行期、前端还是后端」分层定位，用浏览器 F12 和平台日志找到病根。

折腾鸭编辑部2026-08-27 发布2026-08-27 更新

登录后收藏

内容说明

折腾鸭可能通过推广链接获得佣金，但不会影响编辑结论，也不会增加你的支付价格。

按部署全流程走完，点下 Deploy——结果页面白屏、或者报 502。别急着删库重来，90% 的部署故障都能在 10 分钟内定位。这篇给你一套「分层排查法」。

一、先分清：构建期错误还是运行期错误

这是排错的第一刀，切对了方向就成功一半：

依赖装不上：日志里 npm ERR / pip 报版本冲突。多半是没提交 lock 文件（package-lock.json / requirements.txt），去补上重新 push。
没有 build / start 脚本：报 Missing script。package.json 的 scripts 里补上（复习部署全流程·四个坑）。
构建内存超限：免费套餐构建内存小，Next.js 大项目容易爆。本地先 npm run build 确认能过，再考虑精简依赖或升级套餐。

打开页面按 F12（手机 Chrome 可接电脑远程调试），看 Console 标签的红字：

Failed to load resource 404：JS/CSS 路径不对，常见于把首页写成绝对路径 /index.html 但实际部署在子路径。
XXX is not defined：环境变量没配。到平台 Environment Variables 里补上，补完必须重新部署才生效（复习环境变量与密钥安全）。
一长串框架报错（React hook 之类）：本地能跑线上报？先确认本地跑的是生产构建：npm run build && npm start，很多问题本地开发模式被掩盖。

意思是"网关活着，但你的后端进程没起来"。按顺序查三点：

启动命令对不对：平台用什么命令启动？很多平台默认 npm start，Python 项目要显式写（如 gunicorn main:app）。
端口对不对：平台靠环境变量 PORT 告诉你监听哪个端口，代码里必须写 process.env.PORT 或读 $PORT，写死 3000 就会 502。
进程是不是启动即崩：去平台的 Runtime Logs / Deploy Logs 看有没有启动时报错（连不上数据库、缺变量、语法错误），AI 生成代码最常见的崩因是"线上连不上数据库"——数据库地址、账号密码有没有配成生产值？

F12 → Network 标签，点开失败的请求看状态码：

定位到报错日志后，不用自己读。把完整报错堆栈复制给 Cursor / Claude，用这段提示词：

我的项目部署到 [平台] 后出现这个错误：[粘贴完整日志]。本地运行正常。请：1. 用大白话解释这个错误的根本原因；2. 给出具体修复步骤和要改的文件；3. 检查是否还有同类问题。

AI 读日志找病根的效率远超新手自己啃，但前提是你得先把日志找出来——所以上面的分层法依然是基本功。