# 2.8 常见问题 FAQ

:::tip 概述
本页汇总快速入门阶段的高频问题。更多排错手段见 [11.10 故障排查手册](/zh/deploy/troubleshooting.html)。
:::

## 启动类

**Q：启动即退出，提示配置校验失败？**

启动是 fail-fast 的：JWT 密钥为空或过短、DSN 字段不完整都会直接退出。按提示修正 `config.yaml` 或对应 `APP_*` 环境变量。生产模式（`app.prod=true`）还会拒绝默认密钥、万能验证码与未关闭的生成器。

**Q：提示 Redis 连接失败？**

Redis 是可选依赖。cache.Init 探测失败会自动降级内存模式并打告警日志，服务照常启动。需要真实 Redis 时核对 `redis.default.address/pass`。

**Q：Windows 下 `make` 命令不可用？**

使用 `make.bat <目标>`，两套目标完全一致。

**Q：8000 端口被占用？**

改 `server.address`（如 `:8001`），或释放占用端口。注意同步改前端代理目标。

## 数据库类

**Q：连接被拒绝 / 访问被拒绝？**

确认 MySQL 已启动、账号密码与 `database.default` 一致、库已创建并导入种子脚本。

**Q：想换 PostgreSQL / SQL Server 怎么办？**

改 `database.default.driver` 与连接字段即可，代码零改动。已有数据用 `make migrator` 跨库搬迁，见 [7.6 数据库迁移工具](/zh/tools/db-migrate.html)。

**Q：物理删除报错被拦截？**

这是设计行为——一切删除走软删除（`del_flag=1`），物理删除被全局钩子拦截。定时清理等特殊场景用 `WithPhysicalDelete(ctx)` 显式放行。

## 前端类

**Q：`pnpm dev` 后页面接口全部 404/代理失败？**

后端未启动或端口不一致。确认 `/api/health` 可访问，并核对 `ui/.env.development` 的 `VITE_PROXY` 指向。

**Q：登录提示验证码错误？**

验证码有 300 秒有效期且一次性。开发调试可配置 `captcha.bypassCode` 万能码——但生产模式下非空万能码会被拒绝启动。

## 配置类

**Q：新增了配置键，`make check-config` 报不一致？**

新增键必须同步写入 `.env.example`。这是硬检查项，两者键集合必须一致。

**Q：环境变量设置了但不生效？**

覆盖规则：键名 = 配置路径大写、点换下划线、加 `APP_` 前缀；且**仅覆盖 YAML 中已存在的键**，空值视为未设置。例：`database.default.host` → `APP_DATABASE_DEFAULT_HOST`。

**Q：上传的文件访问不到？**

生产环境由 Nginx 直供 upload 目录，`file.domainUrl` 配置访问基址（不含 upload 段）。本地未配置域名时应用挂开发回退且封禁 temp 目录。详见 [7.2 上传配置详解](/zh/tools/upload-config.html)。