이 출시되었습니다! 11월의 새로운 기능 및 수정 사항을 읽어보세요.

통합 터미널 시작 오류 해결

먼저 Visual Studio Code의 통합 터미널을 즐겁게 사용하지 못하고 이 문서를 읽고 계신 점에 대해 죄송하다는 말씀을 드리고 싶습니다. VS Code 팀은 터미널 경험을 최대한 원활하게 만들기 위해 노력하고 있지만, 경우에 따라 VS Code 편집기가 해결할 수 없는 셸 또는 터미널 구성 문제가 발생할 수 있습니다.

수백 명의 개발자와 함께 터미널 시작 오류를 진단한 후 VS Code 팀은 과거에 도움이 되었던 조언과 문제 해결 팁을 모아 이 문서를 작성했습니다. 이 문서에서 셸 또는 터미널 문제에 대한 답변을 찾고 신속하게 업무에 복귀할 수 있기를 바랍니다.

통합 터미널 사용자 가이드

VS Code 통합 터미널 사용이 처음이라면 통합 터미널 사용자 가이드에서 더 자세히 알아볼 수 있습니다. 여기에서 터미널을 구성하는 방법과 일반적인 질문에 대한 답변을 확인할 수 있습니다.

사용자 가이드가 시작 오류 진단에 도움이 되지 않았다면 아래의 특정 문제 해결 단계를 따르십시오. 설정을 확인하고 로깅을 활성화하는 등의 문제 해결 단계는 VS Code를 지원하는 모든 플랫폼(macOS, Linux, Windows)에 적용됩니다.

참고: Windows를 사용하는 경우 먼저 Windows에서 일반적인 문제 섹션을 검토하는 것이 좋습니다.

문제 해결 단계

Visual Studio Code에서 통합 터미널 시작 오류를 해결하려면 다음 단계를 따라 문제를 진단하십시오.

  1. 사용자 설정 확인. 시작에 영향을 줄 수 있는 terminal.integrated 설정을 검토하십시오.

    • terminal.integrated.defaultProfile.{platform} - 터미널에서 사용하는 기본 셸 프로필입니다.
    • terminal.integrated.profiles.{platform} - 정의된 셸 프로필입니다. 셸 경로와 인수를 설정합니다.
    • terminal.integrated.cwd - 셸 프로세스의 현재 작업 디렉터리(cwd)입니다.
    • terminal.integrated.env.{platform} - 셸 프로세스에 추가되는 환경 변수입니다.
    • terminal.integrated.inheritEnv - 새 셸이 VS Code에서 환경을 상속하는지 여부입니다.
    • terminal.integrated.automationProfile.{platform} - 작업 및 디버그와 같은 자동화 관련 터미널 사용을 위한 셸 프로필입니다.
    • terminal.integrated.splitCwd - 분할 터미널이 시작되는 현재 작업 디렉터리를 제어합니다.
    • terminal.integrated.windowsEnableConpty - Windows 터미널 프로세스 통신에 ConPTY를 사용할지 여부입니다.

    설정 편집기(파일 > 기본 설정 > 설정)에서 설정을 검토하고 설정 ID로 특정 설정을 검색할 수 있습니다.

    Search for Integrated terminal settings

    의도치 않게 변경한 설정이 있는지 빠르게 확인하려면 설정 편집기에서 @modified 필터를 사용하십시오.

    Filter for modified settings

    대부분의 통합 터미널 설정은 사용자 settings.json JSON 파일에서 직접 수정해야 합니다. 설정 편집기의 **settings.json에서 편집** 링크를 통해 또는 명령 팔레트(workbench.action.showCommands ⇧⌘P (Windows, Linux Ctrl+Shift+P))에서 **기본 설정: 사용자 설정 열기(JSON)** 명령을 사용하여 settings.json을 열 수 있습니다.

    A user's settings.json file

  2. 셸 직접 테스트. VS Code 외부의 외부 터미널 또는 명령 프롬프트에서 지정된 통합 터미널 셸을 실행해 보십시오. 일부 터미널 시작 오류는 셸 설치로 인해 발생할 수 있으며 VS Code에 국한된 문제가 아닐 수 있습니다. 표시되는 종료 코드는 셸에서 제공하는 것이며 인터넷에서 특정 셸 및 종료 코드를 검색하여 셸 문제를 진단할 수 있습니다.

  3. 최신 버전의 VS Code 사용. 각 VS Code 월별 릴리스에는 많은 업데이트 및 수정 사항이 포함되어 있으며 통합 터미널 개선 사항이 포함될 수 있습니다. VS Code 버전은 도움말 > 정보(macOS에서는 Code > Visual Studio Code 정보)를 통해 확인할 수 있습니다. 최신 버전의 VS Code를 찾으려면 VS Code 릴리스 정보를 참조하십시오. 셸의 최신 버전도 설치했는지 확인하는 것이 좋습니다.

  4. 최신 버전의 셸 사용. 셸이 플랫폼과 별도로 설치된 경우 최신 버전의 셸을 설치해 보십시오. 이전 버전의 운영 체제를 사용하는 경우에도 동일한 조언이 적용됩니다. 예를 들어, Windows 10의 이전 버전은 VS Code 터미널과 잘 작동하지 않았습니다.

  5. 추적 로깅 사용. 추적 로깅을 사용하도록 설정하고 터미널을 시작할 때 로그를 캡처할 수 있습니다. 로깅은 터미널 프로세스/pty를 만드는 데 사용된 모든 인수가 기록되므로 종종 문제의 원인을 파악하는 데 도움이 됩니다. 잘못된 셸 이름, 인수 또는 환경 변수로 인해 터미널이 시작되지 않을 수 있습니다. 문제가 해결되지 않으면 이 로그를 나중에 보관하십시오.

추가 문제 해결 단계

이러한 단계로도 문제를 해결하지 못했다면 다음을 시도해 볼 수도 있습니다.

  • Stack Overflow에 질문하십시오. 시작 문제는 종종 환경 설정과 관련이 있으며 VS Code 문제는 아닙니다.
  • 터미널이 확장에서 시작되는 경우, 문제 보고자(도움말 > 문제 보고)를 열고 "확장 프로그램"으로 파일을 설정하여 확장 프로그램에 문제를 보고하십시오.
  • VS Code의 버그라고 생각되면 문제 보고자(도움말 > 문제 보고)를 사용하여 문제를 보고하십시오. 문제 보고자는 관련 정보를 자동으로 채웁니다. 보고서에 포함할 기타 내용은 훌륭한 터미널 문제 만들기를 참조하십시오.
  • Windows 10 1809(빌드 17763) 이하를 사용하는 경우 문제는 레거시 "winpty" 백엔드와 관련이 있습니다. Windows 1903(빌드 18362)으로 업그레이드하면 Microsoft에서 만든 새 "conpty" 백엔드로 이동하며 이 문제가 해결될 수 있습니다.
  • 터미널이 관리자 전용으로 실행되도록 설정되어 있고 VS Code를 관리자로 실행하지 않으면 터미널을 열 수 없습니다. 기본 터미널을 변경하거나 터미널 exe의 속성을 편집하여 관리자 권한으로 실행되지 않도록 할 수 있습니다.

종료 코드

터미널 시작 실패 알림에 표시되는 종료 코드는 셸 프로세스에서 반환되는 것이며 VS Code에서 생성되는 것이 아닙니다. 터미널에서 사용할 수 있는 셸과 수백 가지 가능한 종료 코드가 있습니다.

  • 특정 셸과 종료 코드를 인터넷에서 검색해 보십시오(예: "PowerShell 4294901760"). 그러면 터미널 시작 실패와 관련된 특정 제안이나 알려진 문제를 찾을 수 있습니다.
  • 셸의 문제 저장소를 검색해 보십시오. 예를 들어 WSL에 문제가 있는 경우 https://github.com/microsoft/WSL/issues에 있는 열려 있거나 해결된 문제에서 오류 코드를 검색하여 해결 방법을 찾을 수 있습니다.

Windows에서 일반적인 문제

호환 모드가 비활성화되었는지 확인하십시오.

Windows 10으로 업그레이드할 때 일부 앱에 호환 모드가 자동으로 켜질 수 있습니다. VS Code에 호환 모드가 활성화되어 있으면 터미널이 깨집니다. 이는 에뮬레이션을 활성화하기 위해 저수준 작업을 수행하기 때문입니다. VS Code 실행 파일을 마우스 오른쪽 버튼으로 클릭하고 **속성**을 선택한 다음 **호환성** 탭에서 **이 프로그램을 호환 모드로 실행** 옵션을 선택 취소하여 호환 모드를 확인하고 비활성화할 수 있습니다.

Windows 10(WSL을 기본 셸로 사용)에서 터미널이 코드 1로 종료되었습니다.

이 오류는 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로 종료되었습니다.

종료 코드 **259**는 PowerShell.exe와 같은 새 프로세스를 시작하려고 할 때 STILL_ACTIVE를 의미할 수 있습니다. 현재 터미널 셸 프로세스가 활성 상태여서 다시 시작할 수 없는 경우, 컴퓨터에서 사용되지 않는 프로그램과 프로세스를 종료해 볼 수 있습니다.

컴퓨터에서 실행 중인 바이러스 백신 소프트웨어가 터미널 셸 시작을 방해할 수도 있습니다.

터미널이 코드 3221225786(또는 유사한 코드)으로 종료되었습니다.

conhost 속성에서 레거시 콘솔 모드가 활성화된 경우 발생할 수 있습니다. 이를 변경하려면 시작 메뉴에서 cmd.exe를 열고 제목 표시줄을 마우스 오른쪽 버튼으로 클릭한 다음 **속성**으로 이동한 후 **옵션** 탭에서 **레거시 콘솔 사용**을 선택 취소하십시오.

Use legacy mode checkbox

다음 단계

12/10/2025
English 한국어 中文(简体)
© . This site is unofficial and not affiliated with Microsoft.