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

WSL에서 개발하기

Visual Studio Code WSL 확장은 Windows Subsystem for Linux(WSL)를 VS Code에서 바로 사용할 수 있는 완전한 개발 환경으로 활용할 수 있게 해줍니다. Linux 기반 환경에서 개발하고, Linux 전용 툴체인과 유틸리티를 사용하며, Windows의 편안함에서 Linux 기반 애플리케이션을 실행하고 디버깅할 수 있습니다.

이 확장은 WSL에서 직접 명령과 다른 확장을 실행하므로, 경로 문제, 바이너리 호환성 또는 기타 OS 간의 어려움에 대해 걱정할 필요 없이 WSL 내의 파일이나 마운트된 Windows 파일 시스템(예: /mnt/c)에 있는 파일을 편집할 수 있습니다. 이 확장은 VS Code Server를 WSL에 설치합니다. 이 서버는 WSL의 기존 VS Code 설치와는 독립적입니다.

WSL Architecture

이를 통해 VS Code는 **로컬과 같은 개발 경험**을 제공합니다. 완전한 IntelliSense(완성), 코드 탐색 및 디버깅을 포함하며, **코드가 어디에 있든 상관없이** 작동합니다.

시작하기

참고: 이 주제를 검토한 후에는 소개용 WSL 튜토리얼을 시작할 수 있습니다.

설치

시작하려면 다음이 필요합니다.

  1. 선호하는 Linux 배포판과 함께 Windows Subsystem for Linux를 설치합니다.

    참고: WSL 1에는 특정 유형의 개발에 대한 알려진 제한 사항이 있습니다. 또한, Alpine Linux에 설치된 확장 프로그램은 확장 프로그램 내의 네이티브 소스 코드에 있는 glibc 종속성으로 인해 작동하지 않을 수 있습니다. 자세한 내용은 Remote Development and Linux 문서를 참조하십시오.

  2. Windows 측에 Visual Studio Code를 설치합니다(WSL 안에는 설치하지 마십시오).

    참고: 설치 중에 추가 작업 선택 프롬프트가 표시되면 code 명령을 사용하여 WSL에서 폴더를 쉽게 열 수 있도록 PATH에 추가 옵션을 반드시 선택하십시오.

  3. WSL 확장을 설치합니다. VS Code에서 다른 원격 확장을 사용하려는 경우 Remote Development 확장 팩을 설치하는 것을 고려할 수 있습니다.

원격 폴더 또는 작업 영역 열기

WSL 터미널에서

VS Code에서 Windows Subsystem for Linux 내의 폴더를 여는 것은 명령 프롬프트 또는 PowerShell에서 Windows 폴더를 여는 것과 매우 유사합니다.

  1. WSL 터미널 창을 엽니다 (시작 메뉴 항목을 사용하거나 명령 프롬프트/PowerShell에서 wsl을 입력하여).

  2. VS Code에서 열려는 폴더로 이동합니다 (/mnt/c와 같은 Windows 파일 시스템 마운트를 포함하되 이에 국한되지 않음).

  3. 터미널에 code .를 입력합니다. 처음 이 작업을 수행할 때 VS Code가 WSL에서 실행하는 데 필요한 구성 요소를 가져오는 것을 볼 수 있습니다. 이 과정은 시간이 오래 걸리지 않으며 한 번만 필요합니다.

    참고: 이 명령이 작동하지 않으면 터미널을 다시 시작해야 하거나 설치 시 VS Code를 경로에 추가하지 않았을 수 있습니다.

  4. 잠시 후 새 VS Code 창이 나타나고, VS Code가 WSL에서 폴더를 열고 있다는 알림을 받게 됩니다.

    WSL Starting notification

    VS Code는 WSL에서 자체 구성을 계속하고 진행 상황을 업데이트합니다.

  5. 완료되면 왼쪽 하단에 WSL 표시기가 표시되며, 평소처럼 VS Code를 사용할 수 있습니다!

    WSL Status Bar Item

이것으로 끝입니다! 이 창에서 수행하는 모든 VS Code 작업은 WSL 환경에서 실행됩니다. 편집 및 파일 작업부터 디버깅, 터미널 사용 등 모든 것이 포함됩니다.

VS Code에서

또는 VS Code에서 직접 WSL 창을 열 수 있습니다.

  1. VS Code를 시작합니다.
  2. F1을 누르고 기본 배포판의 경우 WSL: WSL에 연결을 선택하거나 특정 배포판의 경우 WSL: 배포판을 사용하여 WSL에 연결을 선택합니다.
  3. 파일 메뉴를 사용하여 폴더를 엽니다.

이미 폴더가 열려 있는 경우 WSL: WSL에서 폴더 다시 열기 명령을 사용할 수도 있습니다. 사용할 배포판을 묻는 메시지가 표시됩니다.

WSL 창에 있고 현재 입력을 로컬 창에서 열고 싶다면 WSL: Windows에서 다시 열기를 사용합니다.

Windows 명령 프롬프트에서

Windows 프롬프트에서 직접 WSL 창을 열려면 --remote 명령줄 매개변수를 사용합니다.

code --remote wsl+<distro name> <path in WSL>

예: code --remote wsl+Ubuntu /home/jim/projects/c

입력 경로가 파일인지 폴더인지 추측해야 합니다. 파일 확장자가 있으면 파일로 간주됩니다.

폴더를 열도록 강제하려면 경로에 슬래시를 추가하거나 다음을 사용합니다.

code --folder-uri vscode-remote://wsl+Ubuntu/home/ubuntu/folder.with.dot

파일을 열도록 강제하려면 --goto를 추가하거나 다음을 사용합니다.

code --file-uri vscode-remote://wsl+Ubuntu/home/ubuntu/fileWithoutExtension

Git 작업하기

WSL과 Windows에서 동일한 리포지토리를 작업하는 경우 일관된 줄 끝을 설정해야 합니다. 자세한 내용은 팁과 요령을 참조하십시오.

또한 Windows Git 자격 증명 관리자를 사용하도록 WSL을 구성하여 암호를 방지할 수 있습니다. 자세한 내용은 팁과 요령을 참조하십시오.

확장 관리

VS Code는 확장을 두 가지 위치 중 하나에서 실행합니다: 로컬 UI/클라이언트 측 또는 WSL 내에서. 테마 및 스니펫과 같이 VS Code UI에 영향을 미치는 확장은 로컬에 설치되는 반면, 대부분의 확장은 WSL 내부에 상주합니다.

확장 프로그램 보기에서 확장을 설치하면 올바른 위치에 자동으로 설치됩니다. 설치 후에는 범주 그룹을 기준으로 확장이 설치된 위치를 알 수 있습니다. 로컬 - 설치됨 범주와 WSL 범주가 표시됩니다.

Workspace Extension Category

Local Extension Category

참고: 확장 작성자이고 확장이 제대로 작동하지 않거나 잘못된 위치에 설치되는 경우, 자세한 내용은 원격 개발 지원을 참조하십시오.

원격에서 실행해야 하는 로컬 확장은 로컬 - 설치됨 범주에서 흐리게 표시되고 비활성화됩니다. 원격 호스트에 확장을 설치하려면 설치를 선택하십시오.

Disabled Extensions w/Install Button

또한 확장 보기로 이동하여 로컬 - 설치됨 제목 표시줄 오른쪽의 클라우드 버튼을 사용하여 WSL에 로컬 확장 설치: {이름}을 선택하여 모든 로컬 설치 확장을 WSL 내부에 설치할 수 있습니다. 그러면 WSL 인스턴스에 설치할 로컬 설치 확장을 선택할 수 있는 드롭다운이 표시됩니다.

Install all extensions

WSL에서 터미널 열기

VS Code에서 WSL의 터미널을 여는 것은 간단합니다. 폴더가 WSL에서 열리면 VS Code에서 여는 모든 터미널 창(터미널 > 새 터미널)은 로컬이 아닌 WSL에서 자동으로 실행됩니다.

이 동일한 터미널 창에서 code 명령줄을 사용하여 새 파일 또는 폴더를 WSL에서 여는 등 여러 작업을 수행할 수도 있습니다. 사용 가능한 명령줄 옵션을 보려면 code --help를 입력하십시오.

Using the code CLI

WSL에서 디버깅하기

WSL에서 폴더를 열면 로컬에서 애플리케이션을 실행할 때와 동일한 방식으로 VS Code의 디버거를 사용할 수 있습니다. 예를 들어, launch.json에서 시작 구성를 선택하고 디버깅을 시작하면(F5), 애플리케이션이 원격 호스트에서 시작되고 디버거가 연결됩니다.

.vscode/launch.json에서 VS Code의 디버깅 기능을 구성하는 자세한 내용은 디버깅 문서를 참조하십시오.

WSL 관련 설정

VS Code의 로컬 사용자 설정도 WSL에서 폴더를 연 경우에도 재사용됩니다. 이렇게 하면 사용자 경험이 일관되게 유지되지만, 로컬 컴퓨터와 WSL 간에 일부 설정을 다르게 하고 싶을 수 있습니다. 다행히 WSL에 연결한 후에는 명령 팔레트(F1)에서 기본 설정: 원격 설정 열기 명령을 실행하거나 설정 편집기에서 원격 탭을 선택하여 WSL 관련 설정을 지정할 수도 있습니다. WSL에서 폴더를 열 때마다 이러한 설정은 현재 적용된 로컬 설정을 재정의합니다.

고급: 환경 설정 스크립트

VS Code Remote가 WSL에서 시작될 때 쉘 시작 스크립트는 실행되지 않습니다. 이는 쉘에 맞춰진 시작 스크립트의 문제를 피하기 위해 수행되었습니다. 추가 명령을 실행하거나 환경을 수정하려면 설정 스크립트 ~/.vscode-server/server-env-setup (Insiders: ~/.vscode-server-insiders/server-env-setup)에서 수행할 수 있습니다. 이 스크립트가 존재하면 서버가 시작되기 전에 처리됩니다.

스크립트는 유효한 Bourne 쉘 스크립트여야 합니다. 잘못된 스크립트는 서버 시작을 방해할 수 있습니다. 서버 시작을 방해하는 스크립트가 있는 경우 일반 WSL 쉘을 사용하여 설정 스크립트를 삭제하거나 이름을 바꿔야 합니다.

WSL 로그(WSL: 로그 보기)를 확인하여 출력 및 오류를 확인하십시오.

고급: 컨테이너에서 WSL 2 폴더 열기

WSL 2와 Docker Desktop의 WSL 2 백엔드를 사용하는 경우, Dev Containers 확장을 사용하여 WSL 내부에 저장된 소스 코드를 작업할 수 있습니다! 다음 단계를 따르십시오.

  1. 아직 하지 않았다면, Docker Desktop의 WSL 2 지원을 설치 및 설정하십시오.

    팁: 설정 > 리소스 > WSL 통합으로 이동하여 사용할 WSL 배포판에 대해 Docker 통합을 활성화합니다.

  2. 아직 하지 않았다면, WSL 확장과 함께 Dev Containers 확장을 설치합니다.

  3. 다음으로, 소스 코드를 WSL에서 폴더로 엽니다.

  4. 폴더가 WSL에서 열리면 명령 팔레트(F1)에서 Dev Containers: 컨테이너에서 다시 열기를 선택합니다.

  5. 폴더에 .devcontainer/devcontainer.json 파일이 없으면, 필터링 가능한 목록에서 시작점을 선택하거나 기존 Dockerfile 또는 Docker Compose 파일(존재하는 경우)을 선택하라는 메시지가 표시됩니다.

    Select a node dev container definition

  6. VS Code 창(인스턴스)이 다시 시작되고 dev 컨테이너 빌드가 시작됩니다. 진행률 알림이 상태 업데이트를 제공합니다.

    Dev Container Progress Notification

  7. 빌드가 완료되면 VS Code가 자동으로 컨테이너에 연결됩니다. 이제 컨테이너 내부에서 소스 코드를 작업할 수 있습니다.

자세한 내용은 Dev Containers 설명서를 참조하십시오.

알려진 제한 사항

이 섹션에는 WSL의 일반적인 알려진 문제 목록이 포함되어 있습니다. 완전한 문제 목록을 제공하기보다는 WSL에서 발생하는 일반적인 문제 중 일부를 강조하기 위한 것입니다.

WSL 관련 활성 문제 목록은 여기에서 확인할 수 있습니다.

WSL 1에서 열린 작업 영역의 폴더 이름을 바꾸려고 할 때 EACCES: 권한 거부 오류가 발생합니다.

이것은 VSCode의 파일 감시자가 활성화되어 발생하는 WSL 파일 시스템 구현의 알려진 문제입니다 (Microsoft/WSL#3395, Microsoft/WSL#1956). 이 문제는 WSL 2에서만 해결될 것입니다.

이 문제를 방지하려면 remote.WSL.fileWatcher.polling을 true로 설정하십시오. 그러나 폴링 기반 파일 감시는 대규모 작업 영역에 성능 영향을 미칩니다.

대규모 작업 영역의 경우 폴링 간격을 늘리고(remote.WSL.fileWatcher.pollingInterval) 감시되는 폴더를 제어하는 것이 좋습니다. files.watcherExclude.

WSL 2에는 해당 파일 감시 문제가 없으며 새 설정에도 영향을 받지 않습니다.

WSL 1에서의 Golang

문제 기존 문제
Delve 디버거가 WSL에서 작동하지 않음 go-delve/delve#810, Microsoft/vscode-go#926

WSL 1에서의 Node.js

문제 기존 문제
NodeJS 오류: spawn EACCES (이 오류의 다양한 변형) Microsoft/WSL#3886
Webpack HMR이 작동하지 않음 Microsoft/WSL#2709
Firebase가 Node를 통해 WSL에서만 사용할 수 없을 정도로 느림 Microsoft/WSL#2657

Git 제한 사항

SSH를 사용하여 Git 저장소를 복제하고 SSH 키에 암호가 있는 경우, 원격에서 실행할 때 VS Code의 끌어오기 및 동기화 기능이 멈출 수 있습니다. 암호 없는 SSH 키를 사용하거나 HTTPS를 사용하여 복제하거나, 명령줄에서 git push를 실행하여 이 문제를 해결하십시오.

컨테이너 도구 확장 제한 사항

Container Tools 확장은 원격 및 로컬에서 모두 실행될 수 있지만, 이미 로컬에 설치되어 있는 경우 로컬에서 제거하기 전에는 원격 SSH 호스트에 설치할 수 없습니다. 이 문제는 향후 VS Code 릴리스에서 해결될 것입니다.

확장 제한 사항

많은 확장은 수정 없이 WSL에서 작동합니다. 그러나 특정 기능의 경우 변경이 필요할 수 있습니다. 확장 문제가 발생하는 경우, 문제를 보고할 때 확장 작성자에게 언급할 수 있는 일반적인 문제 및 해결책 요약을 여기에서 확인하십시오.

또한, Alpine Linux 기반 배포판을 사용할 때 WSL에 설치된 일부 확장은 확장 내 네이티브 코드의 glibc 종속성으로 인해 작동하지 않을 수 있습니다. 자세한 내용은 Linux 원격 개발 문서를 참조하십시오.

자주 묻는 질문

기본 배포판을 변경하라는 메시지가 표시되는 이유는 무엇입니까?

WSL: WSL에 연결을 사용하고 Windows 10, 2019년 5월 업데이트(버전 1903) 이전의 WSL에서 실행하는 경우, WSL 명령이 기본 배포판에서만 작동하고 아직 -d 옵션을 지원하지 않기 때문에 기본 배포판을 전환하라는 메시지가 표시됩니다.

wslconfig.exe를 사용하여 항상 기본 배포판을 수동으로 전환할 수 있습니다.

예를 들어,

wslconfig /setdefault Ubuntu

설치된 배포판을 확인하려면 다음을 사용하십시오.

wslconfig /l

라이브러리 또는 종속성 누락에 대한 오류가 표시됩니다.

일부 확장은 특정 WSL Linux 배포판의 표준 설치에 없는 라이브러리에 의존합니다. 해당 패키지 관리자를 사용하여 Linux 배포판에 추가 라이브러리를 추가할 수 있습니다. Ubuntu 및 Debian 기반 배포판의 경우 sudo apt-get install <package>를 실행하여 필요한 라이브러리를 설치합니다. 자세한 설치 내용은 확장 또는 언급된 런타임의 설명서를 참조하십시오.

WSL 확장 프로그램의 연결 요구 사항은 무엇입니까?

WSL 확장 프로그램과 VS Code Server는 아웃바운드 HTTPS(포트 443) 연결이 필요합니다.

  • update.code.visualstudio.com
  • vscode.download.prss.microsoft.com
  • marketplace.visualstudio.com
  • *.gallerycdn.vsassets.io (Azure CDN)

일부 확장 프로그램(예: C#)은 download.microsoft.com 또는 download.visualstudio.microsoft.com에서 보조 종속성을 다운로드합니다. 다른 확장 프로그램(예: Visual Studio Live Share)은 추가 연결 요구 사항이 있을 수 있습니다. 문제가 발생하는 경우 확장 프로그램의 설명서를 참조하십시오.

이 외의 모든 서버와 VS Code 클라이언트 간의 통신은 임의의 로컬 TCP 포트를 통해 이루어집니다. VS Code 자체에서 액세스해야 하는 위치 목록은 네트워크 연결 기사에서 찾을 수 있습니다.

프록시 뒤에 있으며 연결 문제가 있습니다.

Windows 또는 WSL 측에 프록시 설정이 누락되었을 수 있습니다.

VSCode 외부에서 원격 창이 열리면 WSL 확장은 Windows 측에서 VSCode 서버를 다운로드하려고 시도합니다. 따라서 Windows 측 프록시 구성을 사용합니다.

  • OS 설정에서 상속됨
  • Visual Studio Code의 네트워크 연결에 설명된 대로

원격 VSCode가 WSL 터미널에서 시작될 때 다운로드는 WSL 배포판의 wget을 사용하여 수행됩니다. 프록시 설정은 다음에서 구성할 수 있습니다.

서버가 실행되고 나면 원격 탭의 프록시 설정이 사용됩니다.

확장을 로컬/원격으로 실행하도록 강제할 수 있습니까?

확장은 일반적으로 로컬 또는 원격으로 실행되도록 설계 및 테스트되며 둘 다 실행되지는 않습니다. 그러나 확장이 지원하는 경우 settings.json 파일에서 특정 위치에서 실행되도록 강제할 수 있습니다.

예를 들어, 아래 설정은 Container Tools 확장을 로컬로 실행하고 Remote - SSH: Editing Configuration Files 확장을 기본값 대신 원격으로 실행하도록 강제합니다.

"remote.extensionKind": {
    "ms-azuretools.vscode-containers": [ "ui" ],
    "ms-vscode-remote.remote-ssh-edit": [ "workspace" ]
}

"workspace" 대신 "ui" 값을 사용하면 확장이 로컬 UI/클라이언트 측에서 실행되도록 강제할 수 있습니다. 일반적으로 확장 프로그램 설명서에 별도로 명시되지 않는 한 테스트 목적으로만 사용해야 합니다. **확장 프로그램이 손상될 수 있습니다**. 자세한 내용은 원격 개발 지원 문서를 참조하십시오.

확장 개발자로서 무엇을 해야 하나요?

VS Code 확장 API는 로컬/원격 세부 정보를 추상화하므로 대부분의 확장은 수정 없이 작동합니다. 그러나 확장은 모든 노드 모듈 또는 런타임을 사용할 수 있으므로 조정이 필요한 상황이 발생할 수 있습니다. 확장을 테스트하여 업데이트가 필요한지 확인하는 것이 좋습니다. 자세한 내용은 원격 개발 지원을 참조하십시오.

질문 또는 피드백

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