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 文件开头发现：

# ~/.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 配置文件加载机制

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. 方案对比

2. 推荐方案：环境变量分层配置

A. 核心思路

不同类型的配置放到不同的配置文件中，遵循 Linux 标准实践。

B. 具体实施

将 API Key 等敏感环境变量移至 ~/.profile：

# ~/.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 特定配置：

# ~/.bashrc - 适用于交互式 Shell
# 别名、函数、提示符等
alias ll='ls -alF'
alias la='ls -A'
alias l='ls -CF'

C. 配置文件加载顺序

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. 方式一：使用环境变量文件

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

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
2. Jenkins Pipeline Environment Variables