React / 系统课时
常见部署故障排查
常见部署故障排查
本课建立一套从浏览器到数据库的固定排查顺序,帮助你快速定位白屏、刷新 404、跨域、接口超时、数据库连接失败和环境变量错误,并通过可重复的检查方法确认修复是否真正生效。
学习目标
- 按“前端资源→网关与接口→应用→数据库”的顺序缩小故障范围
- 能识别六类常见部署故障的典型现象与根因
- 使用命令和日志完成修复后的闭环验证
先按链路定位故障
部署故障不要从“重启服务”开始。先确认问题发生在哪一层:浏览器是否拿到入口文件,静态资源是否返回 200,前端路由是否被服务器正确回退,接口是否到达后端,后端是否能访问数据库。

先运行一次基础探测。将域名、接口地址和健康检查路径替换为实际值;动态时间和服务器地址可能不同。
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预期输出
[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。
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 可被任何访问者读取。
修复后的闭环验证
修复后至少完成四项验证:无缓存打开首页、直接刷新深层路由、执行一次跨域接口请求、查看应用与数据库日志是否仍有异常。只验证“服务进程存在”不能证明用户链路可用。
还应记录故障现象、根因、修复动作和验证结果。下次出现相同问题时,团队可以直接复用检查顺序,而不是重新猜测。