如何在Gradle的@OutputDirectory中过滤文件？解决任务缓存失效问题

我开发了一个自定义Gradle任务，用于执行Node.js的npm脚本（Shell命令）。该脚本以package.json配置文件为输入，输出node_modules目录。任务代码如下：

@get:InputFile
abstract val packageJson: RegularFileProperty

@get:OutputDirectory
abstract val nodeModules: DirectoryProperty

问题在于，npm会在node_modules中创建指向另一个项目的符号链接，该项目包含每次构建都会被修改的临时文件，导致Gradle判定输出发生变更，任务无法保持最新状态。请问如何过滤@OutputDirectory中的文件？或有其他可行的解决办法吗？

解决方案1：过滤输出文件（Gradle 7.0+） #

用@OutputFiles替代@OutputDirectory，通过文件树过滤规则排除符号链接，让Gradle只追踪实际需要的文件：

@get:OutputFiles
val nodeModulesFiles: FileCollection
    get() = project.fileTree(nodeModules) {
        // 排除所有符号链接
        exclude { file -> file.isSymbolicLink }
        // 也可以针对性排除特定链接，比如指向某外部项目的链接
        // exclude { file -> file.isSymbolicLink && file.targetFile.absolutePath.contains("/path/to/your/external/project") }
    }

这种方式能精准控制Gradle追踪的输出内容，避免外部文件变更干扰任务的最新状态判定。

解决方案2：调整路径敏感度 #

如果符号链接本身的目标路径不会变更，只是目标项目内的临时文件变化，可以降低输出目录的路径敏感度，让Gradle只检查文件/目录的名称和结构，不追踪链接目标的内容：

// 在任务配置块中添加
nodeModules.pathSensitivity = PathSensitivity.NAME_ONLY

注意：此方法会降低增量构建的精度，仅适合确认node_modules的文件结构不会发生变更的场景。

解决方案3：任务后清理问题链接 #

在任务执行完成后，直接删除引发问题的符号链接，从输出目录中移除干扰项：

abstract class NpmInstallTask : DefaultTask() {
    @get:InputFile
    abstract val packageJson: RegularFileProperty

    @get:OutputDirectory
    abstract val nodeModules: DirectoryProperty

    @TaskAction
    fun execute() {
        // 执行npm install逻辑
        project.exec {
            commandLine("npm", "install")
            workingDir(packageJson.get().asFile.parentFile)
        }

        // 删除指定的问题符号链接
        val problematicLink = nodeModules.file("target-linked-project").get().asFile
        if (problematicLink.exists() && problematicLink.isSymbolicLink) {
            problematicLink.delete()
        }
    }
}

解决方案4：自定义输出快照策略（高级场景） #

通过实现FileSystemLocationSnapshotter自定义Gradle的快照逻辑，彻底排除符号链接的追踪：

class NoSymlinkSnapshotter : FileSystemLocationSnapshotter {
    override fun snapshot(location: FileSystemLocation, context: FileSystemLocationSnapshotterContext): FileSystemLocationSnapshot {
        return if (location is Directory) {
            val dir = location.asFile
            val validSnapshots = dir.walk()
                .filter { !it.isSymbolicLink }
                .map { context.snapshotter.snapshot(it, context) }
                .toList()
            DirectorySnapshot(dir.absolutePath, validSnapshots, true)
        } else {
            context.snapshotter.snapshot(location, context)
        }
    }
}

// 在任务中注册快照器
tasks.withType<NpmInstallTask> {
    outputs.registerOutputLocationSnapshotter(NoSymlinkSnapshotter())
}

该方法适合需要完全自定义输出追踪规则的复杂场景。

内容的提问来源于stack exchange，提问作者Vitaliy Tsirkunov