终端启动失败故障排除
首先,对于您来到这里阅读本文档,而不是愉快地使用 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 的错误,请使用问题报告器(帮助 > 报告问题)报告问题。问题报告器会自动填写相关信息,请参阅 创建优秀的终端问题报告,了解报告中还应包含哪些内容。
- 如果您使用的是 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)
如果 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
当终端尝试启动新进程(例如 PowerShell.exe)时,退出代码 259 可能意味着 STILL_ACTIVE
。您可以尝试杀死机器上未使用的程序和进程,以防其中一个程序或进程使终端 shell 进程保持活动状态并且无法重新启动。
您机器上运行的防病毒软件也可能会干扰终端 shell 的启动。
终端退出,代码为 3221225786(或类似代码)
当您在 conhost 的属性中启用旧版控制台模式时,可能会发生这种情况。要更改此设置,请从开始菜单打开 cmd.exe,右键单击标题栏,转到属性,然后在选项选项卡下,取消选中使用旧版控制台。
后续步骤
- 集成终端用户指南 - 了解有关通用终端使用和配置的更多信息。