VSCode——打开大型项目提示 `OOM (Out of Memory)` 的解决方案

一、问题描述

最近在使用 VS Code + Remote SSH 开发一个大型 Python 项目时，打开工作区后 VS Code 会直接崩溃，并弹出如下错误：

The window terminated unexpectedly (reason: 'oom', code: '-536870904')

如下图所示：

（此处可插入 OOM 报错截图）

一开始怀疑是电脑内存不足，但查看 Windows 任务管理器发现：

• 内存总容量：20 GB
• 已使用：约 14 GB
• 剩余可用：约 5.5 GB

系统本身并没有发生真正的内存耗尽。

---

二、问题分析

经过排查发现：

VS Code 本身没有问题。

打开一个空目录可以正常运行，只有打开某个特定工作区时才发生 OOM。

进一步分析项目目录，发现工程结构如下：

TrackEval
│
├── trackeval/
├── scripts/
├── tests/
├── data/
└── processed_data/

其中：

processed_data/
    inference_results/
        tracking_result_xxx/
            000001.txt
            000002.txt
            ...

包含了大量实验结果文件（.txt）。

这些文件虽然每个都很小，但是数量非常多（可能达到数十万甚至更多）。

---

三、为什么会 OOM？

打开工作区以后，VS Code 并不仅仅是显示文件。

它还会同时启动多个后台任务：

• File Watcher（监听文件变化）
• Search（建立搜索索引）
• Python/Pylance（建立代码索引）
• Explorer（读取目录树）
• Remote SSH 同步状态

对于普通项目，这些功能没有任何问题。

但是当项目中存在几十万甚至上百万个小文件时：

• File Watcher 会监听大量文件；
• Search 会尝试建立索引；
• Pylance 会扫描 Python 工程；
• Explorer 会读取大量目录。

最终导致 VS Code 的 Renderer（Electron）内存不断增长，最后触发：

OOM (Out Of Memory)

---

四、解决方案

4.1 核心思想

代码需要索引，数据不需要索引。

例如：

TrackEval
├── trackeval       ← 代码
├── scripts         ← 代码
├── tests           ← 代码
├── data            ← 数据
└── processed_data  ← 实验结果

其中：

• trackeval
• scripts

需要智能提示。

而：

• data
• processed_data

通常只是程序读取的数据。

因此可以告诉 VS Code：

不要扫描这两个目录。

---

4.2 修改 .vscode/settings.json

在项目目录下创建：

.vscode/settings.json

写入如下配置：

{
    // =========================
    // 文件监视（不监听数据目录）
    // =========================
    "files.watcherExclude": {
        "**/data/**": true,
        "**/processed_data/**": true
    },

    // =========================
    // 全局搜索（不搜索数据目录）
    // =========================
    "search.exclude": {
        "**/data/**": true,
        "**/processed_data/**": true
    },

    // =========================
    // Pylance（不分析数据目录）
    // =========================
    "python.analysis.exclude": [
        "**/data/**",
        "**/processed_data/**"
    ],

    // 只分析打开的文件
    "python.analysis.diagnosticMode": "openFilesOnly",

    // 关闭整个工程索引
    "python.analysis.indexing": false
}

保存后：

重新连接 Remote SSH 或重新打开 VS Code。

---

4.3 各配置项说明

1）. files.watcherExclude

"files.watcherExclude": {
    "**/processed_data/**": true
}

作用：

• 不监听目录中的文件变化；
• 大幅减少 File Watcher 的压力。

适用于：

• 数据集
• 日志
• 推理结果
• 模型权重

---

2）. search.exclude

"search.exclude": {
    "**/processed_data/**": true
}

作用：

按下：

Ctrl + Shift + F

时不会扫描该目录。

搜索速度明显提高。

---

3）. python.analysis.exclude

"python.analysis.exclude": [
    "**/processed_data/**"
]

作用：

告诉 Pylance：

不要分析这些目录。

避免：

• 建立索引
• 类型推断
• 自动补全

---

4）. python.analysis.diagnosticMode

"python.analysis.diagnosticMode": "openFilesOnly"

默认情况下：

Pylance 会分析整个工作区。

改成：

openFilesOnly

以后只分析：

当前打开的 Python 文件。

可以显著降低内存占用。

---

5）. python.analysis.indexing

"python.analysis.indexing": false

关闭整个工程索引。

对于大型 AI 项目，通常不会影响日常开发。

---

五、解决效果

修改配置后：

✅ VS Code 不再出现：

The window terminated unexpectedly
(reason: 'oom')

同时：

• 工作区仍然可以正常打开；
• data
• processed_data

两个目录依然保留在资源管理器中，可以正常浏览。

代码补全、跳转定义等功能也不会受到影响，因为代码目录仍然会正常分析。

---

六、适用场景

本文方法适用于：

• 深度学习项目
• 大模型项目（LLM、VLM）
• 多目标跟踪（MOT）
• 目标检测
• 图像分割
• 视频分析
• 海量实验结果目录
• 海量日志文件
• Remote SSH 开发

特别适合下面这种工程：

project/
│
├── src/
├── scripts/
├── checkpoints/
├── datasets/
├── logs/
├── outputs/
├── results/
└── inference_results/

其中：

• checkpoints
• datasets
• outputs
• results
• logs

都可以考虑加入：

• files.watcherExclude
• search.exclude
• python.analysis.exclude

---

七、总结

对于大型 AI 项目来说，真正需要 VS Code 分析的是代码 ，而不是数据。

如果项目中包含大量数据集、推理结果、日志文件或模型权重，建议将这些目录排除出文件监听、搜索和 Python 索引范围。

这样既能保留完整的项目目录结构，又能有效降低 VS Code 的资源占用，避免因海量文件导致的 OOM (Out of Memory) 崩溃问题，同时提升搜索、索引和工作区加载速度。