第2章：开发环境搭建——把吃饭的家伙先备齐

说实话，这些年我带过不少新人，发现八成以上的问题都出在环境搭建阶段。

工具没装对、版本不匹配、权限不够……这些坑我基本上都踩过一遍。

所以这一章，我带你一步步把地基打牢。

2.1 整体环境概览

什么是「开发环境」？说白了就是三样东西：

  • Java —— Nextflow 是跑在 JVM 上的，没有它啥都干不了
  • Nextflow —— 流程引擎本身，我们的主角
  • Docker / Singularity —— 容器化执行，保证每次跑的结果可复现

这三者之间是层层依赖的关系。我习惯把它想象成一个金字塔：

开发环境三层结构 Java Runtime (JVM) 版本 ≥ 11（推荐 17 或 21 LTS） Nextflow 流程引擎 版本 ≥ 22.10（建议 24.04.x） Docker / Singularity 容器运行时，保证环境一致 下层是上层的运行基础，安装时务必自底向上：Java → Nextflow → 容器 只要版本对应正确，这套环境可以用很多年不折腾

你看，底层是 Java，中间是 Nextflow，最上面才是容器。装的时候顺序不能乱，这是经验之谈。

2.2 安装 Java

Nextflow 从 22.10 版本开始，最低要求 Java 11。但我个人强烈建议你直接装 Java 17 或 21，都是 LTS 版本，最稳。

版本选择的经验法则：

  • Java 11 — 能用，但已接近 EOL（生命周期结束）
  • Java 17 — 当前最主流，性能好，建议首选
  • Java 21 — 最新的 LTS，如果你项目不赶时间可以上

2.2.1 在 Linux 上安装

我用的是 Ubuntu 系统，日常开发都在上面。下面是我最常用的安装方式：

# 更新包管理器
sudo apt update

# 直接安装 OpenJDK 17
sudo apt install openjdk-17-jdk -y

# 验证版本
java -version

# 期望输出类似：
# openjdk version "17.0.10" 2024-01-16 LTS
# OpenJDK Runtime Environment (build 17.0.10+7-Ubuntu-122.04)
# OpenJDK 64-Bit Server VM (build 17.0.10+7-Ubuntu-122.04, mixed mode, sharing)

如果你在 CentOS 或 RHEL 上，命令换成 yum：

sudo yum install java-17-openjdk-devel -y

2.2.2 在 macOS 上安装

我用 Homebrew 管理 macOS 上的软件，一条命令搞定：

brew install openjdk@17

# 记得设置 JAVA_HOME
echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@17' >> ~/.zshrc
source ~/.zshrc

一个小技巧：

无论你用什么系统，装完后都跑一下 echo $JAVA_HOME。如果为空，Nextflow 虽然也能靠自动检测找到 Java，但某些高级功能会出问题。我建议显式设置 JAVA_HOME。

2.3 安装 Nextflow

Nextflow 的安装过程，应该是这三个里面最简单的，因为它本质上就是一个脚本。

2.3.1 标准安装流程

# 下载安装脚本
curl -s https://get.nextflow.io | bash

# 把可执行文件移到 PATH 目录
sudo mv nextflow /usr/local/bin/

# 验证安装
nextflow info

# 期望输出中能看到版本号和系统信息

我第一次装的时候，忘记加 sudo mv，结果 nextflow 命令找不到。后来检查才发现文件在当前目录下，需要手动移过去。嗯，这是个小插曲，你装的时候留意一下。

2.3.2 从 GitHub Release 安装（备选方案）

如果你在公司内网，访问外网受限，也可以手动下载：

# 访问 https://github.com/nextflow-io/nextflow/releases
# 下载 nextflow-24.04.2-all 文件

# 重命名并赋予执行权限
mv nextflow-24.04.2-all nextflow
chmod +x nextflow
sudo mv nextflow /usr/local/bin/

2.3.3 版本管理与升级

我项目中经常需要切换 Nextflow 版本，因为不同项目依赖的语法版本不同。Nextflow 提供了很方便的版本管理：

# 查看已安装的版本
nextflow self-version

# 升级到最新稳定版
nextflow self-update

# 锁定到特定版本（非常实用！）
export NXF_VER=24.04.2
nextflow info

避坑指南：

我曾经在一个生产项目中，因为全局升级了 Nextflow 版本，结果管道里的某些 API 不兼容了，回滚花了一上午。后来我养成了一个习惯：在项目的 nextflow.config 里显式指定版本：

// nextflow.config
manifest {
  nextflowVersion = '>=22.10.0, <25.0.0'
}

这样即使全局升级，项目也会提示版本匹配问题，不会直接跑。

2.4 安装 Docker

容器化是 Nextflow 的灵魂。我们做空间质控，涉及的工具链特别多，没容器简直寸步难行。

2.4.1 Docker Engine 安装

Ubuntu 上的标准流程：

# 安装依赖
sudo apt install apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证
sudo docker run hello-world

2.4.2 非 root 用户运行 Docker

我个人特别建议你把这步做了，否则每次跑 Nextflow 都要加 sudo，很烦：

# 把用户加入 docker 组
sudo usermod -aG docker $USER

# 登出再登入，或者直接：
newgrp docker

# 测试
docker ps

提醒一句：

如果你用的是服务器集群，Docker 可能没有 root 权限。这种情况下别折腾赛博安装，直接换 Singularity。其实很多 HPC 环境都禁用了 Docker。

2.5 安装 Singularity

Singularity（现在叫 Apptainer）是 HPC 领域的主流容器方案。我在很多超算中心跑过项目，Singularity 几乎成了事实标准。

2.5.1 从源码编译（推荐）

这是最稳妥的方式：

# 安装依赖
sudo apt install build-essential libssl-dev uuid-dev libgpgme11-dev \
  squashfs-tools libseccomp-dev pkg-config

# 安装 Go（Singularity 用 Go 编写）
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# 克隆并编译
git clone https://github.com/sylabs/singularity.git
cd singularity
./mconfig
make -C builddir
sudo make -C builddir install

# 验证
singularity --version

2.5.2 从包管理器安装（简单版）

# Ubuntu
sudo apt install singularity-container -y

# CentOS
sudo yum install singularity-container -y

包管理器版本通常比较老，但胜在简单快捷。如果是本地开发，够用了。

Docker vs Singularity 怎么选？

场景推荐什么理由
本地开发 / 笔记本电脑Docker生态丰富，社区活跃，调试方便
HPC 集群 / 超算中心Singularity安全模型适配多用户环境，不需要 root
混合团队协作两者都支持Nextflow 可以无缝切换，在配置里指定即可

2.6 环境验证：跑一个 Hello World

环境搭好了，得测一下是不是真的通了。我习惯跑一个最简管道：

# 创建一个简单的 Nextflow 脚本
cat > hello.nf << 'EOF'
nextflow.enable.dsl=2

process sayHello {
    debug true

    script:
    """
    echo "Hello, Nextflow!"
    echo "Java version: \$(java -version 2>&1)"
    """
}

workflow {
    sayHello()
}
EOF

# 分别用 Docker 和本地模式跑一次
nextflow run hello.nf -process.container ubuntu:latest -with-docker
nextflow run hello.nf

如果控制台输出里有两行 "Hello, Nextflow!"，恭喜你，环境搭好了！

我的习惯：

我会把这个 hello.nf 脚本放到每个项目的根目录，方便新同事入职时快速验证环境。你想想看，要是新同事第一天连环境都跑不通，多憋屈。有这个脚本，5 分钟就能确认问题在哪一层。

2.7 常见问题速查

现象可能原因怎么解决
java: command not foundJava 未安装或 PATH 没配检查 JAVA_HOME，确认安装路径
nextflow: command not foundNextflow 可执行文件不在 PATH检查 /usr/local/bin/ 下有没有 nextflow
Docker: permission denied用户不在 docker 组运行 sudo usermod -aG docker $USER 然后重新登入
Singularity: command not found安装路径没加入 PATH检查编译安装后的 bin 目录
管道跑起来特别慢网络拉取 Docker 镜像慢配置国内镜像源或使用 Singularity 预拉取

2.8 本章总结

这一章的核心就是把三个基础工具装好：Java、Nextflow、Docker/Singularity。

  • Java 选 17 或 21 LTS，别纠结版本号
  • Nextflow 用 curl 一键安装，配好 NXF_VER 做版本管控
  • 容器本地开发用 Docker，集群环境用 Singularity

你装完之后，强烈建议跑一遍 Hello World 测试用例。这一步花不了 5 分钟，但能排除掉 90% 的环境问题。

行，环境准备好了。下一部分我们就要开始真正接触 Nextflow 的核心语法了。

← 上一章 📖 返回目录 下一章 →