VS Code 文件嵌套怎样把同名产物收进源文件

项目里同时出现 app.ts、app.js、app.d.ts 和 app.js.map 时，VS Code Explorer 很快会被伴随文件占满。与其用 files.exclude 把它们藏起来，不如开启文件嵌套：让产物仍然可访问，但折叠到对应的源文件下面。

官方地址：https://code.visualstudio.com/docs/editing/getting-started/userinterface

在设置中打开 explorer.fileNesting.enabled，再用 explorer.fileNesting.patterns 写“父文件模式 → 子文件模式”规则，就能把同名产物收进源文件；explorer.fileNesting.expand 决定默认展开还是折叠。

先找到文件嵌套的设置入口

文件嵌套作用于 Explorer 的目录展示，不会移动文件，也不会改变磁盘上的目录结构。先确认当前打开的是目标项目，再决定规则只服务这个工作区，还是所有项目都使用。

1. 在左侧活动栏点击 Explorer，确认项目文件夹已经展开。
2. 按 Cmd/Ctrl+, 打开 Settings，在搜索框输入 file nesting。
3. 找到 Explorer › File Nesting: Enabled 并打开；需要控制初始状态时，再找到 Explorer › File Nesting: Expand。
4. 需要写自定义规则时，点击设置项旁边的打开 JSON 图标，进入当前作用域的 settings.json。

用 patterns 把同名产物收进源文件

自定义规则写在 explorer.fileNesting.patterns 中。左侧是父文件匹配模式，右侧是用逗号分隔的子文件模式；${capture} 会复用左侧 * 捕获到的同名部分。

例如，一个 TypeScript 项目希望把 JavaScript 编译产物、声明文件和 sourcemap 收到对应的 .ts 文件下，可以使用下面这段严格 JSON：

{
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.expand": false,
  "explorer.fileNesting.patterns": {
    "*.ts": "${capture}.js, ${capture}.d.ts, ${capture}.js.map",
    "*.js": "${capture}.js.map",
    "package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml"
  }
}

这段 JSON 不能添加注释，否则设置文件会失效。*.ts 匹配 app.ts，其中 ${capture} 就是 app，所以旁边的 app.js、app.d.ts 和 app.js.map 会成为它的嵌套项。锁文件规则则是把固定的 package.json 作为父文件。

选择工作区范围并确认折叠状态

如果只想让当前仓库采用这套整理方式，在设置界面顶部选择 Workspace 作用域，或把 JSON 写进项目根目录的 .vscode/settings.json。写入 User 作用域会影响其他项目，适合你长期统一维护的文件命名约定。

1. 在设置页面顶部选择 Workspace，确认左侧标记已经切换。
2. 把 Explorer › File Nesting: Enabled 设为开启。
3. 把 Explorer › File Nesting: Expand 设为关闭，让目录首次打开时只显示父文件。
4. 回到 Explorer，展开目标目录；看到文件名右侧出现嵌套数量，点击父文件左侧箭头即可查看子文件。

匹配不到或误收时怎样调整

文件嵌套最常见的问题不是功能没有打开，而是匹配模式和真实文件名没有对上。可以按下面的顺序处理：

• 同名部分没有复用：父模式使用了 * 时，子模式优先写 ${capture}；如果父文件名是固定的，则直接写固定子文件名。
• 只想匹配当前目录名：使用 ${dirname} 代表父文件所在目录名，避免把其他目录里同名文件一起归组。
• 扩展名需要复用：使用 ${extname}，但要先确认它代表的是父文件的扩展名，而不是完整文件名。
• 不想默认展开：确认 explorer.fileNesting.expand 为 false；它只影响初始展示，不会删除嵌套关系。
• 规则像隐藏文件一样消失：检查是否同时配置了 files.exclude 或 search.exclude。文件嵌套是“收起但保留”，排除规则则可能让文件根本不显示。

最后用一个小场景确认配置

可以在测试目录放置 demo.ts、demo.js、demo.d.ts 和 demo.js.map 四个文件。刷新 Explorer 后，预期只看到一个 demo.ts 父项；展开它，三个伴随文件仍能被打开、复制或删除。若只看到一个文件且没有展开箭头，优先检查规则是否写入了当前工作区的 settings.json，以及父模式中的通配符是否与文件名一致。

常见问题

文件嵌套会改变 Git 或构建工具读取文件的方式吗？

不会。它只改变 Explorer 的可视层级，文件仍在原来的目录中，Git、构建工具和命令行看到的路径不变。

应该用文件嵌套还是 files.exclude？

需要偶尔访问产物时用文件嵌套；确定永远不需要在 Explorer 中查看的目录或文件，才考虑 files.exclude。两者可以同时存在，但排除规则可能先让文件不可见。

为什么配置改了但旧目录没有变化？

先折叠并重新展开目录，再确认设置作用域和 JSON 格式。若仍不变化，检查是否有其他工作区设置或配置文件覆盖了当前值。

把文件嵌套当成 Explorer 的“收纳层”即可：它负责降低目录噪声，不负责隐藏事实。用 ${capture} 对齐同名产物，用 Workspace 作用域限制影响，再用展开箭头确认文件仍可访问，通常就能得到清爽且不丢文件的项目视图。