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

第2章：Nextflow安装与配置

好，咱们直接动手。
安装Nextflow这事，其实本身不复杂，但我在项目里见过太多人在这一步浪费时间了。
最典型的问题是什么？Java版本不对，或者网络代理没配好。
简单说，你装Nextflow，本质上就是在装一个Java程序——它本身是个jar包。
所以，最核心的依赖，就是JDK。

2.1 系统环境准备

先确认你的系统是什么。
我个人习惯用Linux（Ubuntu 20.04+或CentOS 7+），macOS也行，Windows用户我强烈建议你装WSL2或者直接用Linux服务器。
Nextflow对Windows原生支持很弱，咱们别跟自己过不去。

Java版本要求
Nextflow 21.04+ 需要 Java 11 或更高版本。
你可以在终端跑这个命令检查：

java -version

如果输出是Java 8，赶紧升级。
以前我在一个项目里因为Java版本太低，Nextflow直接报了个奇怪的类加载错误，排查了半天才发现问题。别重蹈我的覆辙。

除了Java，还要确保curl和wget能用。
很多安装脚本默认用curl下载，如果网络受限，你可以手动下载jar包然后放本地。

2.2 安装方式详解

安装Nextflow主要有三条路。我挨个跟你说说，每个方法都有它的适用场景。

方法一：官方curl一键安装（推荐新手）
这是最省事的，一条命令解决战斗：

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

运行完会在当前目录生成一个 nextflow 可执行文件。
然后把它加到PATH里：

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

验证一下：

nextflow -version

如果看到版本号和Logo，恭喜，装好了。

注意：
上述命令会直接执行远程脚本。如果你在安全要求高的环境中，建议先下载脚本审查一下，或者直接用下面的手动安装方式。

方法二：手动下载jar包（适合离线或内网环境）
我在一些生物信息学集群上干过这事——集群不能访问外网，只能手动传包。
做法很简单：找个能联网的机器，下载对应版本的jar包和启动脚本。

wget https://github.com/nextflow-io/nextflow/releases/download/v23.10.1/nextflow-23.10.1-all
chmod +x nextflow-23.10.1-all
./nextflow-23.10.1-all

你会发现它自动下载了对应版本的jar并创建了nextflow可执行文件。
后续你可以把这个nextflow文件复制到集群的任意位置，只要配好Java就能用。

安装方式对比
方式	适用场景	优点	缺点
curl一键安装	开发机、个人电脑	最快、自动	需联网
手动下载jar	内网、受限环境	可控、离线可用	需要手动处理依赖
conda安装	生物信息学环境	与conda环境统一管理	版本可能滞后

方法三：Conda安装（适合多工具管理）
如果你已经在用conda环境，那直接用conda安装很方便：

conda install -c bioconda nextflow

但注意，bioconda渠道的版本可能比官方晚一两个小版本。
我个人建议想尝鲜新功能的话，还是用官方方式。

2.3 配置核心参数

装完只是第一步。跑起来之前，有几个配置要设好。
我说几个最常见也最重要的。

2.3.1 设置本地执行目录

默认情况下，Nextflow会在当前工作目录下创建 work 目录，所有中间数据都扔里面。
如果硬盘空间紧张，你可以指定路径：

export NXF_WORK=/scratch/$USER/nextflow_work

或者直接写在~/.nextflow/config里：

workDir = '/scratch/$USER/nextflow_work'

2.3.2 配置容器引擎

Nextflow天生就是为容器化设计的。
比如你要用Docker：

nextflow run main.nf -with-docker

或者用Singularity（这在HPC上很常见）：

export NXF_SINGULARITY_CACHEDIR=/path/to/singularity_images
nextflow run main.nf -with-singularity

我曾经遇到一个坑：Singularity默认不挂载当前目录，导致工作目录读不到文件。解决方案是手动设置 SINGULARITY_BINDPATH：

export SINGULARITY_BINDPATH=/data,/home

2.3.3 配置文件优先级

Nextflow的配置可以从多个地方读取，优先级从低到高：

默认配置（内嵌在nextflow.jar里）
~/.nextflow/config（用户级别）
nextflow.config（项目级别）
命令行参数（最高优先级）

你想想看，要是有个参数在项目配置里设了，但命令行也传了同样的参数——一定记住，命令行赢。
所以做参数调优时，用命令行最直接。

2.4 验证安装与基本测试

装完别急着跑大型pipeline，先来个最简单的：

nextflow run hello

这个内置例子会输出一段欢迎信息，同时会创建 work 目录和 .nextflow 目录。
如果这一步正常，说明安装和基本配置都没问题。

然后我再建议你试一下真实的生物信息学pipeline——比如nf-core/rnaseq：

nextflow run nf-core/rnaseq -r 3.14.0 \
    -profile test,docker \
    --outdir ./results

这里-r 3.14.0指定了pipeline的版本，-profile test,docker用了测试数据和Docker环境。
如果你有Singularity，把docker换成singularity就行。

常见问题排查
如果出现 ClassNotFoundException 或 UnsupportedClassVersionError：
99%是Java版本问题。检查一下 java -version 和 javac -version 是否匹配。
如果出现 Permission denied：记得给nextflow加执行权限。
如果网络慢：可以用 export NXF_MODE=offline 跳到离线模式，但要手动保证所有依赖都下载过。

2.5 升级与版本管理

Nextflow更新很频繁。我用过的一个稳定版本是22.10.x，但23.04.x之后性能优化了很多。
升级命令：

nextflow self-update

但注意，这个命令只会更新到最新的稳定版。
如果你需要指定版本：

export NXF_VER=23.10.1
nextflow -version

这会临时覆盖当前环境的版本。要是你经常需要在不同版本间切换，我个人建议用环境变量来控制，别每次都重装。
比如写个脚本切版本：

export NXF_VER="$1"
echo "Switching to Nextflow $NXF_VER"
nextflow -version

2.6 核心安装流程总览

这部分用一张图把安装到配置的流程串起来，你对照着操作不容易漏步骤。

这张图从系统环境检查开始，到版本管理结束。
我个人建议你按这个顺序走，每一步验证通过再往下。
尤其是容器引擎配置那块，我在生产环境见过太多因为Singularity或Docker没配好而导致pipeline跑一半就崩的例子——你提前检查好，后面省心很多。

2.7 小细节与大道理

最后分享一个习惯：
我会在~/.nextflow/config里放一些全局默认配置，比如资源限制、执行器类型、缓存策略。
这样每个新项目就不需要再重复设同一套东西了。
但要注意，项目级nextflow.config的配置会覆盖全局的——记住我前面说的优先级原则。

好了，安装与配置就这些。
别着急，先把这一步做扎实了，后面跑流程的时候你就会发现——嗯，当初花点时间配环境，值！