📚 课程目录第1章 Snakemake简介与安装

Snakemake 简介与安装

说实话，我最早接触 Snakemake 的时候，已经用过 Makefile、Nextflow、CWL 一堆工具了。但真正让我决定把核心流程迁移过来的，是它那种「Python 原生」的干净感。你想想看，在同一个工作流里，既可以用 Python 写规则逻辑，又可以直接调用 R、Shell、甚至你喜欢的任意脚本——这种自由，对生物信息学来说太重要了。

为什么选 Snakemake？

我个人习惯把工作流工具分成三类：纯配置文件驱动型（CWL/SnakeMake 的 Snakefile 也算一类）、脚本拼接型（Shell + Makefile）、以及语言原生型（Luigi、Dask 那种）。Snakemake 正好站在中间——它用 Python 语法定义规则，但执行时是依赖图驱动的。说白了，你写的是 Python 代码，背后的调度却是 DAG（有向无环图）。

我拿它跟几个常用工具比过，发现三个核心优势最吸引我：

对比点	Snakemake	传统 Make	Nextflow
规则定义语言	Python（类 Make 风格）	Shell + GNU Make 语法	Groovy DSL
依赖图可视化	内置 `--dag` 输出	需 Graphviz + 手动	需额外插件
环境隔离	原生 conda 支持	无	需要 Docker/Singularity
HPC 集群对接	SLURM/PBS/LSF 一行配置	无	原生支持

看到 conda 那栏了吗？嗯，这就是我接下来要重点讲的。Snakemake 能从 Snakefile 里自动创建并隔离 conda 环境，这点对空间转录组分析这种依赖杂乱的场景简直是救命稻草。

版本选择：别追新，求稳

我记得刚入坑时，大喇喇装了最新版 8.x 的预发布版本——结果跑一个老流程，run 块里的 shell 调用行为变了，排查了两天。后来我一个做流程运维的朋友砸过来一句话：「生物信息学工作流里，版本号第二位是奇数就别碰生产。」虽然有点绝对，但确实有道理。

官方推荐的稳定版目前是 7.x 系列（截至写这段内容时，7.32.x 是最新稳定微版本）。我建议你直接选 snakemake>=7.0,<8.0。原因很简单：

7.x 的大多数 API 向后兼容 6.x
社区累积的 bug 修得差不多了
HPC 集群调度模块稳定性高
8.x 开始重构了规则解析引擎，虽然性能提升，但生产环境还不太敢直接用

个人小贴士： 我每次搭建新流程，都会先去 snakemake.readthedocs.io 的 Release Notes 看一眼最近三个版本有没有 breaking changes。就几分钟，但能省后面几天查错的时间。

用 conda 搭建干净环境

这一步其实比想象中简单，但我见过很多新手踩同一个坑——直接在 base 环境里装 snakemake。千万别这么做！conda 的 base 环境一旦装多，依赖冲突会炸到你怀疑人生。我个人习惯是：每个项目一个独立环境，用 mamba 加快安装速度。

下面是我每次都会跑的安装流程（你直接复制执行就行）：

# 1. 创建专门的环境，指定 Python 3.9（7.x 要求 >=3.8）
conda create -n snakemake_pipe python=3.9

# 2. 激活环境
conda activate snakemake_pipe

# 3. 安装 mamba（用来代替 conda 的依赖求解器，快 10 倍）
conda install mamba -n base -c conda-forge

# 4. 用 mamba 安装 snakemake（锁定 7.x 稳定版）
mamba install snakemake=7.32 -c conda-forge -c bioconda

⚠️ 我曾经踩过的坑： 有一次我直接在 conda install 里写了 snakemake>=7.0，结果 conda 解析了将近 40 分钟，最后装了个 8.0.dev0 的预发布版。后来换成 mamba 加精确版本号（比如 =7.32），10 秒搞定。所以版本号真的别偷懒。

验证安装：不跑空，测全面

装完了别急着开心，先确认三件事：

能不能找到命令——就是最基本的 which snakemake
版本对不对——snakemake --version
能不能解析一个最简单的 Snakefile——这一步会提前暴露 conda 环境或 Python 路径问题

我一般这样验证：

# 查看安装路径和版本
which snakemake
snakemake --version

# 写一个最小 Snakefile 测试解析
echo "
rule all:
    output: 'hello.txt'
    shell: 'echo Hello Snakemake > hello.txt'
" > Snakefile

# 使用 --dry-run 看 DAG 能否生成（不实际运行）
snakemake --dry-run

# 正式跑一次，验证全链路
snakemake -c1

# 检查输出
cat hello.txt

--dry-run 这个参数我特别喜欢，它只验证依赖图结构，不真的跑命令。我第一次给团队展示流程时，就先用 --dry-run 确认没有循环依赖，再跑实际的。如果你看到类似这样的输出，就说明安装成功了：

Building DAG of jobs...
Job stats:
job         count
all             1
test_rule       1
total           2

This was a dry-run (flag -n). The order of jobs does not reflect the order of execution.

记住： 空间分析流程往往涉及多个 conda 环境切换。Snakemake 的 --use-conda 参数能让每个规则自动管理自己的环境，但前提是你本地的 snakemake 安装必须能正常调用 conda。上面的 --dry-run 测试如果失败，别急着加 --use-conda，先用最基础的 shell 规则跑通。

安装过程的常见翻车现场

我梳理了几个高频问题，你对照看：

问题	典型症状	解决方法
conda 环境创建慢	`Solving environment` 卡半天	换 mamba，或用 `--channel conda-forge` 指定源
版本冲突炸了	安装后 `snakemake` 命令不存在	先用 `conda list snakemake` 看是否真装了；没装就加 `-c bioconda` 重来
Python 版本太新	规则里 `lambda` 或 `os.getcwd()` 报错	降到 Python 3.8-3.10
`--use-conda` 不生效	提示找不到 conda 命令	检查 `which conda`；或在激活环境里 `conda init` 后再试

嗯，上面这些我基本都中过。特别是第一次用 --use-conda 时，没注意 envs 目录权限，结果 conda 创建环境失败，日志里全是红色错误。解决方案很简单：在 Snakefile 所在目录给当前用户写入权限，或者指定 --conda-prefix 到你有权限的路径。

图上这个流程，就是我每次搭新环境的标准路径。从创建 conda 环境到实际跑出 hello.txt，一共 6 步。第一次做完后，可以顺手把 Snakefile 和 hello.txt 删掉，但记得留个 envs/ 目录——后面空间分析流程会频繁用到 --use-conda，提前留好目录结构会省很多事。

一点心里话： 我见过很多同学花半小时安装，却花了两小时 debug。其实只要 --dry-run 能打出 job stats，后面 99% 的问题都不在 Snakemake 自身，而是规则写的逻辑问题。所以这第一节的「验证安装」一定要做到位，后续才有底气面对更复杂的流程。

好了，Snakemake 环境就绪。后面我们就要写真正的 Snakefile 来跑空间转录组数据了——先别急，下节内容不在这里预告，你只要知道：工具已备好，只待搭流程。