排查终端启动失败

首先，对于您正在阅读本文而不是愉快地使用 Visual Studio Code 集成终端，我们深表歉意。VS Code 团队一直努力使终端体验尽可能流畅，但在某些情况下，由于 shell 或终端配置问题，VS Code 编辑器无法规避这些问题。

在与数百名开发者合作诊断他们的终端启动失败问题后，VS Code 团队整理了本文，其中包含过去帮助过用户的建议和排查技巧。我们希望您能在这里找到解决 shell 或终端问题的答案，并能快速恢复工作。

集成终端用户指南

如果您是 VS Code 集成终端的新用户，您可以在集成终端用户指南中了解更多信息。在那里您可以阅读如何配置终端，并查看常见问题的解答。

如果用户指南未能帮助您诊断启动失败问题，请参阅下面的具体排查步骤。这些排查步骤，例如检查设置和启用日志记录，适用于支持 VS Code 的所有平台：macOS、Linux 和 Windows。

注意：如果您使用 Windows 系统，您可能需要先查看Windows 上的常见问题部分。

排查步骤

要排查 Visual Studio Code 集成终端启动失败问题，请按照以下步骤诊断问题

检查您的用户设置。 查看这些可能会影响启动的 terminal.integrated 设置
- terminal.integrated.defaultProfile.{platform} - 终端使用的默认 shell 配置文件。
- terminal.integrated.profiles.{platform} - 定义的 shell 配置文件。设置 shell 路径和参数。
- terminal.integrated.cwd - shell 进程的当前工作目录 (cwd)。
- terminal.integrated.env.{platform} - 添加到 shell 进程的环境变量。
- terminal.integrated.inheritEnv - 新 shell 是否应从 VS Code 继承其环境。
- terminal.integrated.automationProfile.{platform} - 用于任务和调试等自动化相关终端用法的 shell 配置文件。
- terminal.integrated.splitCwd - 控制分屏终端的起始工作目录。
- terminal.integrated.windowsEnableConpty - 是否对 Windows 终端进程通信使用 ConPTY。
您可以在设置编辑器（文件 > 首选项 > 设置）中查看设置，并按设置 ID 搜索特定设置。

快速检查您是否无意中更改了某些设置的方法是，在设置编辑器中使用 @modified 筛选器。

大多数集成终端设置需要直接在您的用户 settings.json JSON 文件中修改。您可以通过设置编辑器中的在 settings.json 中编辑链接，或通过命令面板中的首选项：打开用户设置 (JSON) 命令打开 settings.json（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。
直接测试您的 shell。 尝试在外部终端或命令提示符中，在 VS Code 之外运行您指定的集成终端 shell。某些终端启动失败可能由于您的 shell 安装问题，而非 VS Code 特有的问题。显示的退出代码来自 shell，您可以通过在互联网上搜索特定的 shell 和退出代码来诊断 shell 问题。
使用最新版本的 VS Code。 每个 VS Code 月度版本都有许多更新和修复，可能包含集成终端改进。您可以通过帮助 > 关于（在 macOS 上是 Code > 关于 Visual Studio Code）查看您的 VS Code 版本。要查找最新版本的 VS Code，请访问 VS Code 发布说明。您可能还需要检查是否安装了最新版本的 shell。
使用最新版本的 shell。 如果您的 shell 是独立于平台安装的，请尝试安装最新可用版本的 shell。如果您使用的是较旧的操作系统版本，也适用此建议。例如，某些旧版本的 Windows 10 与 VS Code 终端配合得不太好。
启用跟踪日志记录。 您可以启用跟踪日志记录并在启动终端时捕获日志。日志通常会显示问题所在，因为创建终端进程/pty 所使用的所有参数都会被记录下来。错误的 shell 名称、参数或环境变量可能导致终端无法启动。如果问题尚未解决，请保留此日志以供日后参考。

退出代码

终端启动失败通知中显示的退出代码由 shell 进程返回，而非 VS Code 生成。终端中可以使用许多可用的 shell，并且有数百种可能的退出代码。

尝试在互联网上搜索您的特定 shell 和退出代码（例如，“PowerShell 4294901760”），您可能会找到与您的终端启动失败相关的特定建议或已知问题。
尝试在您的 shell 的问题仓库中搜索。例如，如果您遇到 WSL 问题，您可以在 https://github.com/microsoft/WSL/issues 的开放或已解决问题中搜索您的错误代码，可能会找到解决方法。

Windows 上的常见问题

确保兼容性模式已禁用

升级到 Windows 10 时，某些应用程序可能自动开启了兼容性模式。如果 VS Code 启用了兼容性模式，终端会因其进行的一些底层模拟而损坏。您可以通过右键单击 VS Code 可执行文件，选择属性，然后在兼容性选项卡中取消选中以兼容性模式运行此程序选项来检查和禁用兼容性模式。

在 Windows 10 上终端退出代码为 1（默认 shell 为 WSL）

如果适用于 Linux 的 Windows 子系统 (WSL) 未设置有效的默认 Linux 分发版，则可能发生此错误。

注意：“docker-desktop-data”不是有效的分发版。

打开 PowerShell 并输入 wslconfig.exe /l，确认 WSL 已正确安装并列出系统中当前可用的 Linux 分发版。确认有效的发行版旁边有 (default)。
要更改默认分发版，请输入 wslconfig.exe /setdefault "distributionNameAsShownInList"

发生原生异常

通常，此错误是由于杀毒软件拦截并阻止 winpty/conpty 组件创建终端进程引起的。要解决此错误，您可以将以下文件从杀毒软件扫描中排除

{install_path}\resources\app\node_modules.asar.unpacked\node-pty\build\Release\winpty.dll
{install_path}\resources\app\node_modules.asar.unpacked\node-pty\build\Release\winpty-agent.exe
{install_path}\resources\app\node_modules.asar.unpacked\node-pty\build\Release\conpty.node
{install_path}\resources\app\node_modules.asar.unpacked\node-pty\build\Release\conpty_console_list.node

将此问题报告给杀毒软件团队也有助于彻底解决此问题。

终端退出代码 259

退出代码 259 在终端尝试启动 PowerShell.exe 等新进程时可能表示 STILL_ACTIVE。您可以尝试终止计算机上未使用的程序和进程，以防其中一个进程导致终端 shell 进程保持活动状态而无法重新启动。

您的计算机上运行的杀毒软件也可能干扰终端 shell 的启动。

终端退出代码 3221225786（或类似代码）

当您在 conhost 的属性中启用了旧版控制台模式时，可能会发生此情况。要更改此设置，请从开始菜单打开 cmd.exe，右键单击标题栏，转到属性，然后在选项选项卡下取消选中使用旧版控制台。

Use legacy mode checkbox

后续步骤

集成终端用户指南 - 了解有关通用终端使用和配置的更多信息。

05/08/2025