2. 安装与配置：pip、conda、Docker安装，配置文件详解

安装这事儿吧，其实特简单。但简单归简单，坑也不少。

我记得刚入行那会儿，团队里十个人有八种环境配置方式，最后出报告时版本对不上，返工了一整天。从那以后，我就特别看重安装流程的标准化。

MultiQC的安装方式主要有三种：pip、conda和Docker。每种都有它的适用场景，咱们一个一个说。

2.1 三种安装方式对比

在动手之前，先搞清楚该选哪个。我个人的偏好是这样的：

方式	适用场景	优点	缺点
pip	个人工作站、已有Python环境	轻量、快速、可离线安装	容易和其他包冲突
conda	生物信息团队、需要多版本管理	环境隔离好、依赖处理成熟	包体积大、首次安装慢
Docker	生产环境、HPC集群、云服务器	完全隔离、一键部署、可复现	需要Root权限、对新手不友好

2.2 pip安装

这是最直接的方式。前提是你已经有Python 3.6以上版本。

# 直接安装最新版
pip install multiqc

# 指定版本安装（生产环境推荐）
pip install multiqc==1.14

# 从GitHub安装开发版（有时bug修复比正式版快）
pip install git+https://github.com/ewels/MultiQC.git

我在项目中遇到过一个问题：用 pip install multiqc 装完后，一运行就报 ModuleNotFoundError: No module named 'Markdown'。原因是pip默认没把可选依赖装上。

解决方法是：

# 装全所有依赖
pip install multiqc[all]

# 或者只装核心依赖
pip install multiqc[core]

2.3 conda安装

对于生物信息学团队，conda几乎是标配。为啥推荐？因为它能解决依赖地狱。

# 创建独立环境（环境名自取，我用multiqc_env）
conda create -n multiqc_env python=3.9

# 激活环境
conda activate multiqc_env

# 安装MultiQC
conda install -c bioconda multiqc

# 或者指定版本
conda install -c bioconda multiqc=1.14

你想想看，conda的厉害之处在于它连依赖链上的每个包都给你管好了。我之前有个项目，需要同时用MultiQC 1.13和1.14做对比测试，conda环境一克隆就搞定。

# 克隆环境做测试
conda create -n multiqc_test --clone multiqc_env

2.4 Docker安装

Docker是我个人最偏好的方式。原因只有一个——镜像就是你的环境，打包带走，到哪都能跑。

# 拉取官方镜像
docker pull ewels/multiqc

# 运行容器（挂载当前目录到/data）
docker run -v $(pwd):/data ewels/multiqc /data

这里有个坑。很多人第一次用Docker跑MultiQC，发现报告生成在容器里，宿主机上找不到。你必须把输出目录也挂载出来：

# 带输出目录挂载
docker run -v $(pwd):/data:rw ewels/multiqc /data -o /data/report

# 如果提示没有权限，加上--user参数
docker run --user $(id -u):$(id -g) -v $(pwd):/data:rw ewels/multiqc /data

2.5 基础验证

装好之后，千万别直接开始干活。先验证一下：

# 检查版本
multiqc --version

# 查看帮助
multiqc --help

# 查看可用模块
multiqc --list-modules

如果能正常输出版本号和模块列表，说明安装成功了。我记得第一次装好后，看到“MultiQC v1.14”那段ASCII艺术logo时，心里还挺开心。

2.6 配置文件详解

安装只是开始，真正的生产力来自于配置。MultiQC的配置文件可以让你定制几乎所有的报告行为。

配置文件默认路径：

• 系统级：/etc/multiqc_config.yaml
• 用户级：~/.config/multiqc/multiqc_config.yaml
• 项目级：当前目录下 multiqc_config.yaml（优先级最高）

我一般用项目级配置，因为它能跟着代码库走，别人拉下来就能用。

2.6.1 核心配置项

配置项	说明	示例
title	报告标题	title: "RNA-seq 质控报告 v2.0"
report_comment	报告注释（显示在标题下方）	report_comment: "本报告由pipeline A生成"
intro_text	报告前言文字	intro_text: "样本采集于2024年Q1"
module_order	模块显示顺序	见下方代码块
table_columns_visible	表格中默认隐藏的列	见下方代码块
custom_data	导入自定义数据文件	见下方代码块

2.6.2 实战配置示例

下面是我在一个实际项目中用过的配置文件。它控制着报告的外观和内容：

# multiqc_config.yaml
title: "肿瘤外显子测序质控报告"
report_comment: "本报告由自动化质控pipeline v3.1生成"
intro_text: "样本来源：肿瘤组织 & 配对正常组织"

# 模块顺序控制
module_order:
    - fastqc:
        name: "FastQC 原始数据质控"
    - cutadapt:
        name: "接头去除统计"
    - samtools:
        name: "比对统计"
    - picard:
        name: "标记重复统计"

# 表格列控制
table_columns_visible:
    FastQC:
        percent_duplicates: True
        percent_gc: True
        total_sequences: False

# 自定义数据
custom_data:
    sample_metadata:
        file: "samplesheet.csv"
        columns:
            - sample_id
            - tumor_type
            - library_prep

2.6.3 命令行覆盖配置

有时候不想改配置文件，可以用命令行参数临时覆盖：

# 临时修改标题
multiqc . --title "快速测试报告"

# 强制使用某个模块
multiqc . -m fastqc -m cutadapt

# 排除不需要的模块
multiqc . -e samtools -e picard

命令行参数的优先级高于配置文件。这在调试时特别有用——不用反复改YAML文件，直接加参数看效果。

2.7 安装配置全流程

为了帮你理清脉络，我画了一张图。它展示了从选择安装方式到生成配置再到运行MultIQC的完整逻辑：