第 3 章 配置 Nextflow 环境：nextflow.config 基础

说实话，我刚开始用 Nextflow 的时候，最头疼的就是配置文件。你想想看，一个管道跑在本地好好的，换到服务器就崩了，后来才发现是资源没配对。nextflow.config 就是整个管道的“控制中心”，资源、队列、容器引擎、环境切换全归它管。这一章咱们就把这块硬骨头啃下来，配上几个我踩过的坑，保你少走弯路。

3.1 配置文件的结构与作用域

Nextflow 的配置逻辑其实不复杂，核心就一句话：作用域决定参数生效范围。最常用的是全局作用域，写在最外层；如果想给某个 process 单独设参数，就用 withLabel: 或 process.name 作用域。

// nextflow.config 示例
params.outdir = "./results"
params.genome = "hg38"

process {
    executor = 'local'
    cpus = 2
    memory = '4 GB'
}

docker {
    enabled = true
    image = 'nextflow/rnaseq-nf:latest'
}

我个人习惯把全局参数（比如输出目录、参考基因组路径）扔到 params 下面，运行时还能用 --param 覆盖。有个小技巧：把经常变的值抽象成 params，别写死。

3.2 资源与队列设置

我在项目中遇到过最烦的事：管道跑着跑着被集群管理员 kill 了，原因就是没设置队列和资源上限。Nextflow 本身不调度资源，它把工作交给底层执行器（executor）。你配好 executor、queue、cpus、memory，Nextflow 就按这些参数向作业系统提交任务。

process {
    executor = 'slurm'
    queue = 'highmem'
    cpus = 8
    memory = '32 GB'
    time = '2h'
    clusterOptions = '--gres=gpu:1'
}

注意：time 参数一定要设。为什么？因为集群默认作业时间很短，你不设就默认跑 30 分钟，大型分析根本跑不完。我曾经有个 RNA-seq 定量作业，没设 time，跑了 45 分钟被 kill，翻日志才发现超时 — 真是血泪教训。

3.3 容器引擎配置

容器是 Nextflow 管道的“保命符”——环境依赖全打包，换个机器照样跑。主流引擎就是 Docker 和 Singularity（HPC 场景首选）。配置方式差不多，看个例子：

docker {
    enabled = true
    image = 'ubuntu:22.04'
    runOptions = '-u $(id -u):$(id -g)'
    fixOwnership = true
}

singularity {
    enabled = true
    cacheDir = '/scratch/singularity'
    autoMounts = true
    runOptions = '--cleanenv --containall'
}

如果你在共享文件系统上跑，建议把 Singularity 的 cacheDir 设到本地 SSD 目录，否则每次拉镜像都很慢。我记得有一次团队共用 NFS 缓存，并发拉镜像直接把存储打挂了，从那以后我就强制每个人用 /tmp/singularity。

3.4 Profile 多环境切换

你想想看，开发环境和生产环境资源差异那么大，不可能手动改配置文件。Nextflow 的 profile 就是干这个的。定义好一组参数，运行时用 -profile 指定，自动加载对应配置。

profiles {
    local {
        process.executor = 'local'
        process.cpus = 2
        process.memory = '8 GB'
    }
    cluster {
        process.executor = 'slurm'
        process.queue = 'normal'
        process.cpus = 16
        process.memory = '64 GB'
        process.time = '48h'
    }
    test {
        includeConfig 'conf/test.config'
        process.executor = 'local'
        process.maxRetries = 0
    }
}

运行的时候：

nextflow run main.nf -profile cluster
nextflow run main.nf -profile test,local

多个 profile 可以叠加（逗号分隔），后面的覆盖前面的。我经常写一个 standard profile 放公共参数，再写 debug profile 只改日志级别和重试次数，调试时叠加用。

还有个坑：profile 内不能重复定义同一个参数，否则 Nextflow 会报错。我之前想把 process.cpus 单独放在两个 profile 里，合并时冲突出错，卡了半天。解决方案是用 includeConfig 拆分，或者用参数覆盖机制。

3.5 完整配置模板与结构图

下面是一个我在生产环境中使用的模板，融合了刚才讲的要点：

// nextflow.config
params.outdir = "./results"
params.fasta = "./ref/hg38.fa"

process {
    executor = 'slurm'
    queue = 'normal'
    cpus = 8
    memory = '32 GB'
    time = '24h'
    errorStrategy = 'retry'
    maxRetries = 2
}

docker {
    enabled = true
    image = 'myorg/mypipeline:latest'
    fixOwnership = true
}

profiles {
    local {
        process.executor = 'local'
        process.cpus = 4
        process.memory = '16 GB'
        process.time = '2h'
    }
    test {
        process.executor = 'local'
        process.cpus = 2
        process.memory = '8 GB'
        process.time = '30m'
        process.maxRetries = 0
    }
    debug {
        process.executor = 'local'
        log.level = 'DEBUG'
    }
}

看懂这张图，你就掌握了 nextflow.config 的骨架。以后每次建新管道，直接复制模板改几个参数就行。

3.6 写在后面的提醒

关于配置，还有几点值得记住：

• 参数的优先级：nextflow.config < profile < 命令行 --param。命令行最硬，会覆盖一切。
• 别在配置里写密码或 Token。用环境变量 NXF_SECRET_XXX 或者 params 动态传入。
• 检查你的配置：运行 nextflow config 可以打印最终合并后的配置，调试时特别有用。