主题
前端排故方法论：五步排查法，从网络上查起
"清一下浏览器缓存试试"是 IT 圈最常用的敷衍话术，但真凶 95% 在服务端。从链路最前端（DNS）往后查，一次只改一处，改完立刻验证——这是唯一正确的排查姿势。
| 字段 | 内容 |
|---|---|
| 标签 | #排故方法论 #前端 #调试 #DNS #nginx #五步排查法 #避坑 |
| 踩坑日期 | 2026-07-18（三次推给"浏览器缓存"） |
| 严重程度 | 🔴 中 |
事故经过
三次掉线，三次推给缓存
那天小雅 APP 前端页面掉了三次：
第一次：风哥说"页面打不开了"。我说"清一下浏览器缓存试试？" → 没好。
第二次：我说"用无痕模式试试？" → 没好。
第三次：我说"换个浏览器？" → 没好。
风哥发火了："你老让我清缓存，能不能正经查一下到底哪里坏了？"
我停下来认真排查：
- 第一次：DNS 问题，域名没指向正确的 IP
- 第二次：nginx 问题，
sites-enabled里少了 symlink（改了配置没做链接） - 第三次：证书过期，HTTPS 握手直接失败
三次全是服务端的问题，和浏览器缓存八竿子打不着。
根因分析
为什么"清缓存"成了 IT 圈万能答案
- 操作简单，不需要思考 — 不用查日志、不用 SSH，"你那边试一下"
- 有时候确实有效 — 前端更新了 JS/CSS 但用户浏览器缓存了旧版本，清缓存能解决
- 心理上的"问题隔离" — "你那边的问题"比"我不知道哪出了问题"好听
但实际数据：真正由浏览器缓存导致的问题 < 5%。绝大多数"前端打不开"的根因在服务端。
正确的排查心智模型
text
用户浏览器
↓
DNS 解析 ← ① 第一步查这里
↓
网络层 ← ② 网络连通性
↓
服务器端口 ← ③ 端口有没有在监听
↓
Web 服务 ← ④ 服务状态 + 配置
↓
API网关 ← ⑤ API 直测
↓
前端功能 ← ⑥ 最后才查前端原则：从链路最前端往后查，每一层确认正常才往下走。
反过来（从浏览器往后猜）的问题是：你无法排除上游的干扰。DNS 不通 → 后面全白查。
解决方案：五步排查法
第一步：DNS 解析
域名能解析出正确的 IP 吗？
bash
# 服务器上查 DNS 记录
dig +short www.sirenzhuli.cn
# 预期: 124.222.126.171
# 和已知 IP 对比
dig +short chat.sirenzhuli.cn
dig +short fayan.sirenzhuli.cn
# 如果怀疑 DNS 传播问题，对比多个 DNS 服务器
dig +short www.sirenzhuli.cn @8.8.8.8 # Google DNS
dig +short www.sirenzhuli.cn @1.1.1.1 # Cloudflare| 现象 | 可能原因 | 动作 |
|---|---|---|
| 解析不到（NXDOMAIN） | 域名没配置 A 记录 | 去 DNS 管理后台加 A 记录 |
| 解析到旧 IP | 刚改了 DNS 但 TTL 没到期 | 等待 TTL 过期，或客户端执行 ipconfig /flushdns |
| 部分区域能解析 | DNS 传播延迟 | 等 5-30 分钟 |
第二步：端口监听
服务器在正确的端口上监听吗？
bash
# 查看所有监听端口
sudo ss -tlnp
# 只看关键端口
sudo ss -tlnp | grep -E ":(80|443|8444|8898|13000)\s"
# 外部测试端口是否可达
nc -zv 124.222.126.171 80
nc -zv 124.222.126.171 443正常输出示例：
text
LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",pid=1234,fd=6))
LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=1234,fd=7))如果不在这里 → nginx 没启动，或配置有误导致端口没开。
第三步：服务状态
Web 服务在正常运行吗？
bash
# nginx
sudo systemctl status nginx
sudo nginx -t # 配置语法检查
# 后端服务
sudo systemctl status chat-server
sudo journalctl -u chat-server --since "10 min ago" -n 50必查项：
Active: active (running)✅Active: failed→journalctl看日志Active: activating (start)→ 可能卡住了- 日志里有
ERROR、Traceback、Connection refused→ 定位具体问题
第四步：API 直测（绕过前端）
不依赖前端，直接请求 API：能正常响应吗？
bash
# HTTP 接口
curl -v http://localhost:8898/api/health
# HTTPS
curl -v https://chat.sirenzhuli.cn/api/health
# 需要认证的接口
curl -H "Authorization: Bearer <token>" https://www.sirenzhuli.cn/api/user
# 只看状态码
curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8898/api/healthHTTP 状态码速查：
| 状态码 | 含义 | 查什么 |
|---|---|---|
| 200 | 正常 ✅ | — |
| 301/302 | 重定向 | nginx 转发规则 |
| 403 | 禁止访问 | 权限 / 防火墙 / CORS |
| 404 | 不存在 | API 路由 / nginx location |
| 500 | 服务内部错误 | 后端日志（journalctl） |
| 502 | 网关错误 | 后端服务是否挂了 |
| 504 | 网关超时 | 后端响应太慢/死循环 |
| 000 | 完全不通 | 端口没开/DNS 没解析到 |
第五步：前端功能（最后才查）
前四步全通了，再看前端
bash
# 浏览器 F12 → Network 标签
# - 哪些请求是红色的（失败）？
# - 失败的请求返回了什么状态码？
# - Console 标签有没有 JS 报错？
# 静态资源是否可访问？
curl -I https://www.sirenzhuli.cn/static/js/app.js
curl -I https://fayan.sirenzhuli.cn/assets/index.js只有前四步全部正常，才能把问题定位到前端代码本身。
一键排故脚本（五合一）
bash
#!/bin/bash
# 前端掉线排故脚本
# 用法: bash debug-frontend.sh
DOMAIN="chat.sirenzhuli.cn"
API_PATH="/api/health"
SERVER="124.222.126.171"
echo "========================================="
echo " 前端排故五步法 - $DOMAIN"
echo "========================================="
echo -e "\n[1/5] DNS 解析"
echo " 预期: $SERVER"
echo " 结果: $(dig +short $DOMAIN | head -1)"
echo -e "\n[2/5] 端口监听"
ssh root@$SERVER "ss -tlnp | grep -E ':(80|443)\b'" 2>/dev/null || echo " SSH 连不上，跳过"
echo -e "\n[3/5] 服务状态"
ssh root@$SERVER "systemctl is-active nginx" 2>/dev/null || echo " 跳过"
echo -e "\n[4/5] API 直测"
echo " curl -w '%{http_code}' https://$DOMAIN$API_PATH"
HTTP_CODE=$(curl -o /dev/null -s -w "%{http_code}" "https://$DOMAIN$API_PATH" 2>/dev/null)
echo " → HTTP $HTTP_CODE"
echo -e "\n[5/5] 前端资源"
HTTP_CODE=$(curl -o /dev/null -s -w "%{http_code}" "https://$DOMAIN/" 2>/dev/null)
echo " → 首页: HTTP $HTTP_CODE"
echo -e "\n========================================="
echo " 排查完成"
echo "========================================="预防措施
排故铁律（贴在显示器上）
- 禁止说"清缓存" — 除非你完成了 DNS→端口→服务→API 四步检查并且全部正常
- 一次只改一处，改完立刻验证 — 改了 DNS 就验证 DNS，别顺手改 DNS+nginx 然后不知道哪个生效了
- 从链路最前端往后查 — DNS 不通，后面全白看。端口没开，服务状态也不用看
- 日志优先于猜测 —
tail -f比"我觉得"靠谱一万倍
常见问题快速定位表
| 用户报告 | 最可能根因 | 先查什么 | 排故起点 |
|---|---|---|---|
| "完全打不开，ERR_CONNECTION_REFUSED" | 服务器宕机 / nginx 挂了 | ping + ssh | 第二步 |
| "完全打不开，ERR_NAME_NOT_RESOLVED" | DNS 解析失败 | dig + nslookup | 第一步 |
| "页面一直转圈、超时" | 后端服务挂了 | curl API + journalctl | 第三步 |
| "能打开页面但报错" | 特定 API 异常 | Network 标签看哪个请求红了 | 第四步 |
| "HTTPS 页面打不开、不安全" | 证书过期 / 路径错误 | openssl s_client | 第二/三步 |
| "输入框点不了、点提交没反应" | 前端 JS 报错 | Console 标签 | 第五步 |
| "图片/样式加载不出来" | 静态资源路径 | nginx location 配置 | 第四步 |
出问题时先问自己三个问题
text
① 上次正常能用是什么时候？
② 那个时间点之后改了什么东西？
③ 改了什么就查什么，别瞎猜。90% 的故障都和最近一次变更有关。找不到变更记录 → git log --since="2 days ago" 或检查 nginx 配置的修改时间：ls -lt /etc/nginx/sites-available/。
关联知识点
- nginx 配置不生效排故 — symlink 陷阱与 reload 指令
- SSL 证书迁移实战 — 证书过期导致 HTTPS 不通
- 计算机网络故障排查 — DNS 和端口检测工具详解
- 日志与排故 — journalctl 和
tail -f - Linux 进程管理 — systemctl 排查服务状态
🎯 本章要点
- 从外到内排查：DNS解析→端口监听→服务进程→API接口→前端功能
- 一次只改一处，验证后再改下一处，避免盲目操作
加载练习题中...