工作目录与缓存存储位置：配置缓存路径与命名规范
缓存复用的前提是什么？简单说就是：Nextflow 得知道去哪里找上次跑的结果。如果路径飘忽不定，缓存就不可能被命中。这一章，咱们就聊聊工作目录、缓存存放位置和命名规范——这些看起来基础，但踩坑的人真不少。
核心三要素：workDir、scratchDir、cacheDir
很多刚用 Nextflow 的朋友，上来就写 pipeline，跑完发现第二次重跑居然从头开始。我排查了半天，最后发现是 workDir 和缓存路径没配对。
这三个路径各管各的活：
- workDir：任务执行的工作目录。所有中间文件、临时文件都放这里。
- scratchDir：临时存储区域，通常用于 HPC 集群的本地磁盘。任务跑完之后，结果会被同步回 workDir。
- cacheDir：缓存复用目录。Nextflow 在这里存放缓存指纹和元数据，用来判断任务是否能复用。
| 目录 | 用途 | 默认位置 | 我建议的推荐配置 |
|---|---|---|---|
| workDir | 任务执行、中间文件 | ./work | 持久化存储（如 NFS、对象存储桶） |
| scratchDir | 临时本地缓存（减少 I/O 冲突） | 无 | SSD 或本地 NVMe，任务结束后自动清理 |
| cacheDir | 缓存复用元数据 | $NXF_HOME/cache | 与 workDir 相同的持久化存储，但独立目录 |
缓存路径配置实战
我个人习惯把缓存配置放在 nextflow.config 里，而不是靠环境变量或命令行参数。为什么？因为配置文件可以版本化管理，团队成员拉下来就能用，不会出现「我本地能复用，你那边就缓存穿透」的尴尬。
workDir = '/data/nextflow/work'
cacheDir = '/data/nextflow/cache'
scratchDir = '/local/scratch'
嗯，这里有个细节：scratchDir 我一般配成集群节点的本地 SSD。这样做的好处是任务读写的 IO 压力不会打到共享存储上，cache 的命中率也能稳定一些。
命名规范：别让缓存撞了
你想想看，如果两个不同的 pipeline 用了同一个 workDir，会发生什么？缓存指针乱指，A pipeline 的缓存被 B pipeline 覆盖，跑出来的结果还不对。说白了，就是缓存碰撞。
如何避免？我在项目中统一了一套命名规范：
- 每个 pipeline 使用独立的 workDir 子目录
- 缓存路径包含 pipeline 名称和版本号
- 同一个项目下不同分支（开发、测试、生产）使用不同的缓存标识
举个例子：
workDir = "/data/nextflow/work/${params.pipeline_name}/${params.pipeline_version}"
cacheDir = "/data/nextflow/cache/${params.pipeline_name}/${params.pipeline_version}"
为什么带上版本号？有一次我把流程从 v2.1 升级到 v2.2，只改了少量参数。如果不做版本隔离，Nextflow 会认为缓存有效，结果输出了一些陈旧结果。版本号就是一道保险。
更细致的做法是加入 commit hash 或环境标签：
workDir = "/data/nextflow/work/${params.pipeline_name}/${params.branch}/${params.commit_short}"
commit_short 变量。这样开发分支的缓存不会污染主分支，pr 评审时也能保证缓存独立。
避免 $PWD 陷阱
我早期有一个项目，同事在集群上跑 pipeline，每次提交作业都要从不同目录进入。workDir 配成了 $PWD/work，结果每次作业的绝对路径都不一样。缓存命中率可想而知——几乎为零。
这个问题的根源在于：Nextflow 的缓存哈希计算默认包含了 workDir 的完整路径。路径一变，缓存就失效。
解决办法：
- 使用绝对路径定义 workDir，避免依赖
$PWD - 如果必须用相对路径，确保工作目录固定不变（比如用绝对路径的符号链接）
- 在配置文件中用
baseDir作为相对路径的锚点
workDir = "${projectDir}/../shared_work/pipeline_work"
cacheDir = "${projectDir}/../shared_work/pipeline_cache"
projectDir 是 Nextflow 内置变量，指向 pipeline 主目录。即使你切换到其他目录执行，这个值也是固定的。我用这个方式之后，缓存命中率从 30% 提升到了 85% 以上。
缓存路径的另一种模式：锁定 session
如果你在同一个 workDir 下跑了上百个实验，每次都要手动清理缓存吗？我建议开启 session 隔离：
nextflow run main.nf -with-docker -resume -work-dir /data/work/project_x
加上 -work-dir 参数，每次实验用不同的路径。这种方式适合探索性分析，每个 session 的缓存完全隔离，不会相互干扰。
但要注意：session 用完后记得清理。我见过有人跑了几百个实验，workDir 下堆了几 TB 的中间文件，最后 NFS 直接撑爆了。
我的经验总结：
- 生产环境：用版本化的绝对路径，workDir 和 cacheDir 绑定
- 探索性分析：用
-work-dir参数每次指定新路径，事后清理 - 长期维护的项目：把路径信息写入项目文档，或者直接放在 nextflow.config 里版本控制
核心知识结构
下面这张图展示了 workDir、cacheDir 和 scratchDir 之间的关系，以及缓存复用的判断流程：
集群环境与云环境的差异
不同环境下，缓存路径的配置策略也有区别。我整理了一份对比：
| 环境 | workDir 推荐 | cacheDir 推荐 | 需要注意的点 |
|---|---|---|---|
| 本地 / 单机 | 快速 SSD 或 NVMe | 同一目录下的 .nf_cache 子目录 | 避免写入系统盘的 /tmp |
| HPC 集群 (Slurm/PBS) | 共享 NFS 或 Lustre | 同一共享文件系统下的独立目录 | scratchDir 配本地 SSD，减少 NFS 压力 |
| 云原生 (AWS/GCP Batch) | S3 / GCS 对象存储 | 对象存储下的 /cache 前缀 | 缓存元数据读写可能产生少量请求费用 |
我曾经在 AWS Batch 上吃过一次亏：workDir 配在 S3 上，但 cacheDir 忘了改配置，默认写到了计算节点的本地盘。作业一结束节点销毁，缓存全没了。后面加了 -cache-dir 参数指向 S3 的 s3://bucket/cache，才彻底解决问题。