📚 课程目录第3章缓存键（Cache Key）的组成

缓存键的核心：输入文件、参数与环境

缓存复用这件事，说简单也简单——Nextflow 会算一个哈希值，匹配上了就直接拿上次的结果。但你真的搞懂这个哈希是怎么算的吗？

我记得刚接触 Nextflow 那会儿，遇到一个奇怪的现象：同一个 pipeline，换了个服务器跑，居然全部重跑了。我当时还以为是集群配置问题，折腾了大半天，最后才发现是缓存键里的"环境"部分变了。嗯，从那以后我就格外重视缓存键的组成。

先给你一个总览图，把缓存键的三个维度画清楚。

输入文件：不只有文件名

Nextflow 默认追踪输入文件的元数据（metadata）。说白了，它不光看你文件叫啥，还会看文件大小和最后修改时间。我见过最典型的坑是：从同一个 S3 桶下载的文件，因为是全新的对象，修改时间变了，Nextflow 认为文件不一样，于是全部重跑。

为什么会这样？因为 Nextflow 默认用的是 path 类型参数，它会去 stat 文件。如果你的管道频繁读取外部数据源生成的文件，要小心这个行为。

看看默认行为长什么样：

process SAMPLE {
    input:
    path fastq

    script:
    """
    fastqc ${fastq}
    """
}

上面的 path 声明导致 Nextflow 会用 stat 信息做缓存键。如果文件内容没变，但元数据变了，缓存依然会失效。

那我怎么解决？两种思路：

使用 file 类型替代 path —— 但这是旧语法，不推荐。
用 stageAs 或 toFile 把文件内容哈希提前注入：手动指定缓存键里的文件指纹，而不是依赖元数据。

我个人习惯在 process 定义里加上 cache 指令，明确告诉 Nextflow 怎么对待输入：

process SAMPLE {
    cache 'deep'

    input:
    path fastq

    script:
    """
    fastqc ${fastq}
    """
}

'deep' 模式会让 Nextflow 计算文件的 MD5 内容哈希，而不是仅仅用元数据。代价就是第一次要大算一遍所有文件的 MD5，但后续重跑率会大大降低。

警告：如果你用 cache 'deep'，而且输入文件特别大（比如上百GB的BAM文件），首次计算MD5的时间会非常长。我曾经在一个肿瘤分析项目里吃过这个亏——单文件20GB，500个样本第一次跑多了整整8小时。等你想明白这个逻辑的时候，进度条已经走了一大半。

参数：别漏掉，也别多算

参数方面，Nextflow 会把你写在 params 里以及在 process 内部显式引用的参数都纳入缓存键。但你想想看，如果你在 process 里用了一个没有在 params 中声明的变量，会发生什么？

它也会被哈希进去！

我记得有一次，我在 pipeline 里临时写了个调试用的变量：

params.debug_level = 0

process ALIGN {
    input:
    path reads

    script:
    def extra = params.debug_level > 0 ? "--verbose" : ""
    """
    bwa mem ${extra} reference.fa ${reads} > aligned.sam
    """
}

假设我之前跑的时候 debug_level=0，后来改成 1 再跑，Nextflow 会发现参数变了，于是重新执行 ALIGN 步骤。这很合理。但不合理的是，如果你在 nextflow.config 里添加了一个完全无关的参数，而某个 process 无意中引用了它，缓存照样会废掉。

避坑指南：用 params 配合 set 指令，把只影响某一 process 的参数明确限定作用域：

process ALIGN {
    pub: 'samtools sort', conda: 'samtools=1.9'
    input:
    path reads
    each alignment_param  // 只传需要的参数

    script:
    """
    bwa mem ${alignment_param} reference.fa ${reads} | samtools sort > aligned.bam
    """
}

这样 Nextflow 只把 alignment_param 作为缓存键的一部分，其他全局 params 不会影响 ALIGN 的缓存命中。

小技巧：可以用 params.help 或 params.meta 这类运行说明参数加 @ 前缀，或者通过 nextflow.config 里的 env 块注入，明确哪些不参与缓存计算。我一般会在 pipeline 开头加一段日志输出，把参与缓存键的参数显式打印出来，便于调试。

环境：容器、conda 与模块

环境是缓存键里最隐蔽的变量。Nextflow 会把 process 中声明的 container、conda 或 module 指令内容纳入哈希。为什么说隐蔽？因为容器镜像标签虽然没变，但镜像内部可能已经发生了「滚动更新」。

举个例子：

process FASTQC {
    container 'biocontainers/fastqc:v0.11.9'

    input:
    path seq

    script:
    """
    fastqc ${seq}
    """
}

你用的标签 v0.11.9，在 Docker Hub 上可能被维护者重新推送了同一标签的不同内容。Nextflow 只认标签字符串，不会去校验镜像的实际 ID。所以你拿到的「新」镜像和以前「旧」镜像可能不同，但缓存键没变。反过来，当你真的更新了标签（比如改成 v0.12.0），缓存键变了，所有用到这个容器的 process 都会重跑。

我建议的做法：

如果追求彻底稳定，用镜像 manifest 的摘要（digest），比如 container 'biocontainers/fastqc@sha256:xxxx'。这样容器内容变了，摘要不同，缓存自动失效。
如果追求效率，比如在开发阶段频繁换环境，那干脆把 container 声明抽到 nextflow.config 里，通过参数控制环境切换，方便手动清缓存。

  亮点方案：我最近在一个团队里用 workflow-level cache 配合 -resume 做 CI 加速，把 Docker 镜像的 sha256 写入配置文件，每次 CI 构建时自动算一次摘要，如果业务代码没变但镜像变了，缓存自动失效，不需要人工干预。

实战：如何查看缓存键

Nextflow 不会直接告诉你缓存键是什么，但你可以通过日志和 .nextflow/cache 目录来反推。跑一个 pipeline 之后，看一下运行日志：

executor >  local (1)
[c6e1a2] process > FASTQC (sample1) [100%] 1 of 1
[c6e1a2] process > FASTQC (sample2) [100%] 1 of 1

那个 [c6e1a2] 就是每个 process 实例的缓存键前缀（实际完整哈希位数更多）。如果两次跑同一个样本，这个前缀相同，说明缓存命中；不同说明某个维度变了。

你也可以通过 -dump-channels 参数看到更详细的执行图：

nextflow run main.nf -dump-channels

输出会列出每个 channel 的输入、参数和环境，帮你在调试阶段追踪缓存变更原因。

我们拿一个简单对照表总结一下：

缓存键维度	默认行为	常见陷阱	推荐做法
输入文件	文件名+大小+修改时间	软链接、多次复制导致元数据不同	用 `cache 'deep'` 或手动计算内容哈希
参数	显式 `params` + process 内引用	未声明变量也被哈希；默认值变化	用 `each` 限定作用域；`params` 显式声明所有参数
环境	`container`/`conda`/`module` 字符串	容器镜像滚动更新；conda 环境重建	用镜像 digest；或把环境声明统一放到 config 中管理

好了，这一章讲到这里。核心就是记住：缓存键不是你想象中那么黑盒，它由输入文件、参数和环境三个维度拼接而成。理解每个维度的默认行为，你就能精准控制什么时候重用、什么时候重跑。