JetBrains 插件开发：异步 VFS 写入与刷新指南

异步 VFS 内容写入 - 插件作者需要了解的内容 | JetBrains 平台博客

URL 源: https://blog.jetbrains.com/platform/2026/06/async-vfs-content-writes-what-plugin-authors-need-to-know/

Markdown 内容:

JetBrains 产品的插件和扩展开发。

JetBrains 平台插件

异步 VFS 内容写入 - 插件作者需要了解的内容

2026 年 6 月 3 日

一些插件代码遵循以下模式：

1. 保存打开的文档。
2. 获取文件或目录路径。
3. 将该路径传递给 IDE 之外的某些内容，例如格式器、检查器、编译器、VCS 命令、语言服务器或自定义 CLI 工具。

历史上，可以合理地假设一旦保存完成，磁盘上的文件已经包含最新的编辑器文本。

这不再是事实。

JetBrains 平台现在可以先更新 VFS，然后在后台稍后完成磁盘写入。通过 IntelliJ 平台文件 API 读取文件的代码仍然立即看到新内容。通过 Path、File、Files.* 或外部进程读取相同文件的代码可能需要显式刷新才能完成传递。

官方 SDK 文档在何时将 `VirtualFile` 变化持久化到磁盘并从磁盘加载到 VFS？中涵盖了这个合同。

**为什么存在**

对 VirtualFile 的写入必须在写操作下发生。到目前为止，保存文件通常意味着在写操作仍然打开时执行实际的文件系统写入。

当文件系统很慢、远程或通过 WSL 或 Docker 挂载时，这很昂贵。将磁盘写入移出写操作的目的是减少在文档保存时出现的冻结。

**规则**

如果您使用 IntelliJ 平台文件 API 保存和读取文件，很可能不需要更改任何内容。这很好：

• 通过 FileDocumentManager 保存文档
• 之后通过 VirtualFile 读取它
• 使用 VFS API，如 contentsToByteArray、getInputStream 或 VfsUtil

VFS 表现为写操作已经完成。例如，如果在写操作之后启动读操作，通过 VFS 读取时，它应该看到新内容。

如果您的代码即将直接读取物理文件，或传递路径给另一个进程，请先刷新 VFS 缓冲区，使用 ManagingFS：

import com.intellij.openapi.vfs.newvfs.ManagingFS

FileDocumentManager.getInstance().saveAllDocuments()

// 刷新操作不在写操作中；这可能等待磁盘 I/O。

ManagingFS.getInstance().flushPendingUpdates()

commandLine.createProcess()

如果知道确切的文件，使用更窄的版本：

FileDocumentManager.getInstance().saveDocument(document)

// 刷新操作不在写操作中；这可能等待磁盘 I/O。

ManagingFS.getInstance().flushPendingUpdates(virtualFile)

val textOnDisk = Files.readString(virtualFile.toNioPath())

抛出的版本可以等待 I/O，并可能抛出 IOException，因此在磁盘访问即将发生的地方调用它们。不要在每次保存后都添加刷新以确保安全。

对于用户触发的操作，如果在 IDE 通知比在自己的代码中处理异常更合适，使用：

ManagingFS.getInstance().flushPendingUpdatesOrNotify()

例如，一个操作在浏览器中打开生成或保存的文件，可以在浏览器将其传递给浏览器之前刷新：

FileDocumentManager.getInstance().saveAllDocuments()

ManagingFS.getInstance().flushPendingUpdatesOrNotify()

BrowserLauncher.instance.browse(url, browser, project)

如果保存发生在更早的时间，保持相同的想法：在外部读取器接触文件系统之前立即刷新。

**值得检查的地方**

脆弱点是 VFS 写入的文件到直接磁盘读取的传递。这些可以表现为过时的读取、外部工具看到旧内容或测试变得不可靠，因为它们通过 VFS 写入并使用 NIO 进行断言。

平台代码库已经为许多这些过渡进行了调整，但插件可能仍然有自己的一些情况。常见示例：

• 启动格式器、检查器、编译器、测试运行器、VCS 命令或语言服务器
• 通过 Files.readString、Files.newInputStream、Path 或 File 读取
• 将项目目录或文件路径传递给 CLI 工具
• 通过 VFS 写入并使用 NIO 进行断言的测试
• VFS 监听器，它们调度后续磁盘 I/O

对于 VFS 监听器，在磁盘访问实际发生的地方刷新。如果监听器只是排队工作，不要在同步监听器中刷新。这将等待操作重新回到写操作下。

当前平台代码可能从某些VirtualFile.toNioPath()路径中刷新待写入的数据，因为路径转换通常会紧随其后的是 NIO 访问或进程启动。不要在插件代码中将路径转换用作同步点。如果磁盘可见性很重要，请显式调用刷新 API。

**Opt-In 和故障排除**

此功能默认启用，但并非所有getOutputStream()调用都会自动变为异步。传递给VirtualFile.getOutputStream(requestor)的请求者必须选择启用。今天，重要的路径是编辑器保存：FileDocumentManagerImpl选择启用，因此从编辑器保存的文件将通过新分支进行处理。

选择启用的标记本身，AsyncFileContentWriteRequestor，目前是内部的，因此大多数第三方插件不应急于直接采用异步写入。更紧迫的任务是审查saveAllDocuments()和直接磁盘访问的假设。

要检查问题是否与此行为有关，请暂时禁用它：

-Dvfs.async-content-write.enabled=false 当使用 IntelliJ 平台 Gradle 插件运行插件时，通过runIde任务将标志传递给 IDE 进程：

import org.gradle.process.CommandLineArgumentProvider tasks { runIde { jvmArgumentProviders += CommandLineArgumentProvider { listOf("-Dvfs.async-content-write.enabled=false") } } }

**您可能遇到的测试失败**

这种类型的测试可能会变得不可靠：

writeThroughVfs(virtualFile)

assertEquals("expected", Files.readString(virtualFile.toNioPath())) 测试通过一个文件系统视图写入，通过另一个视图读取。使边界明确：

writeThroughVfs(virtualFile)

ManagingFS.getInstance().flushPendingUpdates(virtualFile)

assertEquals("expected", Files.readString(virtualFile.toNioPath())) 如果断言读取 VFS，就不需要刷新。

[](https://blog.jetbrains.com/platform/2026/06/async-vfs-content-writes-what-plugin-authors-need-to-know/#)

1. 为什么存在
2. 规则
3. 值得检查的地方
4. Opt-In 和故障排除
5. 您可能遇到的测试失败

发现更多