部署后白屏、502 或构建失败：先找到故障在哪一层

先别重装，也别让AI把配置一遍遍改掉。目标是把“网站不正常”变成可验证的问题：哪条请求、什么时候、哪个版本、在哪一层失败。本文是排查路径，不承诺固定时间解决，更不把所有故障归成同一个原因。

先做三件不会覆盖业务的事

1. 记下现场：访问路径、时间与时区、复现步骤、部署版本、错误码；区分所有用户还是某台设备受影响。
2. 保留上一可用版本：确认回退入口和备份状态，不先清空日志、不覆盖唯一配置副本。
3. 划定权限：只读检查通常可先做；重启、配置覆盖、数据库迁移和回退需由有权限的维护者按现有流程处理。

一、构建没有完成：先看首个相关错误

进入部署平台的构建记录，确认使用的提交、命令、运行时和退出码。找首个与失败相关的错误，后面的连锁报错不一定是根因。与上一次成功版本比较锁文件、依赖、环境变量名称和资源限制；不要在聊天中打印变量值。开发模式可访问不代表生产构建成功。

交给维护者的证据是：失败阶段、命令、运行时版本及脱敏错误上下文。若要复现，在隔离环境按同一条件进行，不在生产机随意更新全部依赖来碰运气。

二、构建成功但页面白屏：看浏览器实际请求

电脑上打开开发者工具的 Network 和 Console，再复现该页面。先确认主文档、脚本、样式和API各自返回什么；手机端可先记录截图和具体路径，交给有条件连接调试的维护者。控制台含错误不等于该错误一定导致白屏，要结合请求和发生时间判断。

• 主文档失败：先按HTTP状态与服务端日志排查，不先改前端样式。
• 脚本或样式404：核对请求路径、部署产物和缓存是否对应同一版本，不直接删全部存储。
• 脚本运行异常：保留错误堆栈、文件和行号，结合当前代码定位；不能凭“undefined”就断言缺环境变量。
• API 401/403：核对登录状态和接口权限，不靠放宽全部鉴权修复。
• API 500：记录请求时间和关联ID，到服务端查对应错误；响应不能包含生产凭据。

三、502：沿网关找到真正的上游

MDN将502定义为网关或代理收到无效的上游响应，不只是“后端没启动”。先在网关日志中确认出错请求和上游，再由维护者检查实际进程状态、监听地址、端口、协议及应用启动日志。按架构继续核对容器网络、代理配置或外部依赖，不开放所有端口试错。

若页面间歇出错，保留成功与失败的时间样本；没有日志或资源证据前，不把它直接写成并发不足。超时和连接拒绝也不能仅按页面文案混为一谈。

四、应用已运行：检查业务依赖

按失败操作核对数据库、缓存、上传目录、队列及外部服务状态。查看错误说明和最小必要日志，不导出整库供AI“看看”。HTTPS失败查域名、证书与时间；跨域失败查具体请求及服务规则，不能用关闭证书校验、允许任意跨域或公开敏感接口作为长期修复。

复制这份脱敏求助模板

• 故障开始时间与时区：
• 影响页面/操作；哪些路径仍正常：
• 部署版本/提交；上一次正常版本：
• 最短复现步骤：
• 主文档、资源和API分别返回的状态：
• 首个相关错误与脱敏日志上下文：
• 最近改了什么；已经检查什么：
• 允许的操作范围；备份与回退入口是否可用：

发送前去掉Authorization、Cookie、Token、密码、连接串及个人数据。必要时只给变量名、不给值；截图同样要遮敏。模板是为了定位问题，不是授权接收方任意重装或改库。

修复后怎样确认没有只修好首页

1. 复测原步骤及原请求，确认预期页面、资源和数据正常，而不只看HTTP 200。
2. 检查相邻关键路径：登录、详情、表单、图片或业务接口，按网站实际功能选择。
3. 确认部署版本与资源一致，日志不再重复同一故障，后台任务按预期运行。
4. 记录修改、结果和回退方式；无效修改先撤回再验证下一假设，避免积累未知配置。

• 分清代码推送与部署完成
• 日志与环境变量的秘密保护
• 恢复后怎样设置监控与告警

来源与核对范围

MDN：502 Bad Gateway支持本页的状态码定义；具体故障路径和验收清单为本站编辑建议。

折腾鸭编辑部于 2026-10-03 核对公开资料；未访问读者服务器、执行配置修改或验证其故障恢复，不含推广链接。