VS Code 终端日志被截断？两项配置彻底解锁完整输出与会话持久化 | 排坑笔记

发表于 分类于 阅读次数： 本文字数： 1.1k 阅读时长 ≈ 1 分钟
在 VS Code 调试时遇到终端日志过长被顶掉，或者重启窗口后历史输出全部丢失？本文深入解析 Scrollback 与 Persistent Session Scrollback 的机制差异与配置实操。

1. 现象与复现

在 VS Code 集成终端中执行长构建（如 Docker build、前端打包）或海量单元测试时，输出容易超出默认行数限制。主要在两个场景下表现为日志丢失：

  1. 运行时截断：终端产生超过 1000 行输出时，超出部分自动从顶部丢弃，滑到最顶部也无法查看最初的环境输出或报错根因。
  2. 重载窗口丢失：执行 Developer: Reload Window 或重启 VS Code 后，终端虽然支持会话恢复，但默认仅保留最近 100 行输出，更早的历史记录被直接丢弃。

2. 核心参数与机制解析

VS Code 的终端缓冲区分为活跃运行态和窗口持久化两个独立阶段：

配置项默认值作用阶段说明
terminal.integrated.scrollback1000运行时终端活跃时在内存中维护的最大滚动行数，超出部分丢弃
terminal.integrated.persistentSessionScrollback100会话恢复窗口重启或重载时，从持久化会话写回终端的最大行数

默认限制较为保守主要是为了控制 Electron 渲染进程的内存开销，并避免窗口启动时回填海量文本导致卡顿。现代开发机内存普遍充足，适度调大即可解决问题。

3. 配置方法

方式一：修改 settings.json（推荐）

打开命令面板（Ctrl + Shift + P / Cmd + Shift + P），选择 Preferences: Open User Settings (JSON)，追加配置：

1
2
3
4
{
  "terminal.integrated.scrollback": 10000,
  "terminal.integrated.persistentSessionScrollback": 3000
}

保存后对新建终端立即生效。

方式二：通过界面修改

  1. Ctrl + , 打开设置；
  2. 搜索 terminal.integrated.scrollback，修改为 10000；
  3. 搜索 terminal.integrated.persistentSessionScrollback，修改为 3000。

4. 注意事项

  1. 数值不宜过大：将 scrollback 设为数十万甚至百万行，在多终端并发输出时会明显拉高渲染进程内存，甚至导致终端滚动掉帧。建议常规设置为 10000 ~ 30000 行。
  2. 超大日志重定向到文件：数万行以上的压测或构建日志，建议通过 Shell 重定向结合 tee 输出到文件，避免完全依赖终端缓冲区：
    1
    npm run build 2>&1 | tee build.log
  3. 工作区级隔离：仅希望特定项目生效时，将配置写在项目根目录的 .vscode/settings.json 中即可。