在之前的开发中，我使用 `ClasspathSkillRegistry` 作为 Agent Skill 的查找策略，本地开发环境下调试、运行都一切正常，没有出现任何异常。

感兴趣的小伙伴可以回顾上一篇相关内容：https://www.lucaju.cn/index.php/archives/168/

## 一、问题出现：上线后频繁报「Skill not found」

本以为本地测试无误后，上线就能顺利运行，结果程序部署到服务器后，日志中频繁出现 `Skill not found: ` 错误，导致相关功能完全无法使用。

## 二、问题排查：排除常见误区

遇到问题后，首先排查了最容易出现问题的两个点，均排除异常：

1. 确认 Skill 已成功打包：检查部署的 jar 包，解压后确认 skill 相关文件已正常包含在内，不存在打包遗漏的情况；
2. 确认 Skill Name 无误：核对代码中调用 Skill 的名称与配置文件中的名称，完全一致，排除拼写错误、大小写错误等问题。

## 三、问题根源：找到官方 Issue

排除上述常见问题后，推测可能是框架本身的兼容性问题，于是去 GitHub 上搜索相关问题，果然发现已有其他开发者遇到过相同情况，并且提交了 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426

![skill-issue.png](https://developer.qcloudimg.com/http-save/yehe-11778967/a58a66fffd256efd85f809567f285d0a.png)
从 Issue 中得知，问题根源在于 SpringBoot 项目打包成 jar 包后，路径机制发生变化，导致 `ClasspathSkillRegistry` 无法正常加载 resources 下的 Skill 目录，这是目前 spring-ai-alibaba 框架的一个已知 bug。

## 四、临时解决方案：改用 FileSystemSkillRegistry

由于官方尚未修复该 bug，为了不影响线上功能正常使用，我采用了临时解决方案：将 Skill 目录存放在服务器的文件系统中，通过指定真实路径获取 Skill，对应的查找策略改用 `FileSystemSkillRegistry`。

修改后的核心代码如下：

```java
/**
 * 获取技能智能体钩子。
 */
private static SkillsAgentHook getSkillsAgentHook() {

    // 注释掉原有的ClasspathSkillRegistry方式（本地可用，打包后失效）
    // SkillRegistry registry = ClasspathSkillRegistry.builder()
    //         .classpathPath("skills")
    //         .build();

    /*
      临时解决方案说明：
      spring ai alibaba 目前使用 ClasspathSkillRegistry 打包后，无法获取 Resource 下的目录
      因此修改为使用 FileSystemSkillRegistry，从文件系统真实路径获取 Skill
      相关 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426
     */
    String skillPath = SpringUtils.getProperty("doc.skills-path");
    log.info("skillPath: {}",skillPath);

    FileSystemSkillRegistry registry = FileSystemSkillRegistry.builder()
            .projectSkillsDirectory(skillPath)
            .build();
    return SkillsAgentHook.builder()
            .skillRegistry(registry)
            .build();
}
```

## 五、后续

需要说明的是，这只是一个临时解决方案——使用该方案后，需要手动将 Skill 配置文件同步到服务器的指定路径（即配置项 `doc.skills-path` 对应的路径），增加了少量部署成本。

后续会持续关注官方 Issue 的修复进度，待 bug 修复后，再切换回 `ClasspathSkillRegistry` 方式，减少部署环节的手动操作。

也希望遇到相同问题的小伙伴，能通过这篇踩坑记录少走弯路～

在之前的开发中，我使用 ClasspathSkillRegistry 作为 Agent Skill 的查找策略，本地开发环境下调试、运行都一切正常，没有出现任何异常。

Agent Skill 踩坑记录 | SpringBoot 打包后 Skill 加载失败问题排查与解决

本文记录 Spring AI Alibaba Agent Skill 在 SpringBoot 打包后出现 Skill not found、ClasspathSkillRegistry 无法加载的问题，通过切换 FileSystemSkillRegistry 实现临时解决，分享完整踩坑排查与代码方案。

Java开发

后端

开发工具

Spring AI框架ClasspathSkillRegistry在jar包部署时无法加载Skill资源，导致线上报错。通过排查发现是框架已知bug，临时改用FileSystemSkillRegistry指定文件系统路径解决。需手动同步Skill文件到服务器，待官方修复后切换回原方案。

文件系统

服务器

智能体

GitHub

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Agent Skill 踩坑记录 | SpringBoot 打包后 Skill 加载失败问题排查与解决-腾讯云开发者社区-腾讯云

Agent Skill 踩坑记录 | SpringBoot 打包后 Skill 加载失败问题排查与解决

Agent Skill 踩坑记录 | SpringBoot 打包后 Skill 加载失败问题排查与解决

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐