SonarQube怎么导入外部Issue报告 SonarQube外部Issue导入后不显示如何排查

SonarQube可以把第三方静态分析工具产生的问题导入项目，与自身检测出的Issue一起查看。对于已经适配SonarQube的工具，可以使用对应的报告参数；其他分析器可以转换成Generic Issue格式或SARIF格式再导入。报告文件已经生成但SonarQube页面没有显示问题时，要先确认Scanner实际读取到了报告，再检查报告格式、源码路径、分析范围和当前查看的分支，不能只看报告文件是否存在。

一、SonarQube怎么导入外部Issue报告

外部Issue是在执行SonarScanner分析时一起导入的，并不是在SonarQube网页中单独上传。Generic Issue和SARIF使用的分析参数不同，配置前要先确认第三方工具实际生成了哪一种报告。

1、使用Generic Issue格式导入

①让第三方分析工具先生成符合SonarQube Generic Issue格式的JSON报告。

②检查报告顶层是否包含【rules】和【issues】。

③确认每条Rule具有对应的规则标识和分析器信息。

④检查Issue引用的【ruleId】能够对应报告中的规则。

⑤检查【primaryLocation】中的【filePath】和问题描述。

⑥在项目扫描参数中加入【sonar.externalIssuesReportPaths】。

⑦把参数值设置为报告文件或报告目录，例如【reports/external-issues.json】。

⑧执行SonarScanner重新分析项目。

报告路径可以使用绝对路径，也可以使用相对于【sonar.projectBaseDir】的路径。使用相对路径时，要按照Scanner实际启动目录计算，而不是按照SonarQube服务器安装目录计算。

2、使用SARIF报告导入

①确认第三方分析器能够输出【SARIF 2.1.0】。

②检查报告文件编码为【UTF-8】。

③确认【version】为【2.1.0】。

④检查【runs[].tool.driver.name】。

⑤检查Issue对应的【ruleId】和【message.text】。

⑥在扫描参数中配置【sonar.sarifReportPaths】。

⑦填写一个或多个SARIF报告路径。

⑧重新执行项目分析。

SARIF和Generic Issue不要使用同一个参数。把SARIF文件填入【sonar.externalIssuesReportPaths】并不会自动按照SARIF格式解释。

3、导入已支持的第三方分析器报告

①先确认当前语言和分析器是否已有SonarQube专用集成。

②进入项目的【Project Settings】。

③打开【General Settings】中的外部分析器相关配置。

④找到当前工具对应的Report Files设置。

⑤填写实际报告文件路径。

⑥也可以在CI/CD扫描命令中设置对应的【sonar.xxx.reportPaths】参数。

⑦先运行第三方分析器生成报告。

⑧确认报告生成完成后再启动SonarQube分析。

SonarQube本身不会替你运行PMD、Checkstyle、ESLint等第三方工具，它负责读取已经产生的报告，所以CI任务顺序也要保证外部分析先完成。

二、SonarQube外部Issue导入后不显示如何排查

报告不显示时，先看Scanner日志。只要分析阶段没有真正读取报告，后面调整SonarQube网页中的Issue筛选条件通常没有作用。

1、确认Scanner是否读取报告

①重新执行一次SonarScanner。

②检查控制台分析日志。

③搜索【external】、【SARIF】或当前分析器名称。

④确认日志能够找到配置的报告文件。

⑤如果提示文件不存在，检查【sonar.externalIssuesReportPaths】或【sonar.sarifReportPaths】。

⑥相对路径异常时，确认当前【sonar.projectBaseDir】。

⑦需要更详细信息时开启【sonar.verbose=true】。

⑧重新分析并查看DEBUG级日志。

CI环境中很容易出现“报告在前一个Job生成，但Scanner所在Job没有这个文件”的情况，因此还要确认报告已经作为Artifact或工作目录内容传递到扫描阶段。

2、检查报告中的源码路径

①打开外部Issue报告。

②找到一个确定应该显示的问题。

③查看它对应的【filePath】或SARIF中的源码位置。

④确认这个路径能够对应当前SonarQube项目中的实际源码文件。

⑤检查路径中是否混入另一台机器的绝对目录。

⑥Linux环境注意文件名大小写。

⑦确认目标文件没有被【sonar.exclusions】排除。

⑧重新扫描后查看该文件是否已经进入分析范围。

外部Issue最终要关联到本次分析中的源码。报告指向【src/main/a.c】，而Scanner实际分析的是另一套目录或文件已经被排除时，问题就无法正常挂到对应文件上。

3、检查报告格式和必填字段

①Generic Issue报告先检查JSON语法是否完整。

②确认【rules】和【issues】不是空数组。

③核对【ruleId】引用关系。

④检查【primaryLocation】中的文件和行号。

⑤使用较新SonarQube版本时，按照当前Generic Issue格式生成规则属性和Impact信息。

⑥SARIF报告确认版本为【2.1.0】。

⑦检查必填的Tool、Rule和Message字段。

⑧重新生成报告后再次扫描。

Generic Issue格式在SonarQube 10.3之后发生过调整，使用旧工具长期保存的转换脚本时，应先核对当前服务器版本对应的报告格式。

三、报告已被读取但页面仍找不到Issue怎么继续检查

Scanner日志已经明确执行了外部报告导入后，问题就要转向分析分支、Issue页面和报告中的目标文件。外部规则的管理方式也和SonarQube内置规则不同。

1、确认查看的是同一个分支

①记录执行分析时的Branch或Pull Request。

②打开SonarQube项目页面。

③检查当前顶部选择的分支。

④如果CI扫描的是功能分支，切换到对应分支。

⑤PR分析则进入对应Pull Request结果。

⑥重新打开【Issues】页面查看。

扫描结果只会提交到当前分析对应的分支或PR，在Main Branch查看另一个分支刚导入的问题，自然不会出现。

2、检查Issue筛选条件

①进入项目【Issues】。

②清除当前Status、Severity和Rule等筛选条件。

③把Scope扩大到当前项目全部Issue。

④检查是否存在External相关问题。

⑤按文件路径或Rule ID缩小范围。

⑥打开目标源码文件查看对应问题位置。

外部Issue能够出现在项目分析结果中，但外部规则不会像SonarQube自己的规则一样进入【Rules】页面，也不会通过Quality Profile控制启用和关闭。因此在Rules里搜索不到第三方规则，并不代表报告导入失败。

3、确认目标文件进入了本次分析

①使用DEBUG分析日志检查Indexed Files。

②找到报告中出现问题的源文件。

③确认它被识别为Source，而不是完全没有进入分析。

④检查【sonar.sources】。

⑤检查【sonar.inclusions】和【sonar.exclusions】。

⑥测试代码还要核对Test范围配置。

⑦修正分析范围以后重新运行Scanner。

如果大量外部Issue集中在一个被排除目录，可以优先修正分析范围，而不是逐条修改报告。

总结

SonarQube导入外部Issue时，可以根据报告类型使用Generic Issue、SARIF或第三方分析器专用参数，并在SonarScanner执行项目分析时读取报告。导入后没有显示，应先通过Scanner日志确认报告是否真正被读取，再检查源码路径、报告格式和分析范围；日志已经确认导入后，则继续核对当前分支和Issues页面筛选条件。外部规则不会按照普通Quality Profile规则管理，也不要把Rules页面搜索不到规则误判为导入失败。如需进一步了解SonarQube外部Issue导入、第三方分析报告配置与Issue显示异常排查方法，欢迎联系咨询。