张翔
7.2 KiB
7.2 KiB
前端白屏问题系统性调试报告
执行时间
- 开始时间: 2026-03-28 11:30
- 完成时间: 2026-03-28 11:35
- 总耗时: 5分钟
调试方法论
本次调试严格遵循**系统性调试(Systematic Debugging)**方法，按照四个阶段进行：
- Phase 1: Root Cause Investigation（根本原因调查）
- Phase 2: Pattern Analysis（模式分析）
- Phase 3: Hypothesis and Testing（假设与测试）
- Phase 4: Implementation（实施修复）
Phase 1: Root Cause Investigation
1.1 收集证据
检查前端服务器日志
tail -200 /tmp/admin-frontend-dev.log
结果: 日志显示Vite服务器已启动，但没有后续请求记录。
检查前端服务器进程
ps aux | grep -E "vite|node.*5173" | grep -v grep
结果: ❌ 关键发现 - 前端服务器进程不存在！
检查端口占用
netstat -an | grep 5173
结果: 端口5173没有被监听。
尝试访问前端
curl -s http://localhost:5173
结果: 无任何响应内容。
1.2 根本原因识别
根本原因: 前端开发服务器进程意外终止，导致页面无法访问。
证据链:
- ✅ Vite服务器日志显示曾启动成功
- ❌ 进程列表中没有Vite进程
- ❌ 端口5173未被监听
- ❌ HTTP请求无响应
结论: 前端白屏问题的根本原因是前端服务器未运行，而不是代码错误。
Phase 2: Pattern Analysis
2.1 分析服务器终止原因
可能的原因：
- 手动终止: 用户可能手动停止了服务器
- 后台进程管理: 使用
&后台运行可能导致进程被系统终止 - 终端会话问题: 终端会话断开可能导致后台进程终止
- 资源限制: 系统资源不足导致进程被杀
2.2 对比正常工作状态
正常状态:
- Vite进程运行中
- 端口5173被监听
- HTTP请求返回HTML内容
- 浏览器可以访问页面
异常状态:
- Vite进程不存在
- 端口未被监听
- HTTP请求无响应
- 浏览器显示白屏
Phase 3: Hypothesis and Testing
3.1 形成假设
假设: 如果重新启动前端服务器，页面将正常显示。
验证方法:
- 重新启动前端服务器（前台运行，避免后台进程问题）
- 使用Playwright测试验证页面是否正常
- 检查浏览器控制台是否有错误
3.2 测试执行
重新启动前端服务器
cd /Users/zhangxiang/Codes/Gitee/everything-is-suitable/everything-is-suitable-admin
npm run dev:local
结果: ✅ 服务器成功启动
VITE v7.3.1 development-local ready in 573 ms
➜ Local: http://localhost:5173/
➜ Network: http://192.168.3.169:5173/
验证服务器响应
curl -s http://localhost:5173 | head -20
结果: ✅ 返回正常HTML
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<script type="module" src="/@vite/client"></script>
<meta charset="UTF-8">
<link rel="icon" href="/favicon.ico">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Everything is Suitable Admin 管理系统</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
运行Playwright调试测试
创建了专门的调试测试文件 e2e/debug/debug-white-screen.spec.ts 来检查浏览器中的JavaScript错误。
测试结果: ✅ 测试通过
=== Console Messages ===
[debug] [vite] connecting...
[debug] [vite] connected.
[warning] [Vue Router warn]: No match found for location with path "/"
[log] 资源加载: http://localhost:5173/src/mocks/mock-interceptor.ts - 3 ms
[log] Mock interceptor installed for environment: development-local
[log] 路由跳转: / -> /login
[log] 首次绘制 FP: 420 ms
[log] 首次内容绘制 FCP: 432 ms
[log] 最大内容绘制 LCP: 624 ms
=== Page Errors ===
（无错误）
=== Body Text ===
系统管理登录记住我登 录用户名: admin / 密码: admin123
关键发现:
- ✅ 没有页面错误
- ✅ 页面内容正常显示（登录表单）
- ✅ 路由正常工作（从
/跳转到/login） - ✅ Mock拦截器正常安装
- ✅ 性能指标正常
Phase 4: Implementation
4.1 问题已解决
解决方案: 重新启动前端开发服务器。
验证结果:
- ✅ 前端服务器正常运行
- ✅ 页面可以正常访问
- ✅ 没有JavaScript错误
- ✅ 登录表单正常显示
- ✅ Mock功能正常工作
4.2 预防措施
为了避免将来出现类似问题，建议：
-
使用进程管理工具:
- 使用
pm2或nodemon管理开发服务器 - 避免使用
&后台运行
- 使用
-
添加健康检查脚本:
# health-check.sh if ! lsof -i :5173 > /dev/null; then echo "Frontend server is not running, starting..." cd /path/to/project && npm run dev:local fi -
使用Docker Compose:
- 将前端服务纳入Docker Compose管理
- 自动重启策略：
restart: unless-stopped
-
监控告警:
- 添加端口监控
- 服务不可用时发送告警
调试总结
调试成果
- ✅ 识别了根本原因：前端服务器未运行
- ✅ 验证了解决方案：重新启动服务器
- ✅ 确认了页面功能正常
- ✅ 创建了调试测试脚本用于未来问题排查
调试方法论验证
本次调试严格遵循系统性调试方法：
| 阶段 | 执行情况 | 结果 |
|---|---|---|
| Phase 1: Root Cause Investigation | ✅ 完成 | 发现服务器未运行 |
| Phase 2: Pattern Analysis | ✅ 完成 | 分析了进程终止原因 |
| Phase 3: Hypothesis and Testing | ✅ 完成 | 验证了重启服务器可解决问题 |
| Phase 4: Implementation | ✅ 完成 | 问题已解决并验证 |
关键经验
- 不要假设代码有问题: 白屏不一定是代码错误，可能是基础设施问题
- 检查基础环境: 在深入调试代码前，先验证服务是否正常运行
- 使用自动化测试: Playwright测试可以快速验证页面功能
- 系统性方法: 遵循系统性调试方法可以快速定位根本原因
后续建议
P0 - 立即处理
- 验证登录功能: 访问 http://localhost:5173 测试登录功能
- 运行E2E测试: 执行完整的E2E测试套件验证系统功能
P1 - 本周内完成
- 改进进程管理: 使用pm2或Docker管理开发服务器
- 添加健康检查: 实现自动化健康检查和告警
- 完善文档: 更新开发环境启动文档
P2 - 1个月内完成
- 优化开发环境: 统一开发环境配置和管理
- 建立监控体系: 实现服务监控和自动重启
附录
调试测试文件
相关文档
报告生成时间: 2026-03-28 11:35
报告生成者: 张翔 (全栈质量保障与效能工程师)
调试方法: Systematic Debugging