在 SpringBoot 项目中配置 OpenAI API 密钥，最推荐的方式是通过操作系统环境变量注入，避免将密钥硬编码在代码或配置文件中。适用场景涵盖本地开发到生产部署，核心风险边界是严禁将包含密钥的文件提交至版本控制系统。

命令速用版

在 Linux 或 macOS 终端设置环境变量，并在 application.yml 中引用。

export OPENAI_API_KEY="sk-..."

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

为什么会这样

环境变量配置能将敏感信息与代码逻辑分离，降低密钥泄露风险。SpringBoot 启动时会自动读取系统环境变量并映射到配置属性，无需修改代码即可切换不同环境的密钥。

分步处理

第一步：获取密钥。登录 OpenAI 平台生成 API Key，复制保存。

第二步：设置环境变量。在操作系统或容器编排平台中设置键值对，例如 OPENAI_API_KEY。

第三步：修改配置文件。在 application.yml 中使用 ${变量名} 语法引用环境变量。

第四步：代码注入。使用 @Value("${OPENAI_API_KEY}") 或配置类读取属性。

第五步：忽略敏感文件。确保 .env 文件或包含密钥的本地配置在 .gitignore 列表中。

怎么验证是否生效

启动应用后查看控制台日志，确认配置值已加载且非空。发起一次简单的 API 调用请求，观察返回状态码是否为 200 且无 401 认证错误。

常见坑

避免在代码中直接写死密钥字符串。注意环境变量名大小写敏感问题。修改环境变量后需重启应用才能生效。

常见问题

本地开发怎么设置环境变量

Windows 使用 set 命令，Mac/Linux 使用 export 命令，或在 IDE 运行配置中添加 Env 变量。

生产环境密钥存在哪里

建议使用 Kubernetes Secrets、云厂商 Secret 管理器或 CI/CD 平台的变量管理功能。

配置后读取为 null 怎么办

检查环境变量名是否拼写一致，确认应用已重启，检查配置文件占位符语法是否正确。

参考来源

Spring Boot Documentation - Externalized Configuration https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config

OpenAI Documentation - API Keys https://platform.openai.com/docs/quickstart