接手一个多分支流水线作业时，如果发现新分支推送到Git仓库后，Jenkins一直没有反应，我会先做一件事：打开那个作业的“扫描日志”，看Jenkins实际看到了什么。很多情况下，不是构建配置有大改动，而是分支发现这一步就出了问题。
先看扫描日志，凭据权限是第一个检查点
多分支流水线扫描不到新分支，最常见的原因不是Jenkins配置出错，而是访问Git仓库使用的凭据没有读取新分支的权限。Jenkins会以配置在作业里的凭据身份去执行git ls-remote，如果该账号在GitLab或GitHub上只有旧分支的访问权，而新分支来自另一个项目路径或受保护分支，扫描结果就会只显示旧分支。检查时可打开多分支作业的“扫描日志”，查看到“Could not list branches”或“Permission denied”之类的关键字，同时确认该凭据对应账号是否被添加为仓库成员，以及新分支是否在允许查看的组规则内。不要只凭手动git clone成功就认定凭据有效，因为本机可能缓存了其他账号的SSH key。
这段日志同时也会告诉您Jenkins实际访问的仓库地址，以及最终有没有把新分支加入候选列表。如果报错信息指向权限问题，先不要急着改作业配置，而是回到Git服务端核对账号权限。注意受保护分支的规则可能比普通分支更严格，即使该账号是仓库成员，也可能看不到受保护的新分支。
容易误判的地方：手动clone成功不代表凭据有效
很多人会在服务器上用git clone试一下，克隆成功就认为凭据没问题。但命令行环境里可能加载了SSH agent，或者~/.ssh/config里指定了另一个key，这跟Jenkins作业里绑定的凭据不是同一套。需要单独确认。
git ls-remote git@gitlab.example.com:team/project.git在服务器上执行这条命令时，要确保命令使用的是Jenkins作业里绑定的那个用户身份。输出里如果没有新分支，再检查仓库路径或账号权限。需要注意的是，SSH Key与用户名密码这两类凭据在GitLab上的权限范围不同，受保护分支可能需要维护者权限。
检查分支发现策略里的过滤规则
排除权限问题后，下一个高频原因是分支过滤策略。多数多分支作业会配置“按名称过滤”或“正则过滤”来避免扫描到临时分支，但这个规则可能没覆盖新增的前缀。
如果凭据权限没问题，下一步要检查多分支流水线的“分支来源”中的过滤配置。很多团队会在“按名称过滤”或“按正则过滤”里填写类似release/*或feature/*的表达式，这时新分支只要不符合该模式，就不会出现在扫描结果中，但扫描日志会显示“Did not observe a branch inside the filter list”之类的提示。排查时打开作业配置，查看“分支发现”一栏中是否勾选了“排除已合并的分支”，以及正则表达式是否遗漏了新增分支的前缀。例如原先只有feature，后来起了hotfix开头的分支，表达式没有覆盖hotfix，自然扫不到。建议先用最简单的.*规则做一次测试扫描，确认能发现所有分支后，再逐步收窄范围，避免误排除。
临时放宽过滤条件时，最好在一个非生产环境作业上操作，或者先把原配置截图留存。因为“.*”会扫描仓库里的所有引用，如果远程分支数量很多，扫描时间会变长，也可能刷新出大量之前被过滤掉的旧分支。确认新分支能出现后，记得把正则恢复成原来的格式，并补上hotfix等新增前缀。
扫描触发周期与“立即扫描”
另一个容易忽略的事实是，扫描不是实时的。即使权限和过滤都正常，如果触发周期还没到，新分支也不会出现。
Jenkins扫描新分支并不是实时的，默认周期可能设置为5分钟或更长，甚至有些作业配置成了每天一次。如果新分支刚推送到远端，扫描周期尚未到，Jenkins不会主动去发现它。此时可以在多分支作业页面点击“立即扫描”按钮，手动触发一次仓库索引，然后查看扫描结果是否出现新分支。如果手动扫描能看到，但自动扫描一直没反应，就要检查Multibranch Scan Trigger的配置，确认勾选了“Periodically if not otherwise run”，并合理设置间隔时间。另外还要注意，如果Jenkinsfile中使用了“when { changeRequest() }”之类的条件，虽然分支能被扫描到，但不会触发对应的构建，这会让误以为“扫描不到分支”，实际上分支已经出现在Blue Ocean的分支列表里了。
如果手动扫描能看到，但自动扫描一直没有反应，可以在“Multibranch Scan Trigger”里把间隔调短，比如改成1分钟，观察一段时间。但要注意，频繁扫描会持续请求Git服务端，仓库很大时可能增加服务器负载，建议间隔不要小于5分钟。同时，像“when { changeRequest() }”这类条件，只影响构建触发，不影响分支发现，看日志时要区分这两件事。
仓库地址和本地缓存也可能导致扫描结果过期
如果以上都正常，还需要确认Jenkins实际使用的仓库地址。仓库迁移后，旧地址可能仍然能访问，但只能看到迁移前的分支。打开“Scan Repository Log”，看它实际fetch的是哪个URL，再对比新分支所在仓库的克隆地址。如果发现URL不一致，更新作业里的仓库地址。
另外，Jenkins的工作目录下会保留之前的.git缓存。如果远端分支被删除后又创建了同名分支，或者服务器使用了Git LFS，偶尔会出现本地引用未更新的情况。可以在作业页面的“工作空间”操作里选择“Wipe Out Current Workspace”，清掉工作目录后再扫描。这一步会删除工作空间内未提交的文件，但不会影响构建历史记录。如果作业正在使用该工作空间，需要先停止相关构建，避免清到一半产生文件锁。
按固定顺序排查，把改动记录下来
遇到扫描不到新分支的问题，建议按固定顺序排查而不是这里改一下那里试一下。这里先给出一个顺序，方便回滚：先看扫描日志，再验证凭据权限，然后临时放宽过滤规则，接着手动扫描，如果还不行就新建一个最简单的多分支作业对比。
- 打开多分支作业侧边栏的“查看扫描日志”，看“Looking up branches”之后有没有列出新分支。
- 用凭据ID对应的账号在命令行执行git ls-remote，核对权限和分支列表。
- 把分支发现策略改成“发现所有分支”，过滤正则临时设为.*，扫描一次。
- 如果手动扫描能看到但自动扫描看不到，检查触发周期。
- 最后新建一个只填仓库地址和空正则的多分支作业，用来对比是全局配置问题还是原作业的脏缓存。
每次改动都要记录，因为配置项之间会相互影响。例如同时勾选了“排除已合并的分支”和“需要预合并”，新分支在合入目标分支前就会先被过滤掉，这种组合问题排查起来最费时间。如果新建测试作业能出现新分支，基本可以确定原作业里有其他配置干扰，再逐项回滚对比。
如果上面的步骤都走完了还是不行，就需要看Jenkins与Git服务端的通信是否正常。自建的GitLab如果开启API访问限制，或者插件版本与GitLab版本不兼容，扫描过程可能在拿到分支列表前就中断。这时系统日志里会出现HTTP 403或429响应，可以在“系统管理-系统信息”里核对插件版本，再决定是否调整限流或升级插件。这一步通常放在最后，因为它牵扯因素更多，需要结合环境确认。