🧾 Jenkins 流水线中 Git 拉取代码失败问题

问题现象

在 Jenkins Pipeline 构建过程中，Git 拉取代码（git pull 或 checkout）失败，提示 merge 冲突、无法 fetch、无法 checkout 分支等错误。

---

---

常见原因及解决方案

1️⃣ Git 合并冲突导致拉取失败

❌ 问题描述：

• Jenkins 报错：error: Your local changes to the following files would be overwritten by merge...
• Jenkins 报错：CONFLICT (content): Merge conflict in xxx

✅ 解决方案：

• 清理本地修改和未跟踪文件：

bat '''
    git reset --hard HEAD
    git clean -fd
'''

• 显式合并或 rebase：

bat '''
    git fetch origin dengping_dev
    git reset --hard origin/dengping_dev
    # 或者使用 merge
    git merge --no-ff origin/dengping_dev
    # 或者使用 rebase（推荐）
    git rebase origin/dengping_dev
'''

---

2️⃣ 分支名称不一致或不存在

❌ 问题描述：

• Jenkins 报错：fatal: Couldn't find remote ref <branch-name>
• Jenkins 报错：Branch <branch-name> did not exist

✅ 解决方案：

确保 ${BRANCH} 变量值正确，并与远程分支名一致。例如：

echo "当前构建分支: ${BRANCH}"
bat '''
    echo 获取远程所有分支...
    git fetch origin
    git branch -r
'''

如需强制切换到某个分支：

bat '''
    git fetch origin dengping_dev
    git checkout -b dengping_dev origin/dengping_dev
'''

---

3️⃣ 凭证错误或权限不足

❌ 问题描述：

• Jenkins 报错：Permission denied (publickey)
• Jenkins 报错：Authentication failed for 'https://xxx'

✅ 解决方案：

🔹 SSH 方式：

• 确保 Jenkins 使用的用户有私钥，并添加到 Jenkins 的凭据管理器。
• 示例配置：

checkout([$class: 'GitSCM', 
    branches: [[name: 'dengping_dev']],
    extensions: [],
    userRemoteConfigs: [[url: 'git@github.com:your/repo.git', credentialsId: 'your-ssh-cred-id']]
])

🔹 HTTPS 方式：

• 使用用户名密码或 token 访问：

checkout([$class: 'GitSCM', 
    branches: [[name: 'dengping_dev']],
    extensions: [],
    userRemoteConfigs: [[url: 'https://github.com/your/repo.git', credentialsId: 'your-git-username-pass']]
])

---

4️⃣ Jenkins 工作区残留导致冲突

❌ 问题描述：

• Jenkins 报错：error: unable to create file xxx (File exists)
• Jenkins 报错：error: cannot lock ref 'refs/remotes/origin/xxx'

✅ 解决方案：

每次构建前清理工作区：

options {
    disableConcurrentBuilds()
}
stages {
    stage('Clean Workspace') {
        steps {
            cleanWs()
        }
    }
}

或者手动删除 .git 文件夹（慎用）：

bat 'rm -rf .git'

---

5️⃣ Git 客户端未安装或路径未设置

❌ 问题描述：

• Jenkins 报错：'git' is not recognized as an internal or external command
• Jenkins 报错：sh step attempted to execute a windows batch command

✅ 解决方案：

• 确保 Jenkins 构建节点已安装 Git，并将 Git 的 bin 或 cmd 路径加入系统环境变量 PATH。
• 推荐使用 bat 替代 sh：

bat 'git --version'

---

6️⃣ Jenkins Pipeline 脚本写法不规范（适配 Windows）

❌ 问题描述：

• Jenkins 报错：Unexpected token 或 Groovy compilation error
• Jenkins 报错：bat script returned exit code 128

✅ 解决方案：

使用标准格式编写 bat 脚本块：

bat '''
    echo 开始同步代码...
    git fetch origin dengping_dev
    git reset --hard origin/dengping_dev
    git status
'''

---

推荐完整 Jenkinsfile 拉取逻辑（适配 Windows）

stage('Checkout Code') {
            steps {
                script {
                    echo "准备拉取代码到目录: ${env.WORKSPACE_DIR}"

                    withCredentials([sshUserPrivateKey(credentialsId: 'GIT_SSH_CRED', keyFileVariable: 'GIT_KEY')]) {

                        if (!fileExists("${env.WORKSPACE_DIR}\\.git")) {
                            echo "首次拉取，执行 git clone..."
                            bat """
                                @echo off
                                setlocal
                                set GIT_SSH_COMMAND=ssh -i "%GIT_KEY%"
                                set WORKSPACE_DIR=${env.WORKSPACE_DIR}
                                if not exist \"${env.WORKSPACE_DIR}\" mkdir \"${env.WORKSPACE_DIR}\"
                                cd /d \"${env.WORKSPACE_DIR}\"

                                REM 删除现有内容
                                if exist * (
                                    del /F /Q /S * > nul
                                    for /D %%p in (*) do rmdir /S /Q "%%p"
                                )

                                echo 初始化 Git 仓库...
                                git init
                                git remote add origin ${GIT_REPO_URL}

                                echo 获取远程分支信息...
                                git fetch --all

                                echo 查看可用分支...
                                git branch -r > available_branches.txt
                                type available_branches.txt

                                echo 检出指定分支: ${BRANCH}
                                git checkout -b ${BRANCH} origin/${BRANCH}
                            """
                        } else {
                            echo "已存在代码仓库，执行 git pull..."
                            dir("${env.WORKSPACE_DIR}") {
                                try {
                                    bat """
                                        @echo on
                                        set GIT_SSH_COMMAND=ssh -i "%GIT_KEY%"
                                        cd /d "${env.WORKSPACE_DIR}"
                                        echo "设置 skip-worktree 防止后续操作覆盖"
                                        git update-index --skip-worktree jenkins/jenkins_config.json
                                        git update-index --skip-worktree jenkins/result.json
                                        echo "切换分支"
                                        git checkout ${BRANCH}
                                        echo "强制同步远程最新提交"
                                        git fetch origin ${BRANCH}
                                        git reset --hard origin/${BRANCH}
                                        echo "清理未跟踪文件"
                                        git clean -fd
                                        echo "拉取代码"
                                        git pull origin ${BRANCH}
                                    """
                                } catch (Exception e) {
                                    echo "警告：git 操作失败，但继续执行后续 stage: ${e.getMessage()}"
                                }
                            }
                        }
                    }
                }
            }
        }

---

总结建议

场景	推荐操作
存在本地修改	使用 git reset --hard HEAD 和 git clean -fd
分支不一致	显式 fetch + checkout -b
权限或凭证问题	在 Jenkins 中配置 Git 凭据
Jenkins 工作区残留	使用 cleanWs()
Windows 上运行	全部使用 bat 执行 Git 命令
避免 merge 失败	优先使用 reset --hard 或 rebase

---