📚 课程目录第4章配置文件（nextflow.config）的版本管理

配置文件（nextflow.config）的版本管理：参数分层、环境配置、profile管理

Nextflow 的配置文件，说白了就是整个流程的“总开关”。

我接手过不少别人写的流程，最头疼的就是翻 nextflow.config——里面参数和不同运行环境的配置混在一起，改一个地方就要全局搜索。后来我自己做版本管理的时候，就定了个规矩：必须把参数分层、环境配置和 profile 拆清楚。

参数分层：从全局到局部

Nextflow 的配置遵循一个清晰的覆盖链。你想想看，同一份流程要在本地测试、集群跑、云端部署，参数不可能全写死。它其实是这么个优先级（从低到高）：

Nextflow 内置默认值——比如 process.executor = 'local'。
用户级配置——$HOME/.nextflow/config，适用于本机所有流程。
项目级配置——流程目录下的 nextflow.config，最常用的地方。
Profile 内参数——通过 profiles 作用域指定的值。
命令行参数——-params-file 或直接 --param value，永远最高。

这个层次设计其实很优雅。举个例子，我在公司搭建了一个内部镜像仓库，就把镜像地址写在用户级配置里，这样所有同事都不用改项目文件。

层级	配置文件位置	覆盖范围	典型用途
1. 内置默认	——	全局	executor='local'
2. 用户级	`~/.nextflow/config`	当前用户	私有 token、默认镜像
3. 项目级	`${projectDir}/nextflow.config`	单个流程	流程特有参数
4. Profile	项目级中的 `profiles{}`	按 profile 分组	不同运行环境
5. 命令行	`--xxx` / `-params-file`	单次运行	临时调试、批量提交

注意：很多人混淆了 -params-file 和 nextflow.config 的关系。前者只覆盖 params 作用域，而后者可以定义 executor、conda 环境、resource 等全局设置。我曾经见过同事把 executor 写在 params-file 里，结果流程死活不认——因为它根本不解析那个字段。

Profile 管理：为不同场景而生的配置快照

我个人的习惯是，任何项目至少准备三个基础 profile：standard、conda、docker。哪怕初期只用一种容器方式，也要把其他 profile 的结构先搭好。为什么？因为你永远不知道明天领导会不会说“切换成 Singularity”。

典型的 profile 定义是这样的：

profiles {
    standard {
        process.executor = 'local'
        process.cpus = 2
        process.memory = '4 GB'
    }
    docker {
        process.executor = 'local'
        docker.enabled = true
        docker.imageRegistry = 'registry.example.com'
        process.container = 'my-workflow:latest'
    }
    slurm {
        process.executor = 'slurm'
        process.queue = 'normal'
        process.clusterOptions = '--account=myproject'
    }
}

这里有个容易被忽略的点：profile 之间不是继承关系。如果你在 standard 里设置了 process.cpus = 2，在 docker 里没写，那跑 -profile docker 时 cpus 就会退回到更底层的默认值或全局配置——而不是沿用 standard 的值。所以每个 profile 应当尽量独立写完整。

小技巧：用 includeConfig 可以把公共部分抽成独立文件。比如 params.common.config 放所有 profile 都需要的参数，然后在每个 profile 里 includeConfig 'params.common.config'。这样既复用又不依赖继承顺序。

环境配置：让流程跑在正确的地方

环境配置是版本管理的重灾区。我见过最离谱的是有人把数据库密码明文写在 nextflow.config 里，然后直接提交到 GitHub 公开仓库……

正确的做法是这样的：

敏感信息用环境变量——params.db_password = System.getenv('DB_PASSWORD')，再在 .gitignore 里把 nextflow.config 里包含密码的部分排除掉。
不同运行环境用不同环境变量文件——比如 source env/production.sh 再跑流程，而不是改配置文件。
Conda / Docker / Singularity 环境——在 profile 里明确指定 conda 或 container，并且把环境描述文件（environment.yml / Dockerfile）也纳入版本管理，但要和 nextflow.config 一起 tag 对应版本。

我推荐的项目结构是这样的：

my-workflow/
├── nextflow.config          # 主配置，不含敏感信息
├── conf/
│   ├── params.common.config  # 公共参数
│   ├── profiles/
│   │   ├── docker.config
│   │   └── slurm.config
│   └── secrets.config.example  # 示例，真正密码在 .gitignore 里
├── env/
│   ├── production.env
│   └── testing.env
├── environment.yml          # Conda 环境（版本控管）
└── Dockerfile               # 容器镜像（版本控管）

配置文件的版本管理策略

把 nextflow.config 放进 Git 是底线，但怎么放有讲究。

分隔敏感信息：用 conf/secrets.config 单独存放，并在 .gitignore 中加入这条。然后主配置通过 includeConfig 'conf/secrets.config' 引用。
版本与流程代码同步：每次发布流程新版本时，对应的 nextflow.config 也要打 tag。我曾遇到旧版流程用新版配置跑，结果 missing 参数导致崩溃——就是因为没做同步。
分支管理：对于需要长期维护的不同环境（比如内部测试分支 vs 生产分支），可以在主分支上保留一个 nextflow.config 模板，然后各环境分支只修改 profile 部分。但我个人更倾向于用 CI/CD 变量注入，而不是维护多个配置分支。

    核心原则：配置文件本身是代码的一部分。它应该像你的 main.nf 一样接受版本审查、测试和回滚。

常见陷阱与避坑

Profile 覆盖顺序错觉：如果你指定 -profile docker,slurm，两个 profile 会按顺序合并，后面覆盖前面。所以如果你要把 slurm 的 executor 应用到 docker 上，顺序应该是 docker,slurm。
路径相对性：nextflow.config 里的路径默认相对于 ${projectDir}，但如果你 includeConfig 了一个子文件里的路径，它是相对于子文件所在目录的——这个差异我曾经排查了一下午。
不要用 params 存放非参数配置：比如 params.executor = 'slurm'，这虽然能跑，但引擎根本不会读取 params 里的 executor。正确的做法是用 process.executor 或者写在 profile 里。