# 2.8 常见问题 FAQ

:::tip 概述
本节收录环境搭建与首次运行阶段最常遇到的问题。更多排障条目见 [附录 A 常见问题汇总](../appendix/faq) 与 [11.10 故障排查手册](../deploy/troubleshooting)。
:::

## 环境与编译

### Q：`go build` 报 `go.mod requires go >= 1.27.2`

go.mod 声明的版本高于本机 Go 版本。升级 Go 到 1.27.2+，或使用 go env 切换已安装的高版本。

### Q：依赖下载缓慢或失败

```sh
go env -w GOPROXY=https://goproxy.cn,direct
go mod tidy
```

### Q：前端 `pnpm install` 报引擎不匹配

检查 Node 版本（要求 18+）。部分依赖对 pnpm 版本敏感，可升级 pnpm 后重装：

```sh
npm install -g pnpm@latest
pnpm install
```

## 数据库

### Q：连接 MySQL 报错 `Unknown database`

库名是 `easygoadmin.goframe.elevue`（含点号），确认已建库且拼写一致；建库语句见 [2.4 数据库初始化](./database-init)。

### Q：切换数据库类型后启动报驱动错误

确认 `database.default.type` 与 `link` 前缀一致（如 `type: "pgsql"` 且 `link: "pgsql:..."`）。五驱动已预注册，无需改代码。

### Q：导入脚本后缺少唯一索引

`document/` 各方言脚本中 MySQL 版为规范基准，后四份待人工校对。以 MySQL 版核对 `uk_*` 唯一索引清单（应有 13 个），缺失需人工补齐——唯一索引是并发唯一性的最终保证。

## 启动与运行

### Q：启动报端口占用

```sh
netstat -ano | findstr ":8000" | findstr LISTENING
taskkill /F /PID <pid>
```

或修改 `manifest/config/config.yaml` 的 `server.address`。

### Q：启动日志出现 `IdentityLoader`/`LogSink` 告警

中间件依赖未接线（不阻断启动）。通常原因：`internal/cmd` 缺少对 `internal/logic` 的空白导入，或 init 注册被误删。表现为：不加载角色权限 / 跳过租户校验 / 操作日志不落库。

### Q：日志提示 Redis 连接失败并降级

服务以进程内存缓存运行（`UsingMemory()=true`）。限流计数、任务执行锁、在线用户、JWT 黑名单、验证码全部退化单机语义。检查 Redis 地址/密码，确认后可通过 `/api/cache/info` 验证 `mode` 是否恢复为 `redis`。

### Q：接口返回 `{"code":401}` 

令牌缺失、过期或已被拉黑。重新登录获取新令牌；带 refresh_token 走 `POST /api/oauth2/token` 轮换。注意登录响应字段是 `access_token`（下划线）。

### Q：接口返回 `{"code":403}`

权限不足：确认 gmeta `permission` 标签对应节点已在「菜单管理」存在，且已在「角色管理」为当前角色勾选。超管（ROLE_SUPER_ADMIN）不受限。

### Q：接口返回 `{"code":429}`

触发限流（默认普通接口 120 次/分钟/IP/路径；登录/验证码/令牌兑换 10 次/分钟/IP）。等待窗口过期或调整 `rateLimit.*` 配置。

### Q：写操作被拒绝并提示"演示环境，禁止操作!"

`app.demo: true` 时拦截全部写操作（读操作与公开白名单放行）。本地开发改回 `false` 并重启。

### Q：验证码图片不显示

检查 `/api/captcha` 是否 200；字体文件 `resource/static/fonts/Vera.ttf` 缺失会降级 SVG 渲染（仍可用）；若被限流（认证入口 10 次/分钟）等待窗口过期。

### Q：登录报"验证码错误"

开发环境可在验证码栏直接填配置中的 `captcha.bypassCode`（默认 618618）免校验；生产环境该值应留空。注意验证码为一次性校验（命中即删）。

## 前端

### Q：登录成功但刷新页面回到登录页

确认后端返回的令牌字段读取的是 `data.access_token`；检查浏览器 localStorage 是否被拦截清除；确认系统时间正常（令牌 exp 校验）。

### Q：页面菜单为空

菜单按角色权限动态生成。在「角色管理 → 权限」为角色勾选菜单节点；超管返回全量菜单。也可能是 `getUser` 接口 401——检查令牌。

### Q：接口 404

本项目全部路由统一 `/api` 前缀且**无 `/v1` 版本段**。`/api/v1/user/page` 形式会 404，正确为 `/api/user/page`。