SonarQube在网页里看趋势很方便，但到了里程碑评审、对外交付、审计留档，就需要把同一时间点的报告与数据“固化”为文件，并且能说清楚分支口径、筛选条件与拉取时间。否则很容易出现今天导出的数据和下周再看不一致，最后只能靠截图解释，证据强度不够。下面按导出与归档两条线，把操作路径与常见坑一次讲透。

　　一、SonarQube报告怎么导出

　　导出前先想清楚你要交付的是“可阅读的PDF概览”，还是“可复算的明细数据”。PDF更适合管理层阅读，明细数据更适合整改闭环与审计复核。两类导出不要混用，建议同一批次两者都出一份，后续就不怕被追问口径。

　　1、导出Portfolio层面的PDF概览

　　进入【Portfolios】→打开目标Portfolio→在Overview页右上角点击【Portfolio PDF report】→点击【Download】保存PDF；保存时把文件名写成Portfolio名、分支口径或应用口径、导出日期，避免同名覆盖与时间点混淆。

　　2、导出项目问题清单做整改明细

　　进入项目页后点击右上角【帮助】→【Web API】；搜索并打开接口api/issues/search，在参数里至少填componentKeys为项目Key，再按需要填types、severities、statuses等过滤项，点击【Execute】后把响应保存为issues.json，用作问题明细归档与后续比对。

　　3、导出项目指标快照固定某次结论

　　同样在【Web API】里使用/api/measures相关接口，优先导出“指标快照”作为当次评审的结论页数据来源；操作上在Web API页面填component为项目Key，metricKeys填你关心的指标键，执行后保存为measures.json，作为该批次的指标快照。

　　4、导出指标历史用于趋势复盘

　　如果你要归档趋势曲线，不要只截图，建议直接导出历史序列；在Web API里调用api/measures/search_history，填写component、metricKeys与时间范围from到to，执行后保存为measures_history.json，后续可以用同一份数据在本地复画趋势图并做交叉核对。

　　5、导出时把口径写进metadata文件

　　每次导出建议同时落一个metadata.txt，至少写清SonarQube版本、项目Key、分支名、是否PR维度、导出时间、issues筛选条件、metricKeys清单；这样半年后再翻档案，你仍然能复现当时的导出条件，不会靠记忆补口径。

　　二、SonarQube指标与趋势怎么归档

　　归档的目标是“长期可追溯”，而不是“临时能交差”。因为SonarQube会按Housekeeping规则选择性保留历史分析与明细数据，时间久了历史点会被抽稀或清理，所以关键里程碑必须做外部归档。建议把归档做成固定节奏的批次包，并把批次号回写到发布说明或评审纪要里。

　　1、先定一个统一的归档目录结构

　　建议目录三层：项目Key为一级，分支名为二级，批次号为三级；每个批次至少包含measures.json、measures_history.json、issues.json、metadata.txt四类文件，保证快照、趋势、问题明细、口径说明都在同一包里。

　　2、把归档节奏绑定到里程碑与发布节点

　　建议固定三类批次：需求冻结或代码冻结、质量门禁通过、发布打包完成；每个节点都导出一次快照与历史区间，并把批次号写进发布说明或评审纪要，后续追问趋势变化时能直接指向某个批次包。

　　3、用search_history固定趋势时间窗

　　每次归档建议统一一个时间窗，例如最近90天或最近180天，确保不同批次包之间可对齐；同时保留“导出当日的快照”，避免只存历史不存当次结论，导致评审页数据无法复现。

　　4、对关键版本在SonarQube里打事件标记并外部落盘双保险

　　Housekeeping会保留带事件标记的快照更久，因此关键发布建议在项目历史里打Version类事件标记，同时仍然做外部归档，避免只依赖数据库保留策略。

　　5、归档后做一次抽样一致性校验

　　抽查三件事：measures.json是否与页面同分支同时间点一致，issues.json是否与页面同筛选条件一致，measures_history.json是否覆盖你的时间窗且点位合理；抽查通过再把该批次目录打包上传到制品库或文档库，形成只读留档。

　　三、SonarQube报告导出与趋势归档对不上怎么排查

　　导出与归档对不上，优先认为是“口径不一致”，而不是“数据错了”。你要先把分支、时间窗、筛选条件三件事对齐，再判断差异来自统计口径差异还是Housekeeping抽稀导致历史点变化。下面这套顺序能把问题快速收敛到一两项明确原因。

　　1、先核对分支与维度是否一致

　　确认导出与归档使用的是同一个分支，且是否在PR维度下查看；分支不一致时，issues数量与measures快照天然对不上，先把分支口径统一再继续比。

　　2、再核对issues筛选条件是否与页面一致

　　最常见差异来自statuses与types不一致，例如页面只看Open但接口取了All，或页面看Bugs但接口混入Code Smells；建议把接口参数原样写进metadata.txt，再在页面用同条件复现一次。

　　3、区分快照与历史的对比对象

　　measures.json是导出当下的快照，measures_history.json是时间序列；issues.json往往是“按当前筛选条件返回的集合”。如果你拿“当前集合”去对比“过去某一天的历史点”，看起来就会不一致，必须先定义你要对齐的是哪个时间点。

　　4、怀疑历史点缺失时先检查Housekeeping影响

　　如果你对比的是较久以前的区间，Housekeeping可能已经抽稀或清理了部分历史数据点，导致search_history返回的点位变少；关键版本应以外部归档包为准，或用事件标记确保关键快照保留。

　　5、用同一参数复跑一次接口并对比两次归档

　　在【Web API】里用同一组参数重新执行一次，把新响应与归档包里的旧响应对比；如果差异主要是新增时间点，属于自然增长，如果差异主要是参数口径变了，就回到分支、时间窗、筛选条件三项修正。

　　总结

　　SonarQube报告怎么导出，先用Portfolio PDF report满足PDF概览需求，再用Web API把issues与measures快照和历史落成文件，保证可复算。SonarQube指标与趋势怎么归档，要把快照、趋势、问题清单与口径说明打包成批次，并考虑Housekeeping会影响历史保留，关键里程碑务必外部落盘。遇到对不上时，先对齐分支、时间窗与筛选条件，再区分快照与历史口径，差异就能快速收敛到可解释、可复现的结论。