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

安装与配置

你好，我是老张。在开始写流程之前，先把 Nextflow 装好。这一步其实不难，但坑也不少。我见过太多人在安装环节卡住，最后发现是环境变量没配对。今天咱们就把这事彻底搞定。

安装方式

Nextflow 官方提供了两种主流安装方式：Conda 和 curl。我个人习惯用 curl，因为简单、干净。但 Conda 更适合做环境隔离。你看场景选。

方式一：Conda 安装

如果你已经在用 Conda 管理生物信息软件，那直接一条命令搞定。我常用的环境叫 nf，你可以任意起名。

conda create -n nf -c bioconda nextflow
conda activate nf
nextflow -version

嗯，这里要注意：Conda 源如果慢，记得加清华镜像。

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/bioconda/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/

装上之后验证版本就行。

方式二：curl 一键安装

这才是 Nextflow 团队推荐的姿势。一条命令下载一个 shell 脚本，然后执行。我在项目中经常用这个，配合 Docker 镜像，干净利落。

cd ~/bin   # 或者任何在 PATH 里的目录
curl -s https://get.nextflow.io | bash
chmod +x nextflow
export PATH=$PATH:~/bin
nextflow -version

提示：如果网络受限，可以把安装文件下载到内网机器上，再手动解压。本质上就是一个 nextflow 可执行文件，Java 写的。

你可能会问：为什么这么轻？Nextflow 本身只是一个启动器，真正运行时它会自动从 Maven 仓库拉取核心 jar 包。所以你第一次运行会很慢，后面就快了。

两种方式对比

对比项	Conda	curl
依赖管理	自动解决 Java 依赖	需要手动安装 Java 11+
多版本管理	可以通过环境切换	需要手动下载不同版本文件
网络要求	需要访问 Conda 源	需要访问 GitHub + Maven
推荐场景	已有 Conda 生态	追求最小依赖、生产环境

环境变量

装完 Nextflow 只是第一步。环境变量不配好，后面寸步难行。我踩过最大的坑就是 NXF_HOME 默认指向家目录，结果跑流程时磁盘写满了。

核心环境变量就这几个：

# 必须配的
export NXF_HOME=/data/nextflow   # 缓存和运行文件目录
export NXF_TEMP=/data/tmp        # 临时文件，建议单独分区
export NXF_OPTS='-Xms1g -Xmx4g'  # JVM 内存参数

# 按需配的
export NXF_ANSI_LOG=false        # 关闭 ANSI 日志（集群提交时有用）
export NXF_EXECUTOR='slurm'      # 默认调度器
export NXF_WORK=/data/work       # 工作目录，建议大容量 SSD

警告：不要在 NXF_HOME 里存重要数据。它只是一个本地缓存。流程失败时，你很可能需要清空它。我曾经手误删了跑了一周的缓存……嗯，还好只损失了时间。

另外，记得把这些配置写到 ~/.bashrc 或 ~/.nextflow/config 里。我推荐用 ~/.nextflow/config，它能被所有流程读取。

// nextflow.config (放在 $HOME/.nextflow/)
workDir = '/data/work'
cacheDir = '/data/cache'
executor {
  name = 'slurm'
  queueSize = 100
}

版本管理

Nextflow 更新挺快的，稳定版大概每两三个月一版。我在项目里吃过亏：同一个流程用不同版本跑，结果不一样。后来我学乖了——每次跑流程都锁定版本。

查看当前版本：

nextflow -version

      N E X T F L O W
      version 24.10.2 build 5919
      created 2024-11-20 17:37:43 UTC
      cite doi:10.1038/nbt.3820

安装指定版本：

# curl 方式
curl -fsSL https://github.com/nextflow-io/nextflow/releases/download/v24.10.2/nextflow-24.10.2-all -o nextflow

# Conda 方式
conda install -c bioconda nextflow=24.10.2

更推荐的是在流程根目录放一个 .nextflow.versions 文件，记录依赖。不过最简单的做法是用 Docker 镜像。每次运行指定镜像版本：

nextflow run main.nf -with-docker nextflow/nextflow:24.10.2

这样无论本地装的什么版本，实际运行环境都一样。我团队现在统一用这个方案。你想想看，不同机器上结果完全一致，多省心。

架构概览

理解 Nextflow 的架构，能帮你少走弯路。咱们看张图：

这张图展示的是典型的运行架构。左侧是你操作的终端，中间是 Nextflow 引擎（Java 进程），右侧是实际计算资源的执行平台。引擎不直接跑计算，而是调度 Task。

每一个 process 定义会被引擎解析成一个 Task 模板。当你给不同的 input 时，引擎会生成多个 Task 实例。举个例子：处理 10 个样本，就是 10 个并行的 Task。这些 Task 被提交到 SLURM 队列或本地 CPU 上。

关键概念：引擎是单线程的 Java 进程，只负责调度和状态管理。真正的计算在 Task 里。所以引擎本身很轻，你用 4GB 内存跑上千个样本都没问题。别把引擎当计算节点用，它就是个大脑。

小节：目录结构初探

装好后，看看 NXF_HOME 下都有什么。默认是 ~/.nextflow。

tree -L 2 ~/.nextflow

/Users/laozhang/.nextflow/
├── assets         # 存放 from-local 模块
├── config         # 全局配置缓存
├── credentials    # 认证信息
├── history.db     # 缓存数据库（SQLite）
├── log            # 运行日志
├── plugins        # 插件目录
│   ├── nf-amazon
│   └── nf-google
├── secrets        # 加密密钥
└── tower          # Tower 平台关联文件

这里要注意 history.db。它是 SQLite 文件，记录了你所有运行的哈希值。这种设计让 Nextflow 能自动检测哪些步骤可以复用——说白了就是缓存。但如果你改了小版本，或者运行环境变了，缓存可能会失效。我建议你定期清理没用的缓存，比如跑完一个项目就删掉 ~/.nextflow/history.db。

小技巧：可以用 nextflow info -c 查看当前缓存的哈希状态。想彻底清缓存就 nextflow clean -f。

总结一下配置清单

为了方便你快速上手，我把完整的一套安装配置步骤列出来。你照着做就行。

安装 Java 11+（推荐用 sdkman 管理多版本）
下载 Nextflow 二进制文件
配置环境变量 NXF_HOME 并确保可写
创建 ~/.nextflow/config 设置工作目录和调度器
运行 nextflow run hello 验证安装

# 一步到位脚本（Ubuntu 为例）
sudo apt install -y openjdk-11-jdk curl
curl -s https://get.nextflow.io | bash
sudo mv nextflow /usr/local/bin/
echo 'export NXF_HOME=/opt/nextflow' | sudo tee -a /etc/profile
source /etc/profile
nextflow run hello