使用Jenkins构建时Git LFS报错：git-lfs命令未找到

问题现象 #

• Windows 10代理机手动拉取含Git LFS的仓库可正常构建，但Jenkins流水线执行时无法检出大文件
• 不含Git LFS的流水线可正常拉取构建
• 控制台报错：

stderr: git-lfs filter-process: line 1: git-lfs: command not found

已尝试操作 #

• 参考过Git LFS Jenkins配置相关文章但未解决
• 怀疑Jenkins代理的环境路径未包含git-lfs可执行文件路径

所用流水线脚本 #

pipeline {
agent { label 'WindowsFoo' }//any
tools {
    msbuild 'MSBuild 2022' // I don't believe this is used!
}

stages {
    stage ('Clean workspace') {
          steps {
            // Clean before build
            cleanWs()  // 
            // cleanWs fails if ANY console window is open or windows explorer open to the repository  
             
          }
        }
        
    stage('Checkout') {
        steps {

                 echo 'checkout'
                
                
                    script 
                    {
                    
                        git credentialsId: 'Foo_ID', url: 'https://github.com/Foo/Foo-software.git'
                        
                       
                          
                         checkout([
                $class: 'GitSCM',
                branches: [[name: '*/master']],
                doGenerateSubmoduleConfigurations: false,
                extensions: [[$class: 'GitLFSPull']],   //extensions: [lfs()],
                submoduleCfg: [],
                userRemoteConfigs: [[url: 'https://github.com/Foo/Foo-software.git']]
                      ])  
                       
                    }                   
        }
    }

}

疑问与解决思路 #

1. 验证Jenkins是否安装Git LFS插件（无管理员权限） #

• 进入Jenkins的插件管理页面（路径：Manage Jenkins → Manage Plugins），切换到Installed标签页，搜索Git LFS，若能找到则已安装；若没有权限访问插件管理页面，可在流水线中尝试使用lfs()扩展（替换现有GitLFSPull配置），执行报错则大概率未安装。

2. 无需Git LFS插件的实现方案 #

即使没有插件，也可以通过手动执行Git LFS命令完成拉取：

stage('Checkout') {
    steps {
        script {
            git credentialsId: 'Foo_ID', url: 'https://github.com/Foo/Foo-software.git'
            // Windows代理用bat执行拉取命令
            bat 'git lfs pull'
        }
    }
}

3. 解决git-lfs命令找不到的核心问题 #

报错本质是Jenkins代理的环境变量PATH未包含git-lfs的安装路径，可通过以下方式修复：

• 方法一：修改代理系统环境变量：找到git-lfs安装目录（通常为C:\Program Files\Git LFS），添加到系统PATH中，重启Jenkins代理服务
• 方法二：流水线内临时设置环境变量：

stage('Checkout') {
    steps {
        script {
            // 替换为实际git-lfs安装路径
            env.PATH = "C:\\Program Files\\Git LFS;${env.PATH}"
            git credentialsId: 'Foo_ID', url: 'https://github.com/Foo/Foo-software.git'
            bat 'git lfs pull'
        }
    }
}

• 方法三：修改Jenkins代理服务参数：若代理以Windows服务运行，在服务属性的「启动参数」中添加--env PATH="%PATH%;C:\Program Files\Git LFS"（替换为实际路径），重启服务

4. 优化流水线脚本 #

当前脚本中两次执行git克隆属于冗余操作，建议保留一种即可：若已安装Git LFS插件，使用带GitLFSPull扩展的checkout；若未安装插件，使用普通git克隆加手动git lfs pull命令。

内容的提问来源于stack exchange，提问作者Dave