Loading... # Jenkins 环境变量加载问题根因分析与解决方案 # 一、事件概述 ## 1. 事件背景 在 Jenkins CI/CD 流水线中使用 Claude Code CLI 时，遇到 API Key 认证失败的问题。尽管在 ~/.bashrc 文件中正确配置了 ANTHROPIC 相关环境变量，但 Jenkins 任务仍然报错 Invalid API key。 ## 2. 影响范围 ### A. 影响范围 所有依赖 Claude Code CLI 的 Jenkins 自动化任务 ### B. 影响功能 - 文档自动生成流水线 - 博客自动发布流程 - 依赖 Claude API 的自动化脚本 ## 3. 严重程度 P2 级问题（影响自动化流水线，但有临时解决方案） # 二、事件时间线 ## 1. 问题发现 ### A. 现象描述 Jenkins 构建任务执行失败，错误信息： ``` Invalid API key · Please run /login ``` ### B. 故障环境 - Jenkins Master：192.168.124.86 - Jenkins Agent：mlab.dev.vm1（lab 用户） - 执行命令：claude -p /chinese-doc-generator ... ## 2. 问题排查 ### A. 本地验证 SSH 登录到 Jenkins Agent 手动执行命令，一切正常。 ### B. 对比分析 本地交互式 Shell 可以加载环境变量，Jenkins 非交互式 Shell 无法加载。 ## 3. 根因定位 检查 ~/.bashrc 文件开头发现： ```bash # ~/.bashrc: executed by bash(1) for non-login shells. # If not running interactively, don't do anything case $- in *i*) ;; *) return;; esac ``` 这一段代码导致非交互式 Shell 直接返回，跳过了后续所有环境变量定义。 # 三、问题分析 ## 1. 直接原因 ~/.bashrc 在文件开头有明确的非交互式 Shell 检查，导致 Jenkins 使用的非交互式 Shell 无法加载环境变量。 ## 2. Shell 配置文件加载机制 ```mermaid graph TD A[Shell 启动] --> B{Shell 类型} B -->|Login Shell| C[加载 /etc/profile] C --> D[加载 ~/.profile] D --> E[加载 ~/.bashrc] B -->|非登录交互式| F[加载 /etc/bash.bashrc] F --> E B -->|非交互式| G[不自动加载任何配置] G --> H[除非显式 source] E --> I{是否交互式} I -->|是| J[执行后续配置] I -->|否| K[立即返回] K --> L[环境变量未加载] ```   ## 3. 根本原因（5 Whys 分析） ### A. 为什么环境变量没有生效？ 因为 ~/.bashrc 在非交互式模式下直接 return 了。 ### B. 为什么 ~/.bashrc 会直接返回？ 这是 Ubuntu 默认 bashrc 配置的保护机制，避免非交互式 Shell 加载不必要的配置。 ### C. 为什么本地正常而 Jenkins 不正常？ 本地 SSH 登录是 Login Shell，会加载 ~/.profile；Jenkins 使用非交互式 Shell，且没有显式 source bashrc。 ### D. 为什么在 Jenkins 脚本中直接设置有效？ 因为在当前 Shell 进程中直接 export 环境变量，不依赖配置文件加载机制。 ### E. 深层问题是什么？ 对 Linux Shell 配置文件加载机制理解不足，没有针对 CI/CD 环境正确配置环境变量。 # 四、解决方案 ## 1. 方案对比 | 方案 | 优点 | 缺点 | 推荐度 | |------|------|------|--------| | 移至 ~/.profile | 标准 Linux 做法，所有 Shell 都能加载 | 需要 SSH 重新登录生效 | ⭐⭐⭐⭐⭐ | | Jenkins 脚本显式 source | 灵活，不影响其他环境 | 每个 Job 都要配置 | ⭐⭐⭐ | | 创建独立 .env 文件 | 配置清晰，易于管理 | 需要修改 Jenkins 配置 | ⭐⭐⭐⭐ | | Jenkins 全局环境变量 | 集中管理，对所有 Job 生效 | 需要 Jenkins UI 操作 | ⭐⭐⭐⭐ | | 修改 bashrc 结构 | 一劳永逸 | 可能影响其他非交互式场景 | ⭐⭐ | ## 2. 推荐方案：环境变量分层配置 ### A. 核心思路 不同类型的配置放到不同的配置文件中，遵循 Linux 标准实践。 ### B. 具体实施 **将 API Key 等敏感环境变量移至 ~/.profile**： ```bash # ~/.profile - 适用于 Login Shell 和非交互式 Shell export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic export ANTHROPIC_AUTH_TOKEN=your_api_key_here export ANTHROPIC_API_KEY=your_api_key_here ``` **在 ~/.bashrc 中保留交互式 Shell 特定配置**： ```bash # ~/.bashrc - 适用于交互式 Shell # 别名、函数、提示符等 alias ll='ls -alF' alias la='ls -A' alias l='ls -CF' ``` ### C. 配置文件加载顺序 ```mermaid graph LR A[Shell 启动] --> B{Login Shell} B -->|是| C[~/.profile] B -->|否| D[~/.bashrc] C --> E{调用 bashrc} E -->|是| D D --> F{交互式检查} F -->|通过| G[加载交互式配置] F -->|失败| H[返回] C --> I[环境变量已加载] ```   ## 3. Jenkins 配置最佳实践 ### A. 方式一：使用环境变量文件 ```groovy pipeline { agent { label 'mlab.dev.vm1' } stages { stage('Build') { steps { sh ''' source ~/.profile cd /mydata/code/write/news/ claude -p /chinese-doc-generator "${content}" ''' } } } } ``` ### B. 方式二：使用 Jenkins Credentials ```groovy pipeline { agent { label 'mlab.dev.vm1' } environment { ANTHROPIC_API_KEY = credentials('claude-api-key') } stages { stage('Build') { steps { sh 'claude -p /chinese-doc-generator "${content}"' } } } } ``` ### C. 方式三：使用全局工具配置 在 Jenkins 系统配置中添加环境变量，对所有 Job 生效。 # 五、经验总结 ## 1. 核心知识点 - **Login Shell**：加载顺序为 /etc/profile → ~/.profile → ~/.bashrc - **非登录交互式 Shell**：加载 /etc/bash.bashrc → ~/.bashrc - **非交互式 Shell**：默认不加载任何配置文件，除非显式 source - **~/.bashrc**：通常包含交互式检查，非交互式会提前返回 ## 2. CI/CD 环境配置原则 - 环境变量应放在 ~/.profile 或 /etc/environment 中 - 不要在 ~/.bashrc 中放置 CI/CD 需要的环境变量 - 使用 Jenkins Credentials 管理敏感信息 - 优先使用 Jenkins 原生配置而非依赖 Shell 配置文件 ## 3. 排查技巧 - 使用 `echo $-` 检查 Shell 是否为交互式（包含 i 表示交互式） - 使用 `shopt login_shell` 检查是否为 Login Shell - 在 Jenkins 脚本中添加 `set -x` 查看执行过程 - 使用 `env | grep ANTHROPIC` 验证环境变量是否加载 ## 4. 预防措施 - 在部署新的 CI/CD 任务前，先在 Agent 上模拟非交互式执行 - 建立环境变量配置规范文档 - 使用 Infrastructure as Code 工具（如 Ansible）统一管理配置 *** ## 参考资料 1. [Bash Manual - Bash Startup Files](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html) 2. [Jenkins Pipeline Environment Variables](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#handling-environments) 最后修改：2026 年 01 月 16 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏