假设输入清单有96个样本，MultiQC总表里却只剩94个；原始和剪切后的FastQC结果放在一起，报告里又像只跑了一轮。遇到这种情况，很多人会重新跑上游流程，但问题往往不在计算失败，而在MultiQC怎样找到日志、怎样清洗样本名，以及同名结果怎样写入报告。
MultiQC不是质控算法，也不会重新分析FASTQ或BAM。它扫描已有日志和结果文件，调用对应模块解析指标，再汇总成一个HTML报告。要判断“少样本”，必须把文件发现、模块识别、样本命名和报告展示分开检查。
先核对版本、输入和输出
本文于2026年11月14日核对MultiQC官方资料，当前最新发布版为1.35，要求Python 3.9及以上。官方支持工具页当日列出182个工具模块，但“支持某工具”不等于其所有历史或未来日志格式都能识别，升级上游软件后仍应做小批验证。
MultiQC的输入通常不是原始测序文件，而是FastQC ZIP、STAR日志、samtools stats、featureCounts summary等工具输出。最简单的命令是：
multiqc results/ -o qc_summary -n project_qc.html -f -v
-o指定输出目录，-n指定报告名，-f覆盖同名旧报告，-v打印更详细的搜索与解析日志。正常输出至少包括HTML和multiqc_data/；后者保存可供下游复核的表格数据。官方文档还说明，1.29及以上版本会在数据目录生成multiqc.parquet。
官方示例揭示了最隐蔽的问题：同名覆盖
官方文档给出三个目录：analysis_1、analysis_2、analysis_3，每个目录都有名为sample_1.fastq.gz.aligned.log的文件。MultiQC清洗文件名后，三份结果都可能变成sample_1。如果日志解析得到相同样本名，先前数据会被后来的数据覆盖；命令成功、HTML也能打开，但样本数已经变少。
先用详细日志确认覆盖，再为样本名加目录前缀：
multiqc -v -d -dd 1 results/ -o qc_summary -f
-d把目录加入样本名，-dd 1只取路径末端一个目录。若冲突来自文件名被过度截断，可用-s/--fullnames临时关闭样本名清洗。只有当日志内部记录的样本名无效时，才考虑--fn_as_s_name强制采用日志文件名；这个选项会影响模块识别后的命名，不能不看结果就全局套用。
六种“少样本”现象，处理方式不同
| 现象 | 更可能的原因 | 先做的检查 | 合适处理 |
|---|---|---|---|
| 整个工具模块都没有 | 文件格式或搜索模式未被识别 | 看-v中找到哪些文件、触发哪个模块 |
核对上游版本与模块文档，先拿1—2份日志试跑 |
| 样本数少于文件数 | 清洗后样本名相同，后读结果覆盖前者 | 搜索verbose日志中的覆盖提示，比较原名与显示名 | 用-d -dd 1保留批次目录，或调整命名规则 |
| 原始与剪切后结果混在一起 | 两个阶段清洗成同一名字 | 分别统计raw、trimmed文件清单 | 分目录出报告，或用配置区分模块实例 |
| 出现不该有的旧样本 | 递归扫描到历史目录、临时日志 | 记录实际扫描路径和文件清单 | 用--file-list限定输入，或用--ignore排除 |
| 指定模块缺失但命令仍成功 | 默认会继续处理其他已识别模块 | 核对预期模块是否真的出现在报告 | 配合-m使用--require-logs，缺失时退出码为1 |
| HTML打开后卡顿 | 样本多、交互图和大表渲染压力高 | 区分生成耗时与浏览器渲染耗时 | 筛选范围、使用flat图，不要强制所有图交互化 |
不要只用“HTML能打开”判断成功
一套可复用的验收顺序是：先生成预期输入清单，按工具或阶段统计文件数；再保存MultiQC版本、完整命令和verbose日志；随后核对报告模块、样本数和样本名；最后抽查2—3个异常样本，把MultiQC中的数值与原始日志对回去。
如果流水线明确要求FastQC和STAR都存在，可以让缺失直接失败：
multiqc results/ -m fastqc -m star --require-logs \
--file-list qc_inputs.txt -o qc_summary -f
--file-list每行一个待搜索文件路径，能避免项目根目录里旧结果被意外扫入。需要注意：文件数量不一定等于样本数量，一个样本可能有R1/R2、多个lane或多个工具日志，所以应按模块和建库设计制定预期，而不是机械比较总文件数。
大报告的“变化”可能只是展示策略
MultiQC官方为大样本报告设置了自动降载规则：图中样本达到50个时，部分图默认不在加载时立即绘制；表格达到500行时可转为小提琴图；图中序列达到1000条时默认生成flat图；超过2000个样本时，小提琴图数据还会下采样。这些数字是报告展示阈值，不是数据质控阈值，也不表示样本被删除。
因此，看到灰色“Show Plot”、小提琴图或静态图，先检查界面设置和multiqc_data/，不要把显示方式改变误判为分析失败。官方也明确提醒，PDF会关闭许多交互功能，甚至缺少部分图；交付时优先保留HTML和数据目录，PDF只作补充。
本地够不够，取决于日志规模和数据位置
几十到几百份日志、目录结构清楚时，MultiQC通常可在本地完成，它不需要GPU。先限定搜索路径、解决命名冲突，比增加硬件更有效。真正值得把任务放到服务器上的场景，是上游流程本来就在服务器、日志分散在多个批次、需要定时重跑并保留版本化报告，或有数千样本导致扫描、报告生成和浏览器打开都需要稳定环境。
服务器的价值是让汇总任务靠近数据，固定MultiQC版本、配置文件和输入清单，并把报告纳入流水线；它不会替代对异常指标的生物学判断。环境部署、租用服务器自行运行和委托批量质控分析，应分别确认范围。
MultiQC能汇总证据，不能给数据判生死
MultiQC把多个工具的输出放在同一视图，但不会自动证明样本合格，也不能弥补上游日志缺失。模块之间的红黄颜色、阈值和单位仍来自各自工具。遇到缺样本，先回答“文件有没有被找到、模块有没有识别、名字有没有冲突、展示有没有降载”，再决定是否重跑上游。
如果报告样本数对不上，可以准备MultiQC版本、目录树、预期与实际样本数、运行命令和一段可分享的verbose日志。云生信可先协助判断是命名与配置问题、需要统一服务器环境，还是适合在约定范围内委托完成批量质控与后续分析。
