📚 课程目录第2章安装与环境配置

搭建你的质控流水线：安装与环境配置

好了，咱们正式开始动手。先把工具都备齐了，后面才能跑得顺畅。

这一章说白了就是安装教学。但你别小看它——我接手过好几个项目，一半的问题都出在环境配置上。版本冲突、路径不对、权限不够...各种坑踩了个遍。所以咱们一步步来，稳扎稳打。

Snakemake 装在哪？

Snakemake 是个 Python 包。装它就跟装 Flask、Django 一样简单。

我个人习惯用 conda 来装。 不是因为它多高级，而是 conda 能顺便把 Python、pip 和一堆底层库都管好，省心。

先把 conda 装上（如果你机器上还没有的话）。然后新建一个干净的环境，专门给这门课用：

conda create -n qc_pipeline python=3.10
conda activate qc_pipeline

Python 版本我推荐 3.9 或 3.10。3.11 以上有些旧版 Snakemake 插件还没适配好，我是踩过这个坑的。

然后装 Snakemake 本体：

pip install snakemake

或者用 conda 源：

conda install -c bioconda -c conda-forge snakemake

两条路都行。bioconda 源里的包版本比较稳，但更新慢一点。pip 反之。看你取舍。

Windows 用户怎么办？

Snakemake 在原生 Windows 上跑需要 WSL2（Windows Subsystem for Linux）。Windows 版的 Snakemake 几年前就已经不太维护了——这是我去年在客户现场踩的教训。

别在 Windows cmd 或 PowerShell 里直接 pip install snakemake。 你会遇到一堆微软底层库的兼容问题，浪费时间。

正确做法是：

启用 WSL2（去 BIOS 开虚拟化，装 Ubuntu 22.04 LTS 镜像）
在 WSL 里按 Linux 的流程装 conda + Snakemake
把 Windows 里的测序数据挂载到 WSL 的 /mnt 路径下

嗯，WSL2 现在的性能已经很好了。I/O 瓶颈基本感觉不到。

装质控工具：FastQC、MultiQC、Trimmomatic

工具列表不长，但每个都有讲究。我用个表格给你列清楚：

工具	版本（推荐）	安装方式	用途
FastQC	0.11.9+	conda / 官网下载	单样本质量的原始报告
MultiQC	1.14+	pip / conda	汇总多个 FastQC 报告为一张大表
Trimmomatic	0.39+	conda / 官网 JAR	去除接头、低质量碱基

版本一致性很重要。 我见过有人装了 FastQC 0.12 但 Snakemake 里写的规则还是 0.11 的路径。结果跑出来报告格式变了，MultiQC 解析不了。折腾半天才发现是版本对不上。

建议你锁定 conda 里工具的版本号。

一条命令全装：

conda install -c bioconda -c conda-forge \
  fastqc=0.11.9 \
  multiqc=1.14 \
  trimmomatic=0.39

Trimmomatic 比较特殊。它是个 Java 程序，所以机器上得有 JRE（Java Runtime Environment）。

conda install -c conda-forge openjdk=11

注意 Java 版本。我用 11 和 17 都测过，没问题。Java 8 也行，但某些新版 Trimmomatic 会报日志告警，不影响运行，就是看着烦。

装完之后怎么验证？

别急着写 Snakefile。先检查每个工具能不能正常跑。

# 检查 Snakemake 版本
snakemake --version

# 检查 FastQC
fastqc --version

# 检查 MultiQC
multiqc --version

# 检查 Trimmomatic（看有没有报错就行）
trimmomatic

这四个命令都返回正常的版本号，环境就算搭好了。

一个小技巧： 把 conda env 的 bin 目录加到 .bashrc 的 PATH 里。不然每次都得 source activate，太麻烦。

echo "export PATH=/home/yourname/miniconda3/envs/qc_pipeline/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc

整个安装流程长什么样？

我把上面这些步骤画成了流程图。你打开看看，跟着箭头走一遍就行。

关于 conda 环境管理的建议

你可能会想：这么多工具，装一个环境里会不会打架？

嗯，会。我去年在做一个多步骤质控流程时，就因为一个 YAML 文件格式的变更，导致两个版本的 ruamel.yaml 库打架，Snakemake 直接报错退出。排查了俩小时...

所以我的方案是：

一个项目一个环境。 QC 项目用 qc_pipeline，RNA-seq 用 rnaseq_env，互不干扰。
写一个 environment.yaml 把工具版本锁死。下次换机器，一条命令就能重建。

environment.yaml 长这样：

name: qc_pipeline
channels:
  - bioconda
  - conda-forge
  - defaults
dependencies:
  - python=3.10
  - snakemake=7.32.4
  - fastqc=0.11.9
  - multiqc=1.14
  - trimmomatic=0.39
  - openjdk=11

以后重建环境：

conda env create -f environment.yaml

这一步帮你省掉很多“我机器上能跑你机器上跑不了”的尴尬。

权限问题也提一嘴

如果你在服务器上工作，sudo 不是想用就能用的。这时候：

conda 装到用户目录下（~/.conda/envs/）
pip 加 --user 参数
确保输入数据目录有读权限，输出目录有写权限

chmod +r /path/to/raw_data/*.fastq
mkdir -p /path/to/output
chmod +w /path/to/output