第3章 流程编写实战：输入、输出、参数、脚本与运行

好了，咱们今天来点真格的。前两章我把Nextflow的核心理念和安装环境聊了个遍，这一章，咱们直接上手写一个能跑的流程。

你可能觉得写流程就是堆砌命令行，其实不然。一个健壮的流程，核心在于四个要素：输入输出怎么声明、参数怎么传递、脚本怎么写才规范、以及运行时怎么控制资源。这些做好了，流程才能可复用、可调试。

我个人习惯，每次搭新流程时，都会先把这几个模块的骨架画好。咱们按这个顺序来拆解。

3.1 输入与输出：流程的“门”和“窗”

输入输出是数据流的边界。Nextflow里，输入不仅仅是文件路径，它更是一种通道（channel）的声明。

先看一个简单的例子，定义一个接收FASTQ文件的process：

process FASTQC {
    input:
    path read

    output:
    path "${read.baseName}_fastqc.zip"

    script:
    """
    fastqc ${read}
    """
}

这里有几个细节我想强调一下：

• 输入类型：用path声明文件，用val声明普通值，用env声明环境变量。我在项目中踩过坑，把路径当val传，结果Nextflow把它当字符串处理，导致内部路径解析出错。
• 输出模式：输出文件支持通配符。比如path "*.zip"会匹配所有zip文件。如果你不确定输出文件全名，用通配符更灵活。
• 通道连接：输出会自动连接到下一个process的输入。这也是管道设计的精髓所在。

3.2 参数传递：流程的“遥控器”

参数让流程变得可配置。Nextflow用params对象来管理所有用户可设置的参数。

通常，我会把参数定义写在main.nf文件的头部，或者单独写一个nextflow.config文件。我更推荐后者，因为配置文件和流程逻辑分离，维护起来更清爽。

举个例子，定义输入目录和输出目录：

// main.nf 文件头部
params.reads = "$projectDir/data/*.fastq.gz"
params.outdir = "./results"
params.genome = "hg38"

然后在process里这样引用：

process ALIGN {
    input:
    path reads

    output:
    path "${reads.baseName}.bam"

    script:
    """
    bwa mem ${params.genome} ${reads} > ${reads.baseName}.bam
    """
}

我还习惯在流程开头打印所有参数，方便追踪：

log.info """
╔═══════════════════════════════════╗
║ 流程参数                         ║
╠═══════════════════════════════════╣
║ reads    : ${params.reads}
║ outdir   : ${params.outdir}
║ genome   : ${params.genome}
╚═══════════════════════════════════╝
"""

你看，这样每次运行，日志里就清清楚楚地记录了当前使用的参数配置，排查问题的时候特别有用。

3.3 脚本编写：核心逻辑的正确“姿势”

脚本是每个process真正干活的地方。Nextflow默认用Bash，但也可以切换成Python、R等语言。需要注意的是，脚本块里的代码是在独立的工作目录下执行的，和流程脚本本身的环境是隔离的。

我总结了几个写脚本时的“黄金法则”：

• 尽量用绝对或相对路径：不要在脚本里用cd切换目录，直接通过Nextflow管理的文件路径来操作。
• 使用$projectDir：这个变量指向流程文件所在的目录。如果你的流程依赖一些辅助脚本，可以放在bin/子目录里，Nextflow会自动把它加到$PATH中。
• 避免硬编码临时文件：所有中间文件都生成在当前工作目录，Nextflow执行完后会自动清理。

来看一个完整的多步骤流程示例：

workflow {
    // 定义输入通道，读取所有fastq.gz文件
    Channel.fromPath(params.reads)
        | view { "处理文件: $it" }
        | FASTQC
        | ALIGN
}

process FASTQC {
    input:
    path reads

    output:
    path "${reads.baseName}_fastqc.zip"

    script:
    """
    fastqc ${reads}
    """
}

process ALIGN {
    input:
    path reads

    output:
    path "${reads.baseName}.bam"

    script:
    """
    bwa mem hg38 ${reads} > ${reads.baseName}.bam
    """
}

嗯，这里要注意：管道操作符|把每一步串起来，数据流很清晰。不过，如果中间某个process失败了，后面的步骤会自动跳过。这也是Nextflow设计里比较优雅的地方。

3.4 运行流程：从命令行到作业调度器

流程写好了，怎么跑？最简单的方式就是直接执行：

nextflow run main.nf

但实际项目中，我们通常需要指定参数、资源、以及执行环境。我常用的运行方式有这样几种：

我个人习惯是在nextflow.config里预定义好几个profile，比如：

profiles {
    standard {
        process.executor = 'local'
        process.cpus = 4
        process.memory = '8 GB'
    }
    cluster {
        process.executor = 'slurm'
        process.queue = 'normal'
        process.cpus = 8
        process.memory = '16 GB'
    }
    docker {
        docker.enabled = true
        docker.image = 'biocontainers/bwa:v0.7.17'
    }
}

然后运行时只需要指定profile：

nextflow run main.nf -profile cluster -params-file params.yaml

这样，用户只需要改params.yaml文件就能调整输入数据，而不用动流程代码。

3.5 一图胜千言：流程执行时的数据流

说了这么多理论，咱们用一张图来总结一下流程运行时的数据流向：

从这张图可以看到，数据从输入文件和参数出发，经过通道组装，流入一个个process。每个process都有自己独立的工作目录，互不干扰。执行环境（本地、集群、容器）决定了这些任务具体跑在哪台机器上。

3.6 避坑指南：我走过的那些弯路

最后，我把自己在实战中碰到的几个典型问题列出来，希望能帮你少走点弯路：

• 路径引用问题：在script块里，我习惯用$baseDir或$projectDir来引用流程脚本所在的目录。不要用$PWD，因为工作目录随时可能变化。
• 资源限制：曾经有一个混合计算任务，一部分需要大量内存，一部分需要大量CPU。我统一设了一个资源规格，结果内存密集型任务跑得慢，CPU密集型任务又浪费资源。后来我用withName语法对不同process设置不同资源，效率提升明显。
• 输入文件扫描：使用Channel.fromPath时，记得给个合理的glob模式，比如*_R{1,2}.fastq.gz。不然容易误扫进一些临时文件或目录。