jenkins安装后必须配置核心插件才能运行基本功能：git plugin（支撑源码拉取）、matrix project plugin（支持多配置构建）、ssh相关插件（实现远程部署）、pipeline utility steps（解析json/yaml），且需确保插件版本与jenkins主版本兼容、镜像源配置正确并提交生效、凭据统一通过全局凭据管理添加。
直接装完 jenkins 不等于能用——插件没配好，连 Git 拉代码、Maven 打包、SSH 推部署这些基本动作都跑不起来。核心问题不在安装步骤对不对，而在于「哪些插件必须装」「装错版本会卡在哪」「配置路径写错一个字母就白忙活」。
哪些插件属于“不装就动不了”的硬依赖
刚输完初始密码进首页，别急着点“Install suggested plugins”。那套默认组合看着全，但实际生产中常缺关键项，或带了冗余插件拖慢启动。
-
Git plugin：不是可选，是刚需。没它，Source Code Management里根本看不到 Git 选项；即使手动填 URL，构建时也会报java.lang.ClassNotFoundException: hudson.plugins.git.GitSCM -
Matrix Project Plugin：Jenkins 2.346+ 默认不启用多配置项目（Matrix），但很多老 Pipeline 或参数化构建依赖它。漏装会导致 “This project is not configured to use matrix builds” 报错 -
SSH Build Agents或OpenSSH Credentials Plugin：要走 SSH 连远程服务器部署，这两个至少得有一个。后者更现代，支持密钥文件 + 密码双因子；前者只认 OpenSSH 格式私钥，且不兼容新版本openssh-9.0+的默认密钥格式 -
Pipeline Utility Steps：写 Groovy 脚本解析 JSON/YAML（比如读取package.json版本号）时必用。没它，readJSON、shelly等 step 直接报 unresolved symbol
插件源被墙/加载超时？换镜像源不是加个 URL 就完事
在 Manage Jenkins → Plugin Manager → Advanced 里改 Update Site，填 https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json 是常见做法，但容易忽略两个坑：
- 该镜像只同步官方 update center 的“稳定版”插件，
beta或experimental分支的插件（如新版Configuration as Code）不会出现，搜不到别硬刷 - 填完必须点
Submit，再点Check now—— 否则页面缓存仍用旧地址，后台日志里持续打印Failed to load update center from https://updates.jenkins-ci.org/update-center.json - 如果 Jenkins 运行在内网无外网环境，得提前下载
.hpi文件离线安装。注意：插件有依赖链，比如git插件依赖apache-httpcomponents-client-4-api，漏装后者，Git 配置页打不开
插件装完不生效？检查三处隐性配置点
点了 Install，等进度条走完，重启 Jenkins，结果新建任务还是找不到 Git 选项——大概率栽在这三个地方：
-
/var/lib/jenkins/plugins/目录下对应插件名目录（如git/）里，必须存在git.hpi和解压后的WEB-INF/子目录。如果只有.hpi没解压，说明 Jenkins 启动时权限不足，chown -R jenkins:jenkins /var/lib/jenkins/plugins再重启 - Jenkins 启动用户不是
jenkins（比如改成root），但插件目录属主仍是jenkins，导致加载失败。查日志：tail -f /var/log/jenkins/jenkins.log | grep -i "failed to load plugin" - 插件版本与 Jenkins 主版本不兼容。例如 Jenkins 2.354 要求
git插件 ≥ 4.11.4；若手动上传了 4.2.2，反而因 API 变更报NoClassDefFoundError: hudson.plugins.git.util.BuildData
插件配置最易被跳过的细节：所有凭据（Git token、SSH 私钥、Docker registry password）必须通过 Credentials → System → Global credentials 添加，不能直接写死在 job 配置里。否则流水线执行时会提示 Cannot find credential with id 'xxx'，而这个 ID 在 Pipeline 脚本里是字符串字面量，拼错大小写都算失败。
