1. 参数基础：认识 Nextflow 中的 params，定义与默认值设置

好，咱们直接进入正题。

你在写 Nextflow 流程的时候，肯定遇到过这种情况：一段代码里藏着几个需要调整的数值——比如输入文件路径、线程数、某个软件阈值。这些值如果直接硬编码在脚本里，换个项目、换个数据集就得翻箱倒柜地改代码。

嗯，这显然不是个聪明的做法。

Nextflow 早就替你想好了这个问题。它的答案是 params——说白了，就是一套全局的“参数容器”。你把所有可能变动的值放到这个容器里，在流程里引用它，然后在运行的时候通过命令行、配置文件甚至网页界面去覆盖。

什么是 params？

params 是 Nextflow 内置的一个 Map 对象。你可以在任何地方访问它——main.nf 里、模块文件中、甚至配置脚本里。它天然就是全局可见的。

我个人习惯用这个模式管理所有可配置项。举个例子，最基础的定义方式是这样的：

params.input_fastq = "/data/samples/control_R1.fastq"
params.outdir     = "./results"
params.threads    = 8
params.genome     = "GRCh38"

然后你在 process 里直接引用它们：

process align_reads {
    input:
    path fastq

    script:
    """
    hisat2 -p ${params.threads} -x index/${params.genome} -U $fastq > aligned.sam
    """
}

你看，只要改 params.threads 或者 params.genome，整个流程的运转方式就变了。这就是参数化的基本逻辑。

定义与默认值设置

定义参数的语法很简单。你可以在 main.nf 的顶部直接写 params.xxx = yyy，也可以把它放在单独的配置文件中。我更推荐后一种——把参数定义和业务逻辑分开，维护起来清爽很多。

下面是我的常见做法：

// 在 nextflow.config 中定义默认值
params {
    input_csv = ""
    outdir    = "./results"
    max_cpus  = 4
    max_memory = 8.GB
    skip_qc   = false
}

注意类型。Nextflow 会自动推断 skip_qc 是布尔类型，max_cpus 是整数。但有些情况你得显式声明——比如 max_memory 用了 8.GB 这种带单位的量，这会触发 Nextflow 的内存值校验机制，避免你在脚本里写错单位。

参数的覆盖顺序

为什么会强调“默认值”？因为 params 的最终值不是你写死的那一个。Nextflow 有一套明确的覆盖优先级：

优先级（高→低）	来源	示例
1	命令行 -params-file 或 --xxx	nextflow run main.nf --input_csv ./samples.csv
2	用户自定义配置文件 (-c)	nextflow run main.nf -c my.config
3	nextflow.config 中定义的默认值	params.input_csv = ""
4	流程硬编码（不推荐）	在 main.nf 中直接赋值

你想想看，这意味着什么？你可以在 nextflow.config 里放一套“保险”默认值，然后在实际运行时按需覆盖。流程代码本身不需要改一行。

类型安全与参数验证

Nextflow 的 params 本身不做类型强校验。这意味着你可以传字符串给一个期望整数的参数，流程照样跑，直到某个 process 因为类型错误而崩溃。嗯，这很尴尬。

我的习惯是加一段参数验证逻辑，放在流程启动的最前面：

// 验证关键参数
if (!params.input_fastq) {
    error "你必须指定 --input_fastq 参数，不能为空"
}

if (params.max_cpus < 1) {
    error "max_cpus 必须 >= 1，你的值是 ${params.max_cpus}"
}

if (!params.output_dir) {
    params.output_dir = "./results"
}

这里用到了 Nextflow 内置的 error 函数。一旦条件不满足，流程会在启动时直接终止，并给出清晰的错误提示。这样比跑到半路再炸锅要好得多。

参数与配置文件分离

很多人把参数全部写在 main.nf 里，然后通过注释来区分不同项目。我觉得这是“坏味道”。

更好的做法是：

• 通用默认值 → nextflow.config
• 每个项目的特定配置 → 独立的 .config 文件，如 mouse_rnaseq.config、human_wgs.config
• 运行时临时覆盖 → 命令行 --xxx 参数

这样你只需要管理一组配置文件，流程代码完全不动。我在一个项目中就是这样搞的：30 多种场景的配置各自独立，团队里谁跑哪个项目就加载对应的配置文件，再也不担心参数搞混。

# 命令行用法
nextflow run main.nf -c mouse_rnaseq.config

# 还可以叠加多个配置文件
nextflow run main.nf -c base.config -c mouse_rnaseq.config --input_fastq ./extra_data.fastq

注意叠加顺序：后面的 -c 文件会覆盖前面的同名参数。命令行 --xxx 参数永远优先级最高。

SVG：参数定义与覆盖的关系图

下面这张图可以帮你理清整个 params 的生命周期：

设计参数时的一些教训

这些年我在各种项目里折腾 params，踩过几个坑，说给你听听：

• 不要用中文/特殊字符做参数名——Nextflow 的 DSL 虽然是 Groovy 内核，但参数名是 Map 的键，用 ASCII 小写加下划线最安全。
• 同类参数用命名空间——比如 params.tools.bwa、params.tools.star，而不是 params.bwa_path、params.star_path。这样在配置文件中可以分组管理，结构清晰很多。
• 布尔参数用 is_ 前缀——比如 params.is_skip_qc，读起来更像自然语言。

推荐参数组织结构

下面是我常用的参数组织模板，你可以直接抄过去用：

params {
    // 必填参数（没有合理默认值）
    input_csv    = ""
    reference    = ""
    
    // 可选参数（有安全默认值）
    outdir       = "./results"
    logdir       = "./logs"
    
    // 资源参数
    max_cpus     = 4
    max_memory   = 16.GB
    
    // 功能开关
    is_dry_run   = false
    is_skip_qc   = false
    
    // 工具参数（命名空间化）
    tools {
        bwa_index = "/refs/bwa/hg38"
        star_index = "/refs/star/GRCh38"
    }
}

你可能会问：为什么不把所有参数放在一个大的 params 对象里？

这样你将来扩展流程时，只需要在 params 里新增一个字段，现有的所有代码不会受任何影响。这就是参数化的核心价值：让可变的逻辑外显，让不变的代码内隐。

好了，这一章就到这。你只要掌握了 params 的定义与默认值设置这两个基本动作，Nextflow 参数体系的大门就算推开了。