前言

在日常的持续集成工作中，从 Git 仓库拉取代码并进行编译是最基础也是最核心的步骤。Jenkins 作为流行的 CI/CD 工具，提供了强大的 Git 集成能力。本文将以图文 + 中文注释的方式，手把手教你如何在 Jenkins 中：

• 安装必要的 Git 相关插件
• 添加 Git 仓库的访问凭证（用户名密码 / SSH 私钥）
• 创建 Freestyle 或 Pipeline 项目
• 配置源码拉取并执行编译命令

适用人群：刚接触 Jenkins 的开发人员、运维工程师。
前置条件：Jenkins 服务已启动并可以访问，Jenkins 服务器已安装 Git 客户端。

一、环境准备：安装插件与全局工具

1.1 安装必要插件

登录 Jenkins → 点击左侧菜单 Manage Jenkins → Manage Plugins → 切换到 Available 选项卡，搜索并安装以下插件：

安装完成后，勾选“重启 Jenkins” 使插件生效。

1.2 配置全局 Git 工具

Manage Jenkins → Global Tool Configuration → 找到 Git 模块：

• Path to Git executable：填写 git（前提是 Jenkins 服务器已安装 Git）
• Name：可自定义，例如 Default Git

如果服务器未安装 Git，请先执行 yum install git（CentOS）或 apt install git（Ubuntu）进行安装。

二、核心步骤：添加 Git 凭证

进入 Manage Jenkins → Credentials → System → Global credentials (unrestricted) → 点击右上角 + Add Credentials。

中文：进入 管理Jenkins → 凭据 → 系统 → 全局凭据（无限制） → 点击右上角 + 添加凭据。

2.1 方式一：用户名 + 密码 / Personal Access Token（PAT）

适用场景：使用 HTTPS 协议拉取代码（例如 GitHub、GitLab 等）。

填写信息如下：

点击 Create 完成。

如何获取 PAT？

• GitHub：Settings → Developer settings → Personal access tokens → Generate new token
• GitLab：Settings → Access Tokens → 创建并勾选 read_repository 权限

2.2 方式二：SSH 用户名 + 私钥

适用场景：使用 SSH 协议拉取代码，安全性更高。

步骤 1：在 Jenkins 服务器生成 SSH 密钥对

ssh-keygen -t rsa -b 4096 -C "jenkins@your-server"

一路回车，密钥默认保存在：

• 私钥：~/.ssh/id_rsa
• 公钥：~/.ssh/id_rsa.pub

步骤 2：将公钥添加到 Git 仓库

以 GitLab 为例：登录 GitLab → 右上角头像 → Settings → SSH Keys → 将 id_rsa.pub 文件内容粘贴 → 添加。

步骤 3：在 Jenkins 添加 SSH 私钥凭证

在 Add Credentials 页面：

点击 Create。

⚠️ SSH 踩坑提醒

如果拉取代码时出现 Host key verification failed 错误，请按以下方法解决：

• 方法一（临时）：在 Jenkins 服务器上手动执行一次 ssh git@gitlab.example.com 并接受主机密钥。
• 方法二（全局配置）：Manage Jenkins → Configure Global Security → Git Host Key Verification Configuration → 选择 Accept first connection 或 No verification。

三、创建 Jenkins 项目并配置源码拉取

3.1 新建项目

点击 Jenkins 首页左上角的 New Item → 输入任务名称 → 选择项目类型：

• Freestyle project：适合简单构建，通过界面点选配置。
• Pipeline：适合复杂流水线，通过脚本（Jenkinsfile）定义所有步骤。

本文会分别介绍两种类型的配置方法。

3.2 方式一：Freestyle 项目

3.2.1 配置源码管理

进入项目配置页面 → 找到 Source Code Management 部分：

1. 选择 Git 单选按钮。

2. Repository URL：填写仓库地址（HTTPS 或 SSH 格式均可）。

   • HTTPS 示例：https://github.com/yourname/your-repo.git
   • SSH 示例：git@github.com:yourname/your-repo.git
3. Credentials：下拉选择第 2 步创建的凭证（如 my-git-https-cred 或 my-ssh-cred）。
4. Branches to build：指定分支，例如 */main 或 */master。

3.2.2 配置构建步骤

滚动到 Build 部分 → 点击 Add build step → 选择 Execute shell（Linux）或 Execute Windows batch command（Windows）。

在命令框中输入带有中文注释的编译脚本。例如 Maven 项目：

# 进入当前工作空间（Jenkins 已经自动切换到此目录）
echo "当前目录: $(pwd)"

# 显示 Git 分支信息（可选）
git branch

# 开始 Maven 编译，跳过单元测试
echo "开始编译项目..."
mvn clean package -DskipTests

# 编译完成
echo "编译完成，生成的 JAR 包位于 target/ 目录"

如果是 Node.js 项目：

# 安装依赖
echo "安装 npm 依赖..."
npm install

# 执行构建
echo "执行项目构建..."
npm run build

# 构建完成
echo "构建产物已生成"

保存配置后，点击项目页面的 立即构建 即可测试。

3.3 方式二：Pipeline 项目

Pipeline 项目将整个构建流程以代码形式定义，更易维护和版本控制。

3.3.1 新建 Pipeline 项目

New Item → 输入名称 → 选择 Pipeline → OK。

3.3.2 编写 Pipeline 脚本

在项目配置页面找到 Pipeline 部分 → Definition 选择 Pipeline script → 将以下带中文注释的脚本粘贴到输入框：

pipeline {
    // 使用任何可用的 Jenkins Agent（节点）
    agent any

    // 定义构建的阶段
    stages {
        // 阶段1：从 Git 仓库拉取代码
        stage('拉取代码') {
            steps {
                // 使用 Git 插件拉取代码
                // branch: 要拉取的分支名称（根据你的实际情况修改）
                // credentialsId: 第2步中填写的凭证 ID（必须完全一致）
                // url: 你的 Git 仓库地址
                git branch: 'main',
                    credentialsId: 'my-git-https-cred',   // 替换成你的凭证ID
                    url: 'https://github.com/yourname/your-repo.git'
                
                // 拉取成功后输出提示
                echo "代码拉取成功！"
            }
        }

        // 阶段2：编译构建（以 Maven 项目为例）
        stage('编译构建') {
            steps {
                // 执行 Shell 命令（如果是 Windows，将 sh 改为 bat）
                sh '''
                    echo "开始编译..."
                    mvn clean package -DskipTests
                    echo "编译完成"
                '''
                // 如果是 Node.js 项目，替换为：
                // sh 'npm install && npm run build'
            }
        }

        // 阶段3：运行单元测试（可选）
        stage('运行测试') {
            steps {
                sh 'mvn test'
                echo "单元测试执行完毕"
            }
        }
    }

    // 构建后处理（无论成功或失败都会执行）
    post {
        // 总是执行：清理工作空间
        always {
            cleanWs()   // 删除本次构建的工作空间
            echo "已清理工作空间"
        }
        // 仅构建成功时执行
        success {
            echo "🎉 恭喜！构建成功！"
        }
        // 仅构建失败时执行
        failure {
            echo "❌ 构建失败，请检查控制台日志。"
        }
    }
}

3.3.3 使用 Jenkinsfile 从仓库加载（更佳实践）

将上述 Pipeline 脚本保存为 Jenkinsfile 并提交到你的 Git 仓库根目录。然后在 Jenkins 项目配置中：

• Definition 选择 Pipeline script from SCM
• SCM 选择 Git
• 填写仓库 URL 和凭证，Script Path 填写 Jenkinsfile

这样做的好处是 Jenkinsfile 可以和代码一起版本管理，修改流程无需在 Jenkins 界面操作。

四、常见问题与解决方法（中文提示）

五、触发自动构建（补充）

如果你希望代码推送后 Jenkins 自动拉取并编译，可以通过以下两种方式实现：

5.1 Webhook（推荐）

• 在 Git 仓库（GitHub/GitLab/Gitee）中配置 Webhook，URL 为 http://<jenkins_ip>:8080/github-webhook/（GitHub）或 /gitlab-webhook/（GitLab）
• 在 Jenkins 项目中勾选 Build when a change is pushed to GitLab/GitHub

5.2 Poll SCM（轮询）

• 项目配置 → Build Triggers → 勾选 Poll SCM
• 输入 cron 表达式，例如 * * * * *（每分钟检查一次，不推荐生产环境）