排查终端启动故障
首先,我们很抱歉您在这里阅读此文档,而不是愉快地使用 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
- 是否使用 ConPTY 进行 Windows 终端进程通信。
您可以在设置编辑器(文件 > 首选项 > 设置)中查看设置,并通过设置 ID 搜索特定设置。
检查您是否无意中更改了设置的一种快速方法是使用设置编辑器中的
@modified
筛选器。大多数集成终端设置需要直接在您的用户
settings.json
JSON 文件中修改。您可以通过设置编辑器中的在 settings.json 中编辑链接,或通过命令面板中的首选项:打开用户设置 (JSON) 命令(⇧⌘P (Windows, Linux Ctrl+Shift+P))打开settings.json
。 -
直接测试您的 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 名称、参数或环境变量可能导致终端无法启动。如果问题尚未解决,请保留此日志以备后用。
其他排查步骤
如果这些步骤都未能解决问题,您还可以尝试
- 在 Stack Overflow 上提问,启动问题通常与环境设置有关,而不是 VS Code 的问题。
- 如果终端是从扩展启动的,请通过打开问题报告器(帮助 > 报告问题)并设置“文件到”为“一个扩展”向该扩展报告问题。
- 如果您认为这是 VS Code 的 bug,请使用问题报告器(帮助 > 报告问题)报告问题。问题报告器会自动填写相关信息,请参阅创建出色的终端问题以了解报告中还应包含哪些内容。
- 如果您使用的是 Windows 10 1809(内部版本 17763)或更低版本,该问题与旧版“winpty”后端有关。升级到 Windows 1903(内部版本 18362)将切换到由 Microsoft 构建的新“conpty”后端,这可能会解决您的问题。
- 如果您的终端设置为仅以管理员身份运行,而您未以管理员身份启动 VS Code,则终端将无法打开。您可以更改默认终端,或编辑终端 exe 的属性,使其不以管理员身份运行。
退出代码
终端启动失败通知中显示的退出代码由 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(WSL 作为默认 shell)
如果未为适用于 Linux 的 Windows 子系统 (WSL) 设置有效的默认 Linux 分发版,则可能会发生此错误。
注意:'docker-desktop-data' 不是有效的分发版。
- 打开 PowerShell 并输入
wslconfig.exe /l
以确认 WSL 已正确安装,并列出系统中当前可用的 Linux 分发版。确认有效的发行版旁边有(默认)。 - 要更改默认分发版,请输入
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
当终端尝试启动新进程(例如 PowerShell.exe)时,退出代码259可能表示 STILL_ACTIVE
。您可以尝试终止计算机上未使用的程序和进程,以防其中某个程序或进程使终端 shell 进程保持活动状态而无法重新启动。
在您的计算机上运行的防病毒软件也可能干扰终端 shell 的启动。
终端退出代码为 3221225786(或类似代码)
当您在 conhost 的属性中启用了旧版控制台模式时,可能会发生这种情况。要更改此设置,请从开始菜单打开 cmd.exe,右键单击标题栏,转到属性,然后在选项选项卡下,取消选中使用旧版控制台。
后续步骤
- 集成终端用户指南 - 了解有关常规终端使用和配置的更多信息。