React / 系统课时

常见部署故障排查

常见部署故障排查

本课建立一套从浏览器到数据库的固定排查顺序,帮助你快速定位白屏、刷新 404、跨域、接口超时、数据库连接失败和环境变量错误,并通过可重复的检查方法确认修复是否真正生效。

学习目标

  • 按“前端资源→网关与接口→应用→数据库”的顺序缩小故障范围
  • 能识别六类常见部署故障的典型现象与根因
  • 使用命令和日志完成修复后的闭环验证

先按链路定位故障

部署故障不要从“重启服务”开始。先确认问题发生在哪一层:浏览器是否拿到入口文件,静态资源是否返回 200,前端路由是否被服务器正确回退,接口是否到达后端,后端是否能访问数据库。

部署故障分层排查流程

先运行一次基础探测。将域名、接口地址和健康检查路径替换为实际值;动态时间和服务器地址可能不同。

bash
set -euo pipefail

WEB_URL="https://example.com"
API_URL="https://example.com/api/health"

echo "[1] 首页状态"
curl -sS -o /dev/null -w "%{http_code}\n" "$WEB_URL"

echo "[2] API 状态"
curl -sS -o /dev/null -w "%{http_code}\n" "$API_URL"

echo "[3] API 响应"
curl -sS "$API_URL"
echo

预期输出

text
[1] 首页状态
200
[2] API 状态
200
[3] API 响应
{"status":"ok"}

若首页失败,优先检查 DNS、TLS、Nginx 和静态文件;若首页成功但 API 失败,再检查反向代理、后端日志、超时和数据库。实际健康响应字段应以项目实现为准。

白屏与路由刷新失败

白屏通常不是“React 没启动”,而是入口文件引用的 JS 或 CSS 路径错误、资源未上传完整,或构建时使用了错误的基础路径。打开浏览器开发者工具,先看 Console,再看 Network 中是否出现 404、MIME 类型错误或脚本执行异常。

单页应用刷新子路由出现 404,说明服务器把 /users/1 当作真实文件查找。Nginx 需要在找不到静态文件时回退到 index.html。

nginx
server {
    listen 80;
    server_name example.com;
    root /var/www/app;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_connect_timeout 5s;
        proxy_read_timeout 30s;
    }
}

该配置生效后,静态资源仍按真实路径返回,未知前端路由则交给 React Router。使用 nginx -t 验证语法,再重新加载 Nginx,并分别访问首页和一个深层路由确认结果。

跨域与接口超时

浏览器提示 CORS 时,先确认请求是否跨域,再检查响应中是否由后端或网关统一返回 Access-Control-Allow-Origin。携带 Cookie 时不能同时使用通配符来源,还要允许凭证,并正确处理 OPTIONS 预检请求。

接口超时要区分连接超时和读取超时。连接超时多与目标地址、端口、防火墙或服务未监听有关;读取超时说明请求已到达后端,但业务、外部依赖或 SQL 执行过慢。对照同一请求的网关日志、应用日志和数据库慢查询时间,才能找到真正阻塞点。

数据库连接与环境变量

数据库错误先检查主机、端口、库名、账号和网络连通性,再检查连接池是否耗尽。若只有发布后失败,重点核对生产环境变量是否实际注入,以及变量名是否与代码读取名称完全一致。

前端环境变量通常在构建时写入产物,修改服务器变量后必须重新构建;后端变量多在进程启动时读取,修改后需要重启服务。不要把数据库密码、令牌或私钥写进前端变量,因为构建后的 JS 可被任何访问者读取。

修复后的闭环验证

修复后至少完成四项验证:无缓存打开首页、直接刷新深层路由、执行一次跨域接口请求、查看应用与数据库日志是否仍有异常。只验证“服务进程存在”不能证明用户链路可用。

还应记录故障现象、根因、修复动作和验证结果。下次出现相同问题时,团队可以直接复用检查顺序,而不是重新猜测。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

常见部署故障排查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通