📚 课程目录第4章 Nextflow语法基础

4. Nextflow 语法基础：DSL2 语法、脚本结构、参数定义

DSL2 是 Nextflow 从 DSL1 演进过来的核心语法模式。说白了，它让流程变得更像「搭积木」——每个 process 是独立的功能块，workflow 块负责把这些块串起来。我记得刚开始从 DSL1 迁移到 DSL2 时，最直观的感受就是：终于不用在一个文件里堆上千行代码了。

4.1 DSL2 到底改了啥？

DSL2 不是简单的语法升级，而是设计思路的转变。它引入了三个核心概念：模块化、作用域隔离和显式数据流。

模块化：每个 process 可以单独放在一个文件里，用 include 导入。团队协作时，各人改各人的模块，互不干扰。
作用域隔离：process 内部的变量、标签、指令只在本 process 内生效。不会像 DSL1 那样，一不小心变量就串了。
显式数据流：通道（channel）的输入输出必须在 process 定义里明确声明。数据怎么流、流到哪里，一眼就能看明白。

你想想看，一个流程涉及几十个步骤，如果每个步骤的依赖关系都是「隐式」的，调试起来得多痛苦？DSL2 把这一切摆到了台面上。

小提示：DSL2 默认是开启的。如果你在代码开头写 nextflow.enable.dsl=2，其实是多此一举——从 Nextflow 21.x 版本开始，DSL2 已经是默认模式了。

4.2 脚本结构：main.nf 到底该怎么组织？

一个典型的 DSL2 项目，核心文件就是 main.nf。它一般分成三个区域：参数定义区、workflow 块和 process 定义（或者 include 导入）。

我个人习惯把 workflow 块放在最前面，参数定义紧随其后，process 定义放在最后或者单独拆成模块文件。这样读代码的人第一眼就能看到流程的主干，而不是被细节淹没。

来看一个最小但完整的 DSL2 脚本结构：

// 1. 参数定义区
params.input = "$projectDir/data/*.fastq"
params.outdir = "results"
params.prefix = "sample"

// 2. workflow 块 —— 流程主干
workflow {
    Channel.fromPath(params.input)
        | split_fasta
        | align_sequence
        | collect_results
}

// 3. process 定义
process split_fasta {
    input:
    path reads

    output:
    path "chunk_*"

    script:
    """
    split -l 1000 $reads chunk_
    """
}

process align_sequence {
    input:
    path chunk

    output:
    path "aligned_*"

    script:
    """
    aligner --input $chunk --out aligned_${chunk}
    """
}

process collect_results {
    input:
    path aligned

    output:
    path "final_result.txt"

    script:
    """
    cat $aligned > final_result.txt
    """
}

你注意看，这个脚本的 workflow 块里用了管道操作符 |。它把 split_fasta 的输出直接传给了 align_sequence，数据流向一目了然。

  核心点：workflow 块只负责编排，不负责实现。具体的计算逻辑全在 process 里。这就是「关注点分离」——编排和实现分开，改流程时不碰逻辑，改逻辑时不碰流程。

4.3 参数定义：params 的优先级与陷阱

参数定义看似简单，其实有不少门道。Nextflow 里参数统一放在 params 对象下，但它的值可以从多个来源覆盖。我记得有一次帮同事排查问题，他明明在脚本里写了 params.genome = "hg38"，可运行时却一直报错说参考基因组路径不对。查了半天，发现是配置文件里写了个旧的路径，把脚本里的默认值覆盖掉了。

参数优先级从高到低是这样的：

优先级	来源	示例
最高	命令行参数	`--genome mm10`
高	配置文件（-c 指定）	`params.genome = "mm10"`
中	全局配置文件（nextflow.config）	`params.genome = "mm10"`
低	脚本内默认值	`params.genome = "hg38"`

命令行参数的优先级最高，脚本内的默认值最低。这是设计上的刻意安排——让用户可以在不修改脚本的情况下，灵活地覆盖任何参数。

参数的数据类型也很容易踩坑。Nextflow 会根据上下文自动推断类型，但偶尔会猜错。我曾经遇到过一个问题：

// 这个参数看起来是字符串，但 Nextflow 会把它解析为数字
params.threads = "4"

// 更安全的做法是直接写数字
params.threads = 4

// 或者保留字符串但明确场景
params.label = "high_mem"

如果你在命令行传 --threads 4，它会变成字符串 "4"，但在某些上下文中可能会被当作数字处理。嗯，这里要注意：关键计算参数建议用数字类型，标识类参数用字符串。

避坑指南：我曾经在调试一个多步流程时，发现某个 process 总是拿不到正确的参数值。最后发现是参数名拼写不一致——workflow 块里用的是 params.sample_id，process 里读的却是 params.sampleId。参数名一定要前后统一，最好在脚本头部集中定义，不要散落在各个 process 里。

4.4 从参数到配置的桥梁

参数定义还有一个容易被忽略的功能：为不同运行环境预设参数集。配合 nextflow.config 里的 profiles，你可以把参数按环境分类管理。

// nextflow.config
profiles {
    test {
        params.input = "$projectDir/test_data/*.fastq"
        params.genome = "test_genome.fa"
        params.threads = 2
    }
    production {
        params.input = "/data/raw/*.fastq"
        params.genome = "/data/references/hg38.fa"
        params.threads = 32
    }
}

运行时只需要指定 profile：

nextflow run main.nf -profile test

这样测试环境和生产环境的参数就完全隔离开了。我建议团队都采用这种方式，避免「测试时跑得好好的，上了生产就崩」的尴尬。

参数定义本身不复杂，但它是整个流程配置的基石。把参数管理好，后续的维护成本会低很多。

4.5 本章知识结构

下面这张图展示了 DSL2 脚本的核心结构，以及各个部件之间的关系。你可以把它当作一个「路线图」，写任何流程时都可以对照着检查框架是否完整。

从这个结构图你可以看出，DSL2 的核心思想就是「分而治之」——参数、编排、实现三者分离，每个部分只关注自己的职责。掌握这个结构，你写出来的流程自然就清晰、好维护。