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

使用Nextflow搭建特征学习自动化管线 - 第2节

环境要求与准备工作

装 Nextflow 之前，先看看你手头的环境够不够格。我在几个项目里踩过坑——明明代码写好了，结果环境不兼容，跑起来全是幺蛾子。所以咱们先把地基打牢。

操作系统支持

说实话，Nextflow 对 Linux 和 macOS 的支持最成熟。Windows 用户比较尴尬——原生 PowerShell 跑不了，得靠 WSL2 或者 Docker 绕一圈。我个人习惯装 Linux，省心。

Linux：Ubuntu 18.04+，CentOS 7+，随便用
macOS：10.13 (High Sierra) 以上，M1/M2 芯片也没问题
Windows：必须走 WSL2，或者装个虚拟机

必须装的东西

你想想看，Nextflow 核心是 Java 写的，所以 JDK 是刚需。另外它天生支持容器化，Docker 或 Singularity 至少备一个。

组件	版本要求	为什么需要
Java (JDK)	11 或 17（推荐 17）	Nextflow 运行环境
Docker	20.10+	容器化执行任务（可选）
Singularity	3.8+	HPC 环境替代方案（可选）
Git	2.x	拉取 pipeline 代码

小提示：我建议 Java 版本别用 8，太老了。Nextflow 很多新特性都依赖 JDK 11+，你回头升级还麻烦。

检查 Java 版本很简单：

java -version
# 应该看到类似 openjdk version "17.0.1" 这样的输出

安装 Nextflow

经典一键安装

Nextflow 官方给了一个 curl 脚本，一两秒搞定。我头一回装的时候还怀疑这么简单是不是有坑，结果真没什么花头。

curl -s https://get.nextflow.io | bash

这条命令会下载一个 nextflow 的 shell 脚本到当前目录。把它加到 PATH 里就能全局调用：

chmod +x nextflow
sudo mv nextflow /usr/local/bin/

验证安装：

nextflow -version

你讲看到类似 nextflow version 24.04.2 的输出。数字可能不一样，但版本是 22+ 就行。

通过 Conda 安装（备选）

要是你本来就习惯 conda 管理工具链，也可以走这条路：

conda install -c bioconda nextflow

不过 Conda 版本更新有时比官方慢一点。我一般用官方方式，干净利落。

环境配置：nextflow.config

Nextflow 的配置文件是 nextflow.config，用 Groovy 语法写。说白了就是个键值对字典，但能嵌套、能引用环境变量。嗯，这里要特别注意大小写和缩进，Groovy 对空格不敏感，但你最好保持可读性。

最简配置文件

刚上手时，一个空文件都能跑。但真正干活至少得配两样：进程的执行器（executor）和最大资源上限。举个例子：

// 默认用 local 执行器，就是在本机跑
executor {
  name = 'local'
}

process {
  cpus = 2
  memory = '4 GB'
  time = '1h'
}

核心原则：每个进程的资源不能超过全局上限。否则会报 Resource not available 错误。

配置环境变量与容器

我个人习惯把容器镜像写在配置文件里，这样 workflow 代码里就不用反复写 container 了：

process {
  container = 'biocontainers/bwa:v0.7.17_cv1'
  podman {
    enabled = true
  }
}

env {
  NXF_VER = '24.04.2'
}

注意 NXF_VER 环境变量可以强制指定 Nextflow 版本，在团队协作时很有用——避免有人用老版本跑出奇怪的结果。我曾经就因为没设这个，同事用旧版跑出了一个不同的中间结果，排查了半天。

多环境配置：区分开发与生产

大型项目里，你总得区分本地测试和集群提交。Nextflow 支持按 profile 切换配置：

profiles {
  standard {
    executor {
      name = 'local'
    }
    process {
      cpus = 4
      memory = '8 GB'
    }
  }
  cluster {
    executor {
      name = 'slurm'
      queueSize = 100
    }
    process {
      cpus = 8
      memory = '32 GB'
    }
  }
}

运行的时候加个 -profile 参数就能切换：

nextflow run main.nf -profile cluster

SVG：安装与配置知识图谱

下面这张图把整个安装配置流程串起来了。你可以照着它捋一遍，看看自己漏了哪步。

验证安装与常见问题

快速跑一个测试

装完别急着写大流程，先跑个 hello world 试试水：

nextflow run hello

这个命令会自动从 GitHub 拉取 Nextflow 官方示例 hello.nf。如果看到类似下面这样的输出，说明环境没问题：

N E X T F L O W  ~  version 24.04.2
Launching `hello.nf` [gifted_mestorf] DSL2 - revision: f9c8e6a5e7
[warm up] executor > local
[fc/a1bcde] process > sayHello (1)
[8b/234567] process > sayHello (2)

Hello World!
Hello World!

注意：如果卡在 warm up 很久不动，多半是网络问题。Nextflow 需要连 GitHub 下载缓存。你可以配置代理或提前手动下载 https://github.com/nextflow-io/nextflow/releases 里的 jar 包。

我踩过的坑

Java 版本太低：曾经用 JDK 8 跑 22.10 版本，直接抛 UnsupportedClassVersionError。升到 11 就解决了。
Windows 下 WSL2 文件权限：Windows 和 WSL 跨文件系统访问时，Nextflow 的临时目录可能没写权限，报 Permission denied。把项目放在 WSL2 的 Linux 文件系统里就行。
Docker 没启动：如果你配了 container 但 Docker daemon 没跑，进程会卡住直到超时。运行前先 docker ps 确认一下。

我的建议：第一次配置时，把 NXF_VER 写死，然后用 -profile 切 local 试跑一次。跑通了再配集群。这样你排查问题时会少很多干扰项。

配置文件的路径加载规则

Nextflow 找配置文件的顺序有点讲究，搞乱了容易迷惑：

工作目录下的 nextflow.config（最高优先级）
$HOME/.nextflow/config（全局默认配置）
环境变量 NXF_CONFIG_FILE 指定的路径

注意：如果工作目录里没有 nextflow.config，Nextflow 不会报错，会直接使用全局配置。我有个同事因此把自己的集群参数漏写了，跑了半天才发现。嗯，所以在工作目录里显式创建配置文件是个好习惯。