说实话Spring AI 入门文档写得挺顺的但真正跑起来报错的时候那个体验落差能让你怀疑人生。这不是一篇教你”如何优雅使用 Spring AI”的文章。这是我的踩坑实录每一个坑都是真实付出过时间代价的。有些错误重复踩过三四次才记住写下来算是给自己提个醒顺便帮后来者少走点弯路。1. JDK 17 以下报错Unsupported class file major version XX报错信息java.lang UnsupportedClassVersionError: class file version XX.0 does not match Java version requirement (class file version must be one of 65)出现场景项目跑起来直接崩或者启动时看到UnsupportedClassVersionError。根因Spring AI 基于 Spring Boot 3.x 开发而 Spring Boot 3.x 要求最低 JDK 17。JDK 8、11、14、16 全都不行。解决去 Alibaba Dragonwell 或 Adoptium 下载安装 JDK 17 或 21然后# 确认当前 Java 版本 java -version # 如果用的是 IDEA在 File Project Structure Project # SDK 里手动改成本地装好的 JDK 17这条没什么技巧就是装 JDK没别的办法。踩过三次之后我终于把环境变量里的JAVA_HOME永久改成了 JDK 21。2. pom.xml 里的依赖拉不下来报Could not resolve dependencies报错信息Could not resolve dependencies for project xxx:chatbot:jar:0.0.1-SNAPSHOT: Could not find artifact org.springframework.ai:spring-ai-starter-model-zhipuai:jar:1.1.2出现场景pom.xml 写好了一mvn compile报找不到依赖。根因Spring AI 的包还没进 Maven 中央仓库spring-ai-starter-model-zhipuai这类 artifact 都在 Spring 的 Milestone 仓库里。解决在 pom.xml 里补上仓库配置repositories repository idspring-milestones/id nameSpring Milestones/name urlhttps://repo.spring.io/milestone/url snapshotsenabledfalse/enabled/snapshots /repository repository idsonatype-snapshots/id nameSonatype Snapshot Repository/name urlhttps://oss.sonatype.org/content/repositories/snapshots/url releasesenabledfalse/enabled/releases snapshotsenabledtrue/enabled/snapshots /repository /repositories这条我第一次踩的时候百度了半小时没解决后来发现就是仓库没配。国内网络可能还访问不了国外仓库要配一下阿里云镜像mirrors mirror idaliyunmaven/id mirrorOf*/mirrorOf nameAliyun Maven/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors不过注意sonatype-snapshots这个仓库如果也被镜像覆盖snapshot 版本可能拉不到。那就改成mirror idaliyunmaven/id mirrorOfspring-milestones,central/mirrorOf nameAliyun Maven/name urlhttps://maven.aliyun.com/repository/public/url /mirror只镜像central和spring-milestones放过 sonatype。3. API Key 报错401 Unauthorized或Invalid API key报错信息[ERROR] org.springframework.ai.zhipuai.ZhiPuAiApiException: Invalid API key. Please check your API key.出现场景项目启动没问题接口也调了但每次请求都返回 401。根因就三个可能Key 写错了、Key 没生效、环境变量没读到。排查顺序第一步先看 application.yml 里有没有写死 Keyspring: ai: zhipuai: api-key: ${ZHIPUAI_API_KEY:your-api-key-here} # 这里如果冒号后面那个your-api-key-here就是你环境变量的默认值而你环境变量没配就会用这个假 Key 去请求。第二步确认环境变量名对不对# Windows PowerShell echo $env:ZHIPUAI_API_KEY # macOS / Linux echo $ZHIPUAI_API_KEY输出为空或者空的就说明环境变量没设上。第三步确认 Key 本身没问题。登录 open.bigmodel.cn进 API Key 管理页面确认 Key 没被禁用、没过期、额度还有。4. 模型名写错报model not found报错信息[ERROR] ZhiPuAiApiException: model [glm-4.7-flash] not found or not available出现场景配置写好了Key 也没问题但就是跑不通。根因模型名大小写敏感且智谱的模型名格式要求严格。踩坑记录写成GLM-4全大写→ 报错写成glm-4-flash混了glm-4和4.7→ 报错写成glm-4.7-flash实际想用但当前账号没权限→ 报错写成glm-4→ 成功正确写法对照表你想用的模型正确写法GLM-4 最新版glm-4GLM-4 Flashglm-4-flashGLM-4.7 Flashglm-4.7-flashGLM-4V多模态glm-4v建议先在 open.bigmodel.cn 的体验中心测试一下确认模型能跑再写到配置里。5. 同时引入多个 Starter启动报NoUniqueBeanDefinitionException报错信息NoUniqueBeanDefinitionException: No qualifying bean of type org.springframework.ai.chat.client.ChatClient$Builder available出现场景同时引了spring-ai-starter-model-zhipuai和spring-ai-starter-model-dashscope或者同时引了spring-ai-alibaba-starter然后启动直接崩。根因每个 Starter 都会自动装配自己的ChatClient.Builder实现同时引入多个 Spring AI 扩展的 Starter就会产生冲突——Spring 不知道该用哪个 Builder。踩坑场景还原!-- 这样写会报错 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-zhipuai/artifactId /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId /dependency解决按需只选一个。如果当前用智谱只保留 zhipuai 的 starter如果后续要换通义到时候再改。如果你确实需要同时支持多个模型可以手动指定使用哪个 Builder// 在 Configuration 类里显式注入需要的 Builder Configuration public class ChatClientConfig { Bean public ChatClient zhipuChatClient(ChatClient.Builder builder) { return builder.defaultSystem(你是一个助手).build(); } }6. ChatMemory 不生效连续对话记不住上下文报错信息不报错但连续问问题模型”失忆”了。上一轮说”我叫张三”下一轮问”我叫什么”模型回答”你没有告诉我你的名字”。踩坑过程兴冲冲加了MessageChatMemoryAdvisor以为完事了// 这是错误的用法实际每次请求都会创建新的 Memory 实例 .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))这样写 ChatMemory 是局部变量请求结束后就没了每次对话都是全新的。正确写法把 ChatMemory 提出来作为类成员变量private final ChatMemory chatMemory MessageWindowChatMemory.builder() .maxMessages(50) .build(); public ChatController(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder .defaultSystem(DEFAULT_PROMPT) .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build()) .defaultAdvisors(new SimpleLoggerAdvisor()) .build(); }另外如果你的应用是多实例部署每个实例的 ChatMemory 是独立的——A 实例记住的上下文B 实例不知道。这是分布式场景下的额外坑需要引入 Redis 等外部存储做 Memory 持久化。7. 启动成功但接口没响应一直转圈报错信息无报错但请求发出去之后一直 pending30 秒后超时。踩坑排查过程网络通不通curl http://localhost:8080/chat/simple?queryhi直接返回说明本地没问题API Key 有没有额度没额度不会马上报错有些平台会静默超时模型名有没有写错写错有时候不是报 404而是静默超时最后发现公司网络限制了外网访问Java 应用能连 GitHub 拉依赖但连不上open.bigmodel.cn请求发不出去。解决# 测试网络连通性 ping open.bigmodel.cn curl -v https://open.bigmodel.cn/api/paas/v4 # 如果 ping 不通但能拉依赖说明是 DNS 污染或者白名单问题 # 可以尝试在 application.yml 里指定 base-url部分 starter 支持在国内用智谱模型基本不存在这个问题。但如果你用的是通义千问或者 OpenAI而且走的代理一定注意不要在代码里设全局代理http.proxyHost否则可能导致请求头里的 API Key 被意外转发到不该去的地方。8.GetMapping传中文参数变乱码报错信息不报错但 query 参数传中文返回的结果像是随机抽的完全不对。踩坑过程// 以为是模型的问题结果是编码问题 http://localhost:8080/chat/simple?query你好用 Postman 调没问题用浏览器地址栏直接输就出问题。根因Tomcat 默认 URL 参数编码是ISO-8859-1Spring Boot 3.x 虽然默认改成了UTF-8但某些版本或配置下仍然有问题。解决在application.yml里显式指定server: port: 8080 servlet: encoding: charset: UTF-8 enabled: true force: true或者不用GetMapping的 query 参数改用RequestBody接收 JSONPostMapping(/simple) public String simpleChat(RequestBody MapString, String request) { String query request.get(query); return chatClient.prompt(query).call().content(); } // 请求体 // { query: 你好 }POST JSON 彻底绕开 URL 编码问题推荐这种方式。9.spring-ai-alibaba版本升级后 API 变了报错信息升级了spring-ai-alibaba.version然后编译报错很多类找不到或者方法签名变了。踩坑场景从1.0.0-M5.1升级到1.1.2.2发现DashScopeChatOptions包名变了InMemoryChatMemory改成了MessageWindowChatMemoryChatClient.Builder的配置方法名也有调整根因Spring AI 和 Spring AI Alibaba 都还在快速迭代版本之间的 API 兼容性没有保证。里程碑版本尤其明显——1.0.0-M1和1.0.0-M6之间 API 差距能让人崩溃。建议锁定 BOM 版本不要用LATEST或者不写版本号升级前先看 Changelog确认 breaking changes如果是生产项目锁定 minor 版本只做 patch 升级properties spring-ai.version1.1.2/spring-ai.version !-- 锁定到 1.1.x不要写 1.x -- spring-ai-alibaba.version1.1.2.2/spring-ai-alibaba.version /properties总结踩坑规律写完回头看这些坑有规律环境类JDK 版本、仓库配置、网络连通性——这类问题只要你第一次搭好环境后面基本不会再踩配置类API Key、模型名、编码——这类问题有标准解法踩一次记住就好理解类ChatMemory 实例作用域、多 Starter 冲突、版本兼容性——这类需要真正理解 Spring AI 的设计思想踩了印象最深前两类靠细心第三类靠多读文档多看源码。Spring AI 的文档虽然有些不完整但源码注释写得挺清楚的IDE 里Ctrl点击进去看比百度有效率得多。