返回文档中心

常见问题

XYGo Admin 2025-02-20 165 次阅读

开发过程中常见问题的解答汇总

常见问题

启动相关

Q: 后端启动报 "database connection failed"

请检查：

  1. 数据库服务是否已启动
  2. config.yaml 中的数据库连接信息是否正确
  3. 数据库用户是否有访问权限
  4. 如果使用 PostgreSQL，确认连接字符串格式为 pgsql:user:pass@tcp(host:port)/dbname

Q: 前端启动报 "port 5173 is already in use"

端口被占用，可以修改 vite.config.ts 中的端口，或关闭占用端口的进程：

bash 复制代码 
# Windows
netstat -ano | findstr :5173
taskkill /PID <pid> /F

# Linux/Mac
lsof -i :5173
kill -9 <pid>

Q: gf gen dao 报错

确认 server/hack/config.yaml 中的数据库连接配置正确，且 GoFrame CLI 版本与项目匹配：

bash 复制代码 
gf version
# 建议 >= v2.7

开发相关

Q: 新增的接口 404

检查以下几点：

  1. API 定义文件中的 g.Meta tag 路径是否正确
  2. Controller 是否已在 cmd.go 中注册到对应路由组
  3. 后端是否已重启（Go 不支持热更新）

Q: 前端页面空白，控制台无报错

可能原因：

  1. 路由未正确配置，检查菜单数据中的 component 路径
  2. 动态路由未加载，确认用户角色有该菜单权限
  3. 组件文件路径大小写不匹配（Linux 区分大小写）

Q: 上传文件失败

  1. 检查 sys_config 表中 oss 分组的配置
  2. 确认上传目录有写入权限
  3. 检查文件大小是否超过限制
  4. 如使用云存储，确认 AccessKey 配置正确

部署相关

Q: 生产环境接口跨域

在 Nginx 中配置反向代理，将 API 请求转发到后端服务：

nginx 复制代码 
location /admin/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Q: WebSocket 连接失败

Nginx 需要额外配置 WebSocket 支持：

nginx 复制代码 
location /socket/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Q: 前端打包后页面刷新 404

项目默认使用 Hash 路由模式（URL 带 #），不会出现此问题。如果切换为 History 模式，需要在 Nginx 中配置：

nginx 复制代码 
location / {
    try_files $uri $uri/ /index.html;
}