麻雀窝 Sparrow Zoo

IDEA 启动读不到环境变量:从报错定位到运行配置修复

终端能读取环境变量,IDEA 启动的 Spring Boot 应用却提示未配置。以 skills 目录变量为例,说明如何定位进程环境差异、配置运行参数并验证修复。

面向使用 macOS、Zsh 和 IntelliJ IDEA 启动 Spring Boot 应用的开发者;界面选项随 IDEA 版本有所差异。发布于 更新于
同一台电脑,不同环境IDEA 启动变量缺失排查终端 Shell变量已设置,目录存在IDEA → Java 进程启动时未拿到所需变量运行配置中显式传入保存 → 重启 → 检查应用实际取值
阅读目录

结论先行

终端有变量,不代表 IDEA 启动的 Java 进程也有。此次排查中,终端能够读取 SPARROW_AGENT_SKILL_WORKSPACE,配置的目录也存在,但应用启动日志明确报缺少该配置。最直接的处理是在当前应用的运行配置中显式设置变量,再重新启动验证。

IDEA 支持为运行配置设置环境变量,参见 JetBrains 官方说明。这次只需处理本机启动配置,业务代码无需增加读取 Shell 文件的逻辑。

问题背景

应用启动时注册 Skills 工具,需要一个实际存在的 skills 目录。配置文件使用环境变量占位符:

code
agent.skills.dirs=${SPARROW_AGENT_SKILL_WORKSPACE:}

冒号后没有内容,表示变量缺失时先得到空字符串。本项目启动配置会拒绝空目录,因此问题最终表现为 ChatClient 创建失败,而不是一个直接写着“环境变量读取失败”的错误。

详细内容

沿异常链找到真正缺少的配置

启动失败时,先读最底层原因,不要停在最外层的依赖注入异常。本次异常经过消息订阅器、ChatClient 配置,最终指向:

code
java.lang.IllegalStateException:
Configure agent.skills.dirs or SPARROW_AGENT_SKILL_WORKSPACE

对应配置类先读取 agent.skills.dirs,为空时再读取 SPARROW_AGENT_SKILL_WORKSPACE,两者都为空才抛错。这说明当前应用在创建工具时没有获得有效目录配置,接下来应核对配置来源。

分清已经证实的事实与尚未查明的原因

此次排查的证据
检查位置结果说明
终端进程变量有值证明当前终端环境已设置
变量指定目录实际存在排除该路径不存在
~/.zshenv有变量定义说明终端的配置来源
IDEA 运行配置未显式设置该变量应用依赖继承到的环境
应用启动日志目录配置为空说明启动的 Java 进程未获得有效值

进程在启动时接收环境变量;修改终端环境不会自动更新已经运行的其他进程。IDEA 在 macOS 上会尝试加载 Shell 环境,因此不能笼统地说“IDEA 不读取 .zshenv”。已有进程保留旧环境、Shell 环境加载失败、运行配置设置不同等情况,都可能造成差异。具体加载行为见 JetBrains Shell Environment Loading。

本次诊断的范围

已定位到应用没有取得所需变量,但尚未检查 IDEA 自身的环境加载日志,不能断言一定由某个启动方式或某次超时造成。

在当前 IDEA 运行配置中补上变量

  1. 打开 Run → Edit Configurations。
  2. 选中实际启动的 SparrowApplication,核对入口类和使用的模块。
  3. 找到 Environment variables。若界面未显示,在 Modify options 中启用相应选项;不同版本的名称和位置可能略有差异。
  4. 添加变量名 SPARROW_AGENT_SKILL_WORKSPACE,值填写本机 skills 目录的绝对路径。
  5. 保存配置,结束旧进程,再用同一个运行配置启动。
code
SPARROW_AGENT_SKILL_WORKSPACE=/absolute/path/to/AICoding/.agents/skills

上面是示例路径,必须换成自己的实际目录。此项目的变量本身就指向 skills 目录,不应再追加一层 skills。不要把它放进 Program arguments 或 VM options;这几个字段的作用不同。官方配置入口见 运行参数与环境变量。

用断点确认 Java 进程实际收到了什么

重新启动后,检查原来的缺配置异常是否消失。若仍然失败,在 AgentToolsConfiguration.configure 读取目录的位置设置断点,查看:

code
System.getenv("SPARROW_AGENT_SKILL_WORKSPACE")
environment.getProperty("SPARROW_AGENT_SKILL_WORKSPACE")
environment.getProperty("agent.skills.dirs")

使用推荐的环境变量方案时,前两项应取得目录路径,第三项也应通过占位符得到有效值。如果直接覆盖了 agent.skills.dirs,则 System.getenv 为空也可能正常,判断应以实际使用的配置来源为准。

目录存在只证明路径有效;还要核对应用运行身份能读取目录,且其中包含可加载的 skills。只有重新启动并通过相应初始化,才能说这处启动问题得到验证。后续若出现数据库或模型认证错误,应根据新的异常继续排查。

不要打印密钥

目录路径可以在本机核对;API Key、Token 和密码只检查是否有值,不输出完整内容,也不要把它们写进共享运行配置。

配置方式怎么选,以及哪些操作容易无效

日常在 IDEA 中开发,优先使用应用自己的运行配置。若希望直接指定 Spring 配置,本项目也允许在 VM options 中设置:

code
-Dagent.skills.dirs=/absolute/path/to/skills

这是 Java 系统属性,不会创建同名环境变量,只适用于通过 Spring 配置读取此属性的代码。推荐方案和替代方案选择一种即可,避免多处设置后不知道实际用的是哪一份。

在 IDEA 内置 Terminal 中 export,只会影响该 Shell 及其之后启动的子进程,不能据此认定工具栏 Run 启动的应用也获得相同值。只新建 .env 文件也不能保证生效;必须由当前 IDEA 版本的运行配置或应用中已存在的加载机制明确读取它。

如果要继续追查 IDEA 为什么没有继承 Shell 环境,可通过 Help → Show Log in Finder 查找 idea.log 中与环境加载有关的错误,再参考 JetBrains 的 Shell 环境加载说明处理。无需为了修复一个本机目录配置而改动全局系统环境。

总结归纳

这类问题的关键,是检查真正启动应用的进程获得了什么配置。先从最底层异常确定变量名,再对比终端、运行配置与应用取值,最后在明确的启动入口传入并重新验证。

本文记录的是已完成的排查和可执行修复步骤;撰写时尚未保存本次 IDEA 配置,也未完成重启验证,不能将方案说明当作修复成功记录。

参考资料

  1. JetBrains:Program arguments, VM options, environment variables

    说明运行参数、Java 系统属性与环境变量的不同配置入口。

  2. JetBrains:Shell Environment Loading

    说明 macOS 上 IDE 加载 Shell 环境的机制,以及加载失败时的日志排查方向。官方资料核对于 2026-10-28。