零基础搭建 Jenkins CI/CD 流水线

知识分享

2026-06-16 18:00

11 阅读

前言

不少团队希望引入自动化构建和部署来提升效率，但 Jenkins 的配置对新手来说容易卡在各种报错上。
本文围绕 Jenkins CI/CD 展开，从零开始教你安装 Jenkins、配置一条能拉取 Git 代码、自动构建并部署到测试服务器的流水线。
全文步骤均可直接复制执行，即使你从未接触过持续集成也能跟着完成。

第一步：准备环境和安装 Jenkins

先确认你的服务器满足基础条件

操作系统：Ubuntu 20.04 或 CentOS 7 以上
已安装 Java 8 或 11（Jenkins 依赖 JVM 运行）
能够访问外网，用于下载插件和代码

安装 Jenkins（以 Ubuntu 为例）

# 添加 Jenkins 官方源并导入密钥
wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -
sudo sh -c 'echo deb https://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'

# 更新并安装
sudo apt update
sudo apt install openjdk-11-jdk jenkins -y

# 启动服务并设置开机自启
sudo systemctl enable jenkins
sudo systemctl start jenkins

安装完成后，通过 sudo systemctl status jenkins 确认服务处于 active (running) 状态。
初始密码位于 /var/lib/jenkins/secrets/initialAdminPassword，用 cat 查看并保存好，稍后第一次登录需要使用。

第二步：初始化 Jenkins 并安装必要插件

浏览器访问 http://你的服务器IP:8080，输入初始密码，按界面提示：

选择“安装推荐的插件”——这样能自动装好 Git、Pipeline、Blue Ocean 等常用插件。
创建管理员账号，记住用户名和密码。
实例配置保持默认（Jenkins URL 填写服务器IP或域名）。

注意：如果插件安装一半超时或失败，可以稍后手动去“系统管理 → 插件管理 → 可选插件”里补装：

Git（克隆代码必需）
Pipeline（流水线支持）
SSH Agent（后续部署到远程服务器可用）

第三步：创建你的第一条流水线任务

点击 Jenkins 首页的“新建任务”。
输入任务名称，比如 my-first-pipeline。
选择“流水线（Pipeline）”，点击确定。

进入任务配置页，往下翻到“流水线”区域，把定义改为“Pipeline script from SCM”。
这样 Jenkins 会从你的 Git 仓库读取流水线脚本（Jenkinsfile）。

SCM：选择 Git
Repository URL：填入你的 Git 仓库地址（比如 GitHub 的 HTTPS 链接）
Credentials：如果仓库需要认证，点击添加，填入用户名和密码（或令牌）
分支：默认 */master，按需改为 main 或其他分支
Script Path：保留默认的 Jenkinsfile

点击保存。

第四步：编写 Jenkinsfile（流水线脚本）

在你的项目根目录下新建一个名为 Jenkinsfile 的文件，内容如下（以 Node.js 项目为例）：

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Build') {
            steps {
                sh 'npm install'
                sh 'npm run build'
            }
        }
        stage('Deploy') {
            steps {
                sh 'scp -r dist/* user@your-server:/var/www/html/'
            }
        }
    }
}

说明：

Checkout 阶段自动拉取最新代码。
Build 阶段执行 npm install 和构建命令。
Deploy 阶段将生成的静态文件通过 scp 复制到远程 Web 服务器目录。

如果你的项目不是 Node.js，请替换对应命令（如 Maven 项目用 mvn clean package，Python 项目用 pip install 等）。

将 Jenkinsfile 提交到 Git 仓库主分支。

第五步：触发构建并查看结果

回到 Jenkins 任务页面，点击“立即构建”。
稍等几秒，左侧会出现一个构建历史记录。

点击最新的构建编号（如 #1），再点“控制台输出”，可以看到详细日志。
如果一切顺利，你会在日志末尾看到 Finished: SUCCESS。

验证部署是否生效：如果部署阶段使用 scp 上传到了远端 Web 服务器，直接访问该服务器的 IP 或域名，应该能看到更新后的页面。

常见问题与避坑

Q1：Jenkins 构建时提示 command not found？
需要在 Jenkins 全局工具配置中设置 Node.js、Maven 等工具的路径。进入“系统管理 → 全局工具配置”，找到对应的工具（如 NodeJS），添加安装版本并保存。同时确保构建节点上确实安装了该命令。

Q2：SCP 连接远程服务器报 Permission denied (publickey)
解决方案：在 Jenkins 服务器上生成 SSH 密钥对（ssh-keygen -t rsa），将公钥添加到目标服务器的 ~/.ssh/authorized_keys 中。然后在 Jenkins 的凭据中添加私钥文件，在流水线中使用 sshagent 插件来加载凭据。

Q3：流水线一直卡在 checkout scm 不往下走
常见原因是插件未安装或版本不匹配。去“系统管理 → 插件管理”检查 Git 和 Pipeline: SCM Step 插件是否已安装。如果还不行，尝试在流水线脚本里显式使用 git url: '仓库地址', credentialsId: 'xxx' 的方式。

Q4：构建成功但部署的内容没变化
先确认 Build 阶段输出的文件路径是否正确。比如 npm run build 生成的文件默认在 dist 目录，而部署命令里 scp 的源路径是否准确。可以在构建日志中加上 sh 'ls -la dist/' 来确认。

总结

到此你已经完成了一条最基本的 Jenkins CI/CD 流水线：代码推送后自动被 Jenkins 拉取、构建并部署到远程服务器。
后续可以根据需要添加测试、邮件通知、多环境部署等环节。
遇到异常时先回看本文的避坑部分，大部分新手问题都在上面覆盖到了。
如果你用的是宝塔面板或其他面板，建议先确认 Jenkins 使用的端口（默认 8080）没有被面板防火墙拦截，否则外部无法访问 Jenkins 控制台。

自动化运维平台搭建实战：Ansible从入门到批量部署

Ansible批量管理入门：从安装到免密批量执行命令

前言