SonarQube怎么配置代码扫描 SonarQube扫描任务执行失败怎么解决

在本机能扫，放进CI就失败，先查两边运行环境；日志已经上传报告，项目页面却没更新，就去看后台处理。SonarQube扫描涉及几个连续环节，不能只凭流水线变红判断故障。配置时把项目标识、扫描目录和凭据对应好，出错后再沿日志找到中断位置，通常比反复修改整份配置更有效。

一、SonarQube怎么配置代码扫描

扫描由执行机器上的SonarScanner发起，服务器负责接收并处理报告。因此，除了页面里的项目设置，还需要准备扫描器、源码及相应构建环境。

1、建立项目并准备访问凭据

已有项目直接使用原项目标识即可。新建时应记录Project key，后面的扫描配置要与它一致。令牌所属账号需要具备执行分析的权限，仅能浏览项目还不够。

①点击【Create Project】→【Local Project】，填写项目名称和【Project key】，完成创建。

②点击用户菜单中的【My Account】→【Security】，选择适合的令牌类型后点击【Generate】。

令牌通过CI凭据功能传入，避免写进仓库。使用SonarScanner CLI时可配置SONAR_TOKEN环境变量；其他扫描器应按各自支持的方式传递，不宜直接复制整套CLI参数。

2、按工程类型选择扫描方式

Maven、Gradle工程优先使用对应扫描集成，便于取得构建信息；.NET工程需要将扫描步骤与构建过程配合。下面的配置文件方式主要针对SonarScanner CLI。

在工程根目录建立sonar-project.properties，填写sonar.projectKey和sonar.host.url。源码在src目录时，可设置sonar.sources=src；存在独立测试目录时，再按实际目录配置测试范围。文件编码不同于环境默认值的，可通过sonar.sourceEncoding明确指定。

进入该目录后运行sonar-scanner。不要只复制别人的路径：配置里的相对路径以分析基准目录为依据，CI工作目录改变后，原来的src未必仍指向源码。

二、SonarQube扫描任务执行失败怎么解决

保留失败时的完整日志，先看它是否已经生成并上传报告。报告上传之前的问题，主要在执行端排查；上传之后处理失败，则要转到服务器任务记录。

1、连接或认证阶段失败

超时、连接拒绝、证书错误和权限错误，处理方向不同。应在真正运行扫描的机器上验证连接，本机浏览器能打开页面，不能证明CI节点同样可达。容器内的localhost也通常不是宿主机上的SonarQube。

①进入【My Account】→【Security】，检查所用令牌是否到期或已撤销。

②打开目标项目的【Project Settings】→【Permissions】，核对账号的【Execute Analysis】权限。

若日志报证书信任错误，应配置扫描器所用的信任库；若是报告上传时返回403，还要检查代理或网关是否拦截请求，不能只重新生成令牌。

2、分析器启动后失败

这时应从第一条明确异常往前看，检查扫描器、运行时与分析器的兼容要求。业务项目使用的Java版本，不一定就是扫描器运行所需的版本。

Java工程提示缺少编译类时，先确认构建成功，再核对sonar.java.binaries对应的目录。需要的编译产物没有准备好，不能通过排除全部Java源码来“修复”。CLI日志不足时，可以临时运行sonar-scanner-X查看详细信息，排查结束后恢复正常日志级别。

3、报告上传后后台处理失败

扫描器提示EXECUTION SUCCESS，只能说明执行端完成了相应工作。服务器还需要处理报告，任务仍在排队时，页面暂未更新不一定是故障。

①打开【Project Settings】→【Background Tasks】，按提交时间找到本次任务。

②对失败任务点击【Show Error Details】，查看处理异常。

③打开【Show SonarScanner Context】，核对这次任务使用的参数。

服务器端可结合任务时间与标识检查ce.log。确认是内存或其他资源问题后，再调整对应资源，不要同时给扫描器和服务器盲目增加内存。

4、扫描完成但质量门禁未通过

如果流水线等待质量门禁结果，分析已经成功，仍可能因覆盖率、新增问题等条件不达标而失败。此时继续检查网络和令牌，没有多少帮助。

①打开项目【Overview】，查看分析时间与【Quality Gate】结果。

②展开未通过条件，核对具体指标和阈值。

还应分清“门禁未通过”和“等待门禁超时”。后者需要继续查看后台任务及等待设置，不能直接当作代码质量不合格。

三、恢复扫描后怎样检查有没有漏扫或扫错

有些调整能让任务变绿，却也改变了扫描内容。例如扩大排除范围后不再报错，原本需要检查的目录也一起消失了。恢复后应核对结果，不能停在退出码为零。

1、确认结果进入正确项目

项目显示名称可以修改，Project key才是扫描归属的重要依据。测试配置时若沿用了别的项目标识，结果可能已经上传，只是没有进入当前查看的项目。

①在【Overview】中核对最近分析时间。

②进入【Project Settings】→【Background Tasks】，查看本次任务的【Show SonarScanner Context】，确认项目标识。

2、检查最终参数及文件数量

命令行参数通常会覆盖配置文件和页面中的同名设置。本地改好了，CI仍使用旧值，就要回到流水线检查。应同时对照日志中的文件数量、识别语言和排除情况，确认变化有合理原因。

①打开本次任务的【Show SonarScanner Context】，对照源码、测试及排除参数。

②进入项目【Code】页面，检查预期目录和文件是否出现在分析结果中。

3、用原提交再验证一次

环境修复后，尽量先对原来的代码提交重跑。若同时换了代码、扫描器和配置，即使成功，也很难判断哪项修改起了作用。确认修复有效后，再把扫描配置与构建流程一起保存，并记录所用版本，减少本机和CI之间的差异。

总结

扫描任务变红时，最有用的信息是它停在了哪一步。把执行日志、代码提交和后台任务对应起来，故障范围会清楚得多。任务恢复后，再看一眼扫描目录与文件数量，避免为消除报错漏掉需要检查的代码。质量门禁则应按实际未通过的条件处理。希望这些方法能帮大家少做几轮无效重跑；如有相关需求，欢迎进一步沟通。