当前位置：首页 > news >正文

Jenkins全链路教程——Jenkins项目创建与基础构建

news 2025/8/8 8:43:17

一、Freestyle项目“为什么值得学？”

1.1 它到底是什么？

Freestyle项目是Jenkins中最传统、最直观的任务类型，通过“填空式”界面完成配置（比如拉代码→编译→打包）。简单说，它像一个“任务清单”——你只需在界面上勾选/填写关键参数，Jenkins就会按顺序帮你执行。

举个🌰：如果你要做“前端项目自动打包”，Freestyle会帮你：
① 从Git拉最新代码→② 安装npm依赖→③ 执行打包命令→④ 保存结果。

1.2 它的“优缺点”很真实！

优点（新手友好）：
✅ 操作门槛低：无需学复杂的Pipeline语法（比如写Jenkinsfile），点点鼠标就能配置；
✅ 灵活性高：支持Git/SVN等源码工具，兼容Shell/Python/批处理等脚本；
✅ 可视化强：每个步骤的配置都能在界面上直接看到，方便调试。

缺点（适用场景有限）：
❌ 复杂任务难扩展：涉及多阶段并行（比如微服务部署）或动态判断时，配置会很繁琐；
❌ 配置不可复用：每个项目独立配置，无法像Pipeline那样通过代码共享模板；
❌ 日志查看麻烦：所有步骤的输出混在一起，找问题需要“大海捞针”。

1.3 它最适合这些场景！

• 个人/小团队的单模块项目（比如一个Java后台服务、一个H5活动页）；
• 需快速验证的临时任务（比如测试新接口的自动化打包）；
• 完全不懂CI/CD的纯新手（通过界面操作理解“自动化构建”的底层逻辑）。

二、Freestyle项目创建全流程

2.1 新建Freestyle项目

打开Jenkins首页→点击左侧“新建任务”→输入项目名称（如my-first-freestyle，建议用英文+用途命名）→选择“Freestyle project”→点击“确定”。

（✨ 小提示：名称尽量简洁，避免中文空格，方便后续管理～）

2.2 配置“常规”信息

在项目配置页的“常规”模块：

• 描述：填写项目说明（如“前端H5活动页自动打包，用于测试环境部署”），方便后续维护；
• 丢弃旧的构建：勾选“限制构建的保留天数”（建议7天）和“限制构建的最大个数”（建议20个），避免磁盘被日志占满；
• 参数化构建过程（可选）：若需动态传参（如指定分支名），勾选“此项目参数化”→添加“字符串参数”（名称BRANCH，默认值main）。

2.3 配置“源码管理”

在“源码管理”模块，必须选择你的代码托管工具（以最常用的Git为例）：

关键配置项说明：

• Repository URL：填写Git仓库地址（格式：https://github.com/用户名/仓库名.git 或 git@github.com:用户名/仓库名.git）；
❗️避坑：若用SSH协议（git@...），需提前在Jenkins服务器配置SSH密钥（将服务器公钥添加到GitHub/GitLab的“SSH Keys”中）；
• Credentials（凭证）
：若仓库私有，必须添加凭证→点击“添加→Jenkins”→选择凭证类型：
- • 选“Username with password”：填Git账号+密码（或GitHub的Personal Access Token，需勾选repo权限）；
- • 选“SSH Username with private key”：填SSH用户名（如git），并粘贴服务器私钥（路径：~/.ssh/id_rsa）；
• Branches to build：填写要构建的分支名（默认main，若用了参数化，可填${BRANCH}动态获取）；

2.4 设置“构建触发器”

在“构建触发器”模块，根据需求选择触发方式：

① 轮询SCM

• 填写“Schedule”（Cron表达式），格式：分时日月周；
🔍 示例：H/5 * * * *表示“每5分钟检查一次”（H是“哈希分散”，避免所有任务同时执行）；
❗️避坑：轮询会增加服务器压力，仅推荐测试环境使用。

② GitHub hook trigger

• 需安装“GitHub Integration”插件（若未安装，在“系统管理→插件管理”搜索安装）；
• 在GitHub仓库→“Settings→Webhooks”→点击“Add webhook”；
- • Payload URL：http://你的Jenkins公网IP:8080/github-webhook/（若Jenkins在局域网，需用Ngrok等工具暴露公网地址）；
- • Content type：选application/json；
- • 触发条件：选“Just the push event”（仅推送代码时触发）；
• 回到Jenkins项目配置页→勾选“GitHub hook trigger”。

2.5 配置“构建环境”

在“构建环境”模块，根据项目需求勾选：

① 注入工具路径

• 若项目需Node.js（前端打包），需先在“系统管理→全局工具配置→NodeJS”添加Node版本（如v18.18.0）→勾选“Provide Node & npm bin/ folder to PATH”；
• 若需Maven（Java项目），在“全局工具配置→Maven”添加Maven版本（如3.8.8）→勾选“Install automatically”。

② 清理工作区

• 勾选“Delete workspace before build starts”，构建前自动删除旧文件（特别适合前端项目，避免node_modules版本冲突）。

③ 注入敏感信息

• 勾选“Use secret text(s) or file(s)”→点击“添加→Secret text”→填写“变量名”（如API_TOKEN）和“值”（你的Token）→在构建脚本中用$API_TOKEN调用。

2.6 添加“构建步骤”

在“构建”模块→点击“添加构建步骤”，根据项目类型选择：

① 前端项目（Vue/React，用Node.js）
选择“执行Shell”，输入：

# 切换npm源（避免超时）  
npm config set registry https://registry.npmmirror.com  # 安装依赖（--force解决版本冲突）  
npm install --force  # 打包（生产环境）  
npm run build -- --mode production  # 可选：压缩打包结果（方便后续部署）  
tar -czf dist.tar.gz -C dist .

❗️避坑：若npm install报错“权限不足”，在命令前加sudo（或调整npm全局目录权限）。

② 后端Java项目（Maven）
选择“执行Shell”，输入：

# 清理并编译（跳过测试）  
mvn clean package -Dmaven.test.skip=true  # 复制jar包到部署目录  
cp target/demo-0.0.1-SNAPSHOT.jar /data/deploy/

❗️避坑：若提示“mvn: command not found”，检查“全局工具配置”中Maven路径是否正确（路径示例：/usr/local/maven-3.8.8/bin/mvn）。

2.7 添加“构建后操作”

在“构建后操作”模块，可添加：

① 归档制品（保存打包结果）
勾选“Archive the artifacts”→填写“Files to archive”（如dist.tar.gz或target/*.jar）→勾选“Allow empty archive”（允许无制品时不报错）。

② 发送通知（失败提醒可选）
安装“Email Extension”插件→勾选“Editable Email Notification”→配置SMTP服务器（如QQ邮箱：smtp.qq.com，端口465）→填写收件人邮箱→设置“Trigger”为“Failure”（仅失败时通知）。

2.8 保存配置→测试构建

所有配置完成后→点击页面底部“保存”→返回项目首页→点击左侧“立即构建”→观察“构建历史”中的状态：

• 蓝色球：构建成功；
• 红色球：构建失败；
• 黄色球：不稳定（如测试部分失败）。

2.9 查看构建日志

点击构建记录→“控制台输出”，重点检查：

• 源码拉取阶段：是否有“Authentication failed”（凭证错误）或“Branch not found”（分支名错误）；
• 依赖安装阶段：是否有“404 Not Found”（包不存在）或“Timeout”（网络问题）；
• 构建脚本阶段：是否有“Command not found”（环境变量未配置）或“Syntax error”（脚本语法错误）。

2.10 解决常见问题

问题现象	可能原因	解决方法
Git拉取失败：“Authentication failed”	凭证错误（密码过期/Token无权限）	检查凭证是否正确，重新添加Token（GitHub需勾选`repo`权限）
构建触发失败：“Webhook未收到请求”	Jenkins公网IP错误/Ngrok未启动	用`curl http://你的JenkinsIP:8080/github-webhook/`测试连通性
Node.js“command not found”	全局工具配置未添加/路径错误	在“系统管理→全局工具配置”检查Node版本和路径是否正确