Exam_registration/TROUBLESHOOTING.md

考试信息管理系统 - 常见问题修复指南

🔧 问题：首页显示 "Not Found"

问题描述

访问系统首页（http://localhost:8080）时显示 "Not Found" 错误。

原因分析

1. 前端未构建：项目缺少 frontend/dist 目录
2. 静态文件服务未配置：后端无法提供前端页面文件
3. SPA 路由未处理：Vue Router 的前端路由需要特殊配置

解决方案

方法一：使用快速启动脚本（推荐）

Windows PowerShell:

.\start.ps1

Windows CMD:

start.bat

脚本会自动：

• ✅ 检查 Go 和 Node.js 环境
• ✅ 安装前端依赖
• ✅ 构建前端生产版本
• ✅ 启动后端服务
• ✅ 配置静态文件服务

方法二：手动修复

步骤 1：构建前端

# 进入前端目录
cd frontend

# 安装依赖（首次需要）
npm install

# 构建生产版本
npm run build

构建成功后会生成 frontend/dist 目录。

步骤 2：验证构建结果

# 检查 dist 目录是否存在
dir dist

# 应该看到：
# index.html
# assets/
# static/

步骤 3：重启后端服务

# 停止当前运行的服务（Ctrl+C）

# 重新启动
go run cmd/main.go

步骤 4：访问系统

打开浏览器访问：http://localhost:8080

应该能看到登录页面。

---

📋 完整排查清单

1. 检查前端是否已构建

# PowerShell
Test-Path frontend\dist

# 或 CMD
dir frontend\dist

如果返回 False 或提示目录不存在，需要构建前端。

2. 检查后端日志

启动后端时应该看到：

Server started on port 8080

如果没有此输出，查看错误信息并解决。

3. 检查数据库连接

确保 config/config.yaml 中的数据库配置正确：

database:
  host: localhost
  port: 3306
  user: root
  password: YOUR_PASSWORD  # ⚠️ 修改为你的密码
  dbname: exam_registration

4. 检查浏览器控制台

按 F12 打开开发者工具，查看：

• Network 标签：是否有 404 错误
• Console 标签：是否有 JavaScript 错误

5. 清除浏览器缓存

有时浏览器缓存会导致旧版本问题：

• Ctrl+Shift+Delete 清除缓存
• 或使用无痕模式访问

---

🎯 其他常见问题

问题：npm install 失败

错误信息：

npm ERR! code ECONNREFUSED

解决方案：

1. 检查网络连接
2. 切换 npm 镜像源：

npm config set registry https://registry.npmmirror.com
npm install

问题：前端构建失败

错误信息：

Error: Cannot find module 'xxx'

解决方案：

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

问题：后端启动失败 - 端口被占用

错误信息：

bind: address already in use

解决方案：

方案 1：关闭占用端口的进程

# Windows PowerShell
netstat -ano | findstr :8080
taskkill /PID <进程 PID> /F

方案 2：修改端口 编辑 config/config.yaml:

server:
  port: 8081  # 改为其他端口

问题：登录后仍然 404

可能原因：

• Token 未正确保存
• 路由守卫配置问题

解决方案：

1. 检查浏览器 Local Storage 是否有 token
2. 检查浏览器 Console 是否有错误
3. 尝试清除缓存重新登录

---

🆘 获取帮助

如果以上方法都无法解决问题：

1. 查看完整日志

   # 启动时查看详细日志
   go run cmd/main.go 2>&1 | tee startup.log
   

2. 检查系统要求

   • Go 1.21+
   • Node.js 18+
   • MySQL 8.0+

3. 重新部署

   # 删除并重新克隆项目
   # 或备份数据后重新执行初始化流程
   

4. 联系技术支持

   • 提供完整的错误日志
   • 说明操作系统版本
   • 说明已尝试的解决方法

---

✅ 验证成功标准

系统正常运行的标志：

• ✅ 后端服务启动，显示 "Server started on port 8080"
• ✅ 访问 http://localhost:8080 显示登录页面
• ✅ 可以使用 admin/admin123 登录
• ✅ 登录后显示系统首页（Dashboard）
• ✅ 导航栏各菜单可以正常切换
• ✅ API 请求正常（无 404 错误）

---

祝您使用愉快！ 🎉