2. MultiQC 安装与环境配置
安装这事，看着简单，但踩坑的人真不少。我见过太多人在环境配置上花大半天，最后发现是 Python 版本不对。咱们把这一步走稳了，后面才能专心搞模板。
2.1 环境要求先说清
MultiQC 本质是个 Python 工具。所以依赖 Python 3.8+ 环境。你想想看，有些服务器上还是 Python 2.7，那基本白搭。
最低硬件建议：
- CPU：无特殊要求，但多核会快一点
- 内存：512 MB 起步，处理大量样本时建议 2 GB+
- 磁盘：预留 100 MB 即可
2.2 虚拟环境——这是我的第一条建议
为什么我要先说虚拟环境？有一次我在客户服务器上直接 pip install，结果把整个系统的依赖搞崩了，运维大哥差点没让我走。从那以后，虚拟环境成了我安装任何 Python 工具前的习惯动作。
为什么必须用虚拟环境？
- 隔离依赖，避免与系统 Python 包冲突
- 方便版本管理，想删就删，不拖泥带水
- 多项目共存在一台机器上，互不干扰
创建虚拟环境两种主流方法，我习惯用 conda：
# 使用 conda
conda create -n multiqc_env python=3.10
conda activate multiqc_env
# 或者使用 venv（Python 自带）
python3 -m venv multiqc_env
source multiqc_env/bin/activate激活后，你的终端前面会出现环境名，就像这样：
(multiqc_env) user@server:~$嗯，看到这个提示符，就说明环境已经激活了。
2.3 方法一：pip 安装（我最常用的方式）
说白了，这是最简单的安装方法。你在虚拟环境里，一行命令搞定：
pip install multiqc如果你要安装特定版本，像我有时为了复现问题会这么做：
pip install multiqc==1.14安装完成后，验证一下：
multiqc --version理论上你会看到类似：
multiqc, version 1.21我曾经碰到过的问题： 用 pip 安装时，如果你的环境里有多个 Python 版本，pip 可能指向的是 Python 2。这种情况下安装会失败或者装上老版本。建议先检查一下：
pip --version确认 pip 关联的是 Python 3.x。如果是 Python 2 就改用 pip3。
3.4 方法二：conda 安装（我最推荐的方案）
conda 的好处是自动帮你处理一些底层依赖，比如 matplotlib、numpy 这些。记得我在一台没有 root 权限的服务器上装 MultiQC，pip 因为依赖缺了 build 工具报了一堆错，换 conda 就好了。
conda install -c bioconda multiqcconda 默认从 conda-forge 和 bioconda 频道拉包。如果你在 conda 里遇到找不到包，可以明确指定频道：
conda install -c conda-forge -c bioconda multiqc安装后验证命令和 pip 一样：
multiqc --version两种安装方式的对比，我列了个表：
| 特性 | pip 安装 | conda 安装 |
|---|---|---|
| 安装速度 | 较快 | 较慢（解析依赖时间长） |
| 依赖处理 | 只处理 Python 包依赖 | 处理系统级 + Python 依赖 |
| 版本选择 | 可指定精确版本 | 支持较灵活 |
| 推荐场景 | 个人开发机 | 服务器、集群、多用户环境 |
2.5 方法三：源码编译（什么时候用？）
说实话，大部分用户不需要这么做。什么时候需要？一种是你要开发 MultiQC 插件或者改源码；另一种是官方发布的新版本还没上传到 PyPI 或 conda 频道。
我去年就遇到过。MultiQC 刚发了一个 bug 修复版本，conda 和 pip 都还没更新。没办法，只能从 GitHub 上拉代码来跑。
步骤很清晰：
# 克隆仓库
git clone https://github.com/MultiQC/MultiQC.git
cd MultiQC
# 使用虚拟环境（别忘记！）
python3 -m venv venv
source venv/bin/activate
# 以开发模式安装
pip install -e .这个 -e . 参数很关键，它让 Python 以「可编辑模式」安装。你改了源码后，不需要重新安装，修改就生效。
你也可以装所有开发依赖：
pip install -e ".[dev]"然后确认一下：
python -c "import multiqc; print(multiqc.__version__)"2.6 安装验证：不止看版本号
单纯看 multiqc --version 输出只能说明它装了，不一定能正常工作。我个人习惯用一个小样本集做冒烟测试。
MultiQC 官方提供测试数据：
# 下载测试数据（假设你有 wget）
wget https://raw.githubusercontent.com/ewels/MultiQC/master/test-data/data/modules/fastqc/fastqc_test.zip
unzip fastqc_test.zip
# 运行 MultiQC
multiqc .如果一切顺利，你会看到类似下面的输出日志：
[INFO ] multiqc : This is MultiQC v1.21
[INFO ] multiqc : Template : default
[INFO ] multiqc : Searching '.'
[INFO ] multiqc : Processed 2 FastQC reports
[INFO ] multiqc : Report : multiqc_report.html
[INFO ] multiqc : Data : multiqc_data看到 Report: multiqc_report.html 就说明安装没问题。我习惯把这个文件用浏览器打开看一眼，确认没报错。
如果运行报错提示缺少某个模块，建议先看看是不是虚拟环境没激活，这是最常见的问题。确认虚拟环境激活后还是报错，可以试试用 pip list 检查已安装包：
pip list | grep multiqc2.7 常见安装问题速查
我在教学和项目里收集了几个高频问题：
| 现象 | 原因 | 解决办法 |
|---|---|---|
| pip install 报 SSL 错误 | 网络问题或代理未配置 | 加 --proxy=http://你的代理 |
| conda 安装慢到无法忍受 | 默认源在国内访问慢 | 换国内镜像，比如清华源 |
| multiqc 命令找不到 | 未激活虚拟环境 | 检查 $PATH 是否包含 bin 目录 |
| 编译安装时缺 C 扩展 | 缺少 gcc 等构建工具 | 安装 build-essential（Linux）或 Xcode Command Line Tools（macOS） |
2.8 一张图看懂安装流程
下面这张图把整个安装逻辑串起来了，你自己看一遍就知道怎么选：
2.9 我的推荐
如果你是新手，直接走这条路最稳：
- 先装 conda（Miniconda 就够了）
- 用 conda 创建一个干净的虚拟环境
- conda install -c bioconda multiqc
- 验证版本 + 跑测试数据
这套流程我在几十台机器上验证过，几乎不出错。如果你已经熟悉了，也可以直接用 pip。总之，这一步走扎实了，后面我们写自定义模板的时候，就不会被环境问题打断思路。