终端启动失败故障排除
首先,我们很抱歉您在此阅读此文档,而不是愉快地使用 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) 命令打开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 名称、参数或环境变量都可能导致终端无法启动。如果您的问题尚未解决,请保留此日志以备后用。
其他故障排除步骤
如果这些步骤都未能解决问题,您还可以尝试:
- 在 Stack Overflow 上提问,通常启动问题与环境设置有关,而非 VS Code 本身的问题。
- 如果终端是从扩展程序启动的,请通过打开问题报告器(帮助 > 报告问题)并设置“上报至”=“一个扩展”向该扩展程序报告问题。
- 如果您认为这是 VS Code 的 bug,请使用问题报告器(帮助 > 报告问题)报告问题。问题报告器会自动填写相关信息,有关报告中还应包含的其他内容,请参阅创建出色的终端问题。
- 如果您使用的是 Windows 10 1809(内部版本 17763)或更低版本,该问题与旧版“winpty”后端有关。升级到 Windows 1903(内部版本 18362)将切换到由 Microsoft 构建的新版“conpty”后端,这可能会解决您的问题。
- 如果您的终端设置为仅以管理员身份运行,而您未以管理员身份启动 VS Code,则终端将无法打开。您可以更改默认终端,或编辑终端可执行文件的属性,使其不以管理员身份运行。
退出代码
终端启动失败通知中显示的退出代码来自 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)
如果 Windows Subsystem for Linux (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)时,该进程仍处于活动状态
。您可以尝试终止计算机上未使用的程序和进程,以防其中一个程序或进程使终端 shell 进程保持活动状态而无法重新启动。
您的计算机上运行的防病毒软件也可能会干扰终端 shell 的启动。
终端退出,代码为 3221225786(或类似代码)
当您在 conhost 的属性中启用了旧版控制台模式时,可能会发生这种情况。要更改此设置,请从“开始”菜单打开 cmd.exe,右键单击标题栏,转到属性,然后在选项选项卡下取消选中使用旧版控制台。
后续步骤
- 集成终端用户指南 - 了解更多关于通用终端使用和配置的信息。