参数定义与覆盖：params、default参数、命令行覆盖

参数管理这件事，我刚开始用Nextflow时觉得很简单。不就是设几个变量嘛？结果第一次部署生产环境就栽了跟头——开发机跑得好好的配置，到集群上全乱套了。后来才明白，参数定义和覆盖的优先级才是多环境配置的核心命门。

说白了，params就是Nextflow里最灵活的变量容器。它不像硬编码那样死板，也不像环境变量那样绕弯子。你可以在配置文件里设默认值，在命令行里临时覆盖，甚至在不同profile里给不同值。这一整套机制，就是我们今天要啃下来的硬骨头。

参数本质：一个可覆盖的键值对

在Nextflow里，所有用户自定义参数都通过 params 对象传递。这个对象本身是个Map，你可以在 main.nf 里这样访问：

params.genome = "GRCh38"
params.reads  = "data/sample.fastq.gz"

但这里有个坑——在 main.nf 里硬编码参数是坏习惯。我在项目中见过有人直接写死了路径，结果换一台机器就得改脚本本身。正确的做法是把参数定义全部交给 nextflow.config。

默认值定义：nextflow.config 是主战场

配置文件里用 params 块定义参数，这是最标准的方式：

params {
    genome = "GRCh38"
    reads   = "data/sample.fastq.gz"
    outdir  = "results"
    max_cpus = 8
}

我个人习惯把 所有 可能变化的值都丢进 params。哪怕你觉得某个值永远不改，也先放进去——哪天需求变了你就知道这个习惯多值钱了。你在代码里只引用 params.outdir，而不是写死 result 字符串。

运行时覆盖：命令行才是最终老板

Nextflow最爽的一点是——命令行参数可以覆盖配置文件里的一切。语法很简单，用双横线：

nextflow run main.nf --genome "hg38" --reads "data/new_sample.fastq.gz"

这条命令执行时，params.genome 和 params.reads 都会被替换。你可以在同一个命令里覆盖任意多个参数。我曾经为一个客户做部署，他的需求是同一个管道，每次跑不同数据集。解决方案就是：配置里写通用默认值，命令行每次传不同的 --reads 和 --outdir。简单、干净、不出错。

参数覆盖优先级：一张表说清楚

什么值最终生效？优先级从低到高是这样的：

优先级逻辑其实很简单：谁离执行时越近，谁说了算。命令行是运行时敲的，所以它权限最大。profile在命令行之前加载，排在第二。

避坑指南：参数覆盖的常见陷阱

陷阱一：路径里写变量，忘记用引号。

# 错误示例
nextflow run main.nf --indir /data/samples/v1.0

如果路径包含空格或特殊字符，必须用引号包起来：

nextflow run main.nf --indir "/data/samples/v1.0"

陷阱二：同一参数在多个地方定义，以为“就近原则”就够了。 不完全是。优先级规则是固定的，你不能在脚本里写死参数然后指望命令行覆盖——main.nf 里如果用了 def genome = "GRCh38" 而不是 params.genome，命令行 --genome 就根本覆盖不了它。所以切记：所有可配置参数必须走 params。

陷阱三：命令行覆盖后，不检查就往下跑。 我曾经有一次在集群上提交任务，命令行传了 --outdir /lustre/team/project_abc，结果那个路径写错了一个字母。管道跑了6小时，输出全部跑到了错误目录，清理起来巨麻烦。我的教训是：在管道开头就打印 params 的值，确认无误再继续。

// 在 main.nf 开头加一行
log.info """Pipeline parameters:
  genome: ${params.genome}
  reads:  ${params.reads}
  outdir: ${params.outdir}
"""

profile中的参数策略

多profile场景下，参数覆盖更灵活。一种常用策略是：在profile块里写“环境专属值”，而通用默认值保留在外层 params：

params {
    genome = "GRCh38"
    reads   = "$projectDir/data/sample.fastq.gz"
    outdir  = "results"
}

profiles {
    prod {
        params.genome = "hg38"
        params.outdir = "/shared/results"
        process.executor = "slurm"
    }
    test {
        params.reads = "$projectDir/data/test.fastq.gz"
        params.outdir = "test_results"
    }
}

你看，prod profile只覆盖 genome 和 outdir，reads 没动就继续用外层默认值。这就是按需覆盖的思想——你不需要在profile里把每个参数都抄一遍，只改需要变的部分就好。

本段核心逻辑图

参数的最佳实践清单

1. 全部走 params：脚本里不要出现硬编码路径或常数。哪怕你觉得某个值永远不变，也先放到 nextflow.config 里。
2. 默认值要“温和”：CPU用4而不是64，内存用2GB而不是128GB。让新用户拉下来就能跑，不浪费资源。
3. profile里只覆盖差异：不要在每个profile里重复定义所有参数，只改环境真正需要变的部分。
4. 运行前打印参数：在 workflow 块开头加一行 log.info，输出当前所有参数值。这是最便宜的保命手段。
5. 命令行参数一定要校验：如果你自己写CI/CD脚本，在 nextflow run 之前先用shell检查传参是否符合预期格式。我曾经见过有人传 --outdir "/tmp/" （末尾多了个空格），结果路径转义出了问题。