常见问题排查
这页不是“把所有知识点重新讲一遍”。
它的目标更像一个排错索引：当你已经遇到某个现象时，先在这里判断应该去哪个方向查。
先按现象找方向
Section titled “先按现象找方向”我连第一段响应都跑不出来
Section titled “我连第一段响应都跑不出来”先看：
常见原因：
- 依赖没加对
- 端口访问错了
- 程序启动后立即退出
Feat Cloud 启动了，但控制器不生效
Section titled “Feat Cloud 启动了，但控制器不生效”优先看：
最常见原因：
- 控制器没被扫描到
- 注解处理没有正确触发
- 路径理解错了，访问的不是最终映射 URL
能启动，但访问接口是 404
Section titled “能启动，但访问接口是 404”优先检查：
- 路由路径是否与你访问的 URL 完全一致
- 你用的是
Controller路径还是Router路径 - 修改代码后是否真的重新编译了
如果是 Feat Core 路由问题，看 Router 路由组件。
如果是 Feat Cloud 控制器问题，看 Controller 开发实践。
请求很慢，或者一个慢请求会拖住其他请求
Section titled “请求很慢，或者一个慢请求会拖住其他请求”优先看：
先不要一上来就怀疑框架本身。
很多时候只是你把耗时逻辑直接塞进了同步处理流程里。
想改端口、线程数、上传大小，但不知道该从哪开始
Section titled “想改端口、线程数、上传大小，但不知道该从哪开始”直接看 ServerOptions 配置指南。
这类问题不需要 FAQ 再重复展开。
MyBatis 接进去了，但查不到数据
Section titled “MyBatis 接进去了，但查不到数据”优先看：
重点排查：
feat.yaml中的feat.mybatis.path是否写对initial-sql是否真正执行- mapper 包名是否与
mybatis-config.xml一致
AI 模型一直没有返回内容
Section titled “AI 模型一直没有返回内容”优先看：
典型原因：
- 本地 Ollama 没起
- 模型名写错
FEAT_AI_API_KEY没进当前运行环境
SSE 连上了，但就是收不到事件
Section titled “SSE 连上了，但就是收不到事件”优先看 SSE 客户端教程。
重点确认：
- 响应头里的
Content-Type是否真的是text/event-stream - 你注册的是
onData(...)还是命名事件onEvent(...) - 服务端有没有真正持续输出事件
WebSocket 连不上，或者连上后发消息报错
Section titled “WebSocket 连不上，或者连上后发消息报错”优先看 连接第一个 WebSocket 服务。
重点确认：
- URL 是否用
ws://或wss:// - 服务端是否真的支持 WebSocket 升级
- 是否在
onOpen(...)之前就发消息了
HTTPS 跑不起来
Section titled “HTTPS 跑不起来”优先看 为 Feat 服务启用 HTTPS。
最常见原因：
- 证书路径不对
- PEM 文件没有打进资源目录
- 实际访问时仍然用的是
http://
应用能本地运行，但一进容器就挂
Section titled “应用能本地运行，但一进容器就挂”优先看 交付一个 Feat Cloud 应用。
先查最朴素的问题：
- Jar 是否真的打出来了
- Dockerfile 的
COPY路径是否正确 - 启动主类是否写错
几个经常被问到的基础事实
Section titled “几个经常被问到的基础事实”Feat 最低支持什么 JDK
Section titled “Feat 最低支持什么 JDK”JDK 8 或更高版本。
Feat 的几个主要模块分别是什么
Section titled “Feat 的几个主要模块分别是什么”feat-core：底层 HTTP 服务能力feat-cloud/feat-cloud-starter：更高层的注解式开发模型feat-ai：AI 能力接入
返回值什么时候会自动转 JSON
Section titled “返回值什么时候会自动转 JSON”在 Feat Cloud 控制器里，String 会按文本返回；对象和集合通常会自动序列化为 JSON。
具体表现可以直接看 Controller 开发实践。
如果你还是不确定该看哪一页
Section titled “如果你还是不确定该看哪一页”回到 从哪里开始读 Feat 文档。
很多“排错”其实是因为一开始就走错了文档路径。