《The Concise TypeScript Book》技术速递：TypeScript 原生 API 新增分层虚拟文件系统（Layered VFS）

• 文档
• 教程

本文基于《The Concise TypeScript Book》官网「TypeScript 新闻」栏目收录的官方资讯（西班牙语版见 typescript-native-api-adds-layered-vfs.md，英文原版见 typescript-native-api-adds-layered-vfs.md，发布于 2026 年 9 月 9 日），解读 TypeScript 原生 API 的新能力：用显式的虚拟文件系统（VFS）数据创建和增量更新 snapshot。读完本文，你将理解createFileSystem、createFileSystemWithLib、createFileSystemLayer三个 helper 的职责边界，掌握full与layer两种 VFS 形态的差异与适用场景，并了解当前"单真实 snapshot、操作串行"的 API 限制。

背景：TypeScript 7 原生化与程序化 API 的回归

要理解这次 VFS 变更，需要先回到 TypeScript 7 的路线图。根据本仓库新闻栏目收录的信息（见 typescript-7-released.md），TypeScript 7.0 于 2026 年 7 月 8 日发布，是第一个基于全新 Go 原生代码库的稳定版本，官方基准测试显示完整构建相比 TypeScript 6 快约 7.7～11.9 倍，语言服务也迁移到了 Language Server Protocol（LSP）。但7.0 并未提供稳定的程序化（programmatic）API，嵌入 TypeScript 的工具链（如当时的 Astro、Vue、MDX、Svelte 及部分 Angular 工作流）仍依赖 TypeScript 6。

后续的官方新闻勾勒出了原生 API 逐步补齐的轨迹：

• 2026 年 7 月 24 日，原生代码库加入四种程序化 emit 路径（program.emit、program.emitToString、program.getJavaScriptEmit、program.getDeclarationEmit），其中program.emit明确支持"写入配置的虚拟文件系统"（见 typescript-7-native-api-adds-emit-methods.md）；
• 2026 年 9 月 14 日，原生 API 补充了 typescript-eslint 所需的检查器与类型 API（见 typescript-native-api-adds-typescript-eslint-apis.md）；
• 2026 年 9 月 9 日，也就是本文的主角——原生 API 新增分层虚拟文件系统支持。

同时，官方在 7 月 27 日明确说明tsgo预览名称将退出、原生代码库将回归主 TypeScript 仓库（见 typescript-7-native-tooling-consolidates.md）。因此，本文描述的原生 API 变化属于TypeScript 7.x 原生 API 系列能力建设的一部分，工具链在接入前应核实所用 TypeScript 版本是否已包含对应 API。

核心变更：三个 VFS helper 与Snapshot.update

本次变更的核心内容是：原生 TypeScript API 现在能够用显式的虚拟文件系统数据来构建和更新 snapshot。在此之前，工具要模拟"文件被新增、修改、删除"这类场景，往往需要重建整套文件系统输入；而现在可以通过 VFS 数据直接表达这些差异，无需重建整个文件系统输入。

变更引入了三个新 helper：

配套地，Snapshot.update获得了一项关键能力：在现有 snapshot 之上应用一个新的缓存层（cache layer）。这意味着工具可以基于旧 snapshot 的缓存结果做增量更新，而不是从零重建——这正是"分层"设计的价值所在：把"变化的部分"作为新的一层叠加到既有快照上。

两种 VFS 形态：full与layer

本次 API 明确区分了两种 VFS 形态，它们在数据来源与回退行为上有本质差异：

full：完全驻留内存

• 整个文件系统内容全部保存在内存中；
• 不会回退到 host（宿主）文件系统或 session 文件系统的回调；
• 适合需要完全隔离、确定性强的场景，例如在测试中模拟一套自包含的源码树，或在不同平台间复现一致的解析结果。

layer：分层叠加 + 宿主回退

• 以宿主文件系统为底层，在其上叠加一层虚拟数据；
• 缓存未命中（cache miss）时回退到 host，即 VFS 中找不到的文件会从真实文件系统读取；
• 支持removedPaths参数，用来隐藏宿主上实际存在的文件或目录。这为"模拟删除"提供了低成本途径：无需拷贝或删除真实文件，只需在分层 VFS 中声明这些路径被移除。

两种形态都支持符号链接（symlink），且支持两类目标：VFS 内部的符号链接，以及指向 host 路径的符号链接。这让工具可以灵活地重映射模块路径或模拟 monorepo 内的链接结构。

从设计上可以推断：full更偏向"无副作用、完全可复现"的构建/测试环境，而layer更偏向"以真实项目为基础、叠加少量虚拟修改"的编辑器场景与增量分析。

典型应用场景

结合上述能力，可以推断本特性主要服务以下工具场景（均为基于 API 设计做出的合理推断，仓库官方新闻未逐一列举实例）：

1. 增量文件变更建模：编辑器或语言服务器在用户编辑单个文件后，不再需要重建整个文件系统输入，只需用Snapshot.update叠加一层包含改动文件的 VFS 缓存层；
2. 删除模拟：利用layerVFS 的removedPaths，在不动宿主磁盘的情况下让解析器"看不见"某些文件或目录，适合测试模块不存在时的编译行为；
3. 内存构建：fullVFS 配合原生 emit API（如program.emit支持写入配置的虚拟文件系统，见 typescript-7-native-api-adds-emit-methods.md），可以在不落盘的情况下完成从类型检查到产物生成的完整流程；
4. 符号链接重映射：利用两类符号链接支持，模拟包管理器创建的node_modules链接结构或跨目录引用。

当前限制：单真实 snapshot、操作串行

官方新闻明确指出了该特性现阶段的两条边界：

• VFS 支撑的 snapshot 仍然计为真实 snapshot（real snapshot），因此原生 API 维持"同一时刻只能存在一个真实 snapshot"的既有限制；
• snapshot 操作目前仍为串行（serial），尚不支持并行 snapshot 操作。

换言之，分层 VFS 虽然显著降低了构建与更新的成本，但并未突破原生 API 在 snapshot 数量与并发上的约束。计划基于 snapshot 并行调度来提升吞吐的工具，需要等待原生 API 后续放宽这些限制。

与本仓库的关系与后续跟进

本次新闻属于本仓库「TypeScript 新闻」栏目的一个条目，栏目汇总了 TypeScript 官方的发布与变更速报，供开发者低成本跟进（总览见 typescript-news/index.md，西班牙语索引见 es-es/typescript-news/index.md）。相关条目还包括原生 API 的 emit 方法、typescript-eslint 所需 API 以及 TypeScript 7 工具链整合计划，建议对照阅读以获得完整上下文。

该功能的官方来源是 TypeScript 已合并的 pull request："Add optional VFS parameters to updateSnapshot"（PR #64115）。需要特别说明两点：

• 本次新闻发布于 2026 年 9 月 9 日，且官方新闻明确 7.0 尚无稳定程序化 API、新 API 计划在 TypeScript 7.1 引入，因此接入前务必在目标 TypeScript 版本中实测createFileSystem系列 helper 与Snapshot.update的可用性；
• 原生 API 的同步（synchronous）与异步（asynchronous）表面是否同时覆盖本次 VFS 变更，官方新闻未明确提及（typescript-eslint API 新闻中曾说明该次变更同步/异步表面均已更新），工具链应以实际版本行为为准。

总结

TypeScript 原生 API 的分层虚拟文件系统能力，为工具链提供了"以显式 VFS 数据构建 snapshot、以缓存层增量更新 snapshot"的新范式：fullVFS 提供完全内存化的确定性环境，layerVFS 提供带宿主回退与removedPaths删除掩码的增量视图，两者均支持符号链接；而"单真实 snapshot、操作串行"的现状也提醒集成方合理规划 snapshot 生命周期。对于正在评估 TypeScript 7 原生 API 的工具作者而言，这是一项值得持续跟踪的基础能力。

• 文档
• 教程