원격 개발 팁 및 트릭

이 문서는 Visual Studio Code의 각 원격 개발 확장 프로그램에 대한 문제 해결 팁과 트릭을 다룹니다. 각 특정 확장 프로그램 설정 및 작업에 대한 자세한 내용은 SSH, Containers 및 WSL 문서를 참조하세요. 또는 시작하기 빠른 튜토리얼을 통해 원격 환경에서 빠르게 작업할 수 있습니다.

GitHub Codespaces에 대한 팁과 질문은 GitHub Codespaces 설명서를 참조하세요.

SSH 팁

SSH는 강력하고 유연하지만 설정 복잡성이 추가됩니다. 이 섹션에서는 다양한 환경에서 Remote - SSH 확장 프로그램을 설정하고 실행하기 위한 몇 가지 팁과 트릭을 포함합니다.

AI 채팅 응답 사용자 지정

사용자 지정 지침을 사용하면 일반적인 가이드라인이나 규칙을 설명하여 특정 코딩 관행 및 기술 스택과 일치하는 응답을 얻을 수 있습니다.

사용자 지정 지침을 사용하여 Copilot에 연결된 원격 환경 유형(설치된 언어 또는 도구 체인 등)에 대한 추가 정보를 제공할 수 있습니다. 로컬에서와 마찬가지로 copilot-instructions.md 파일을 사용할 수 있습니다. 또한 dev 컨테이너를 사용할 때 추가 지침 구성 단계를 수행할 수 있습니다.

$EDITOR 변수 구성

macOS / Linux 원격 호스트의 경우, 셸 구성 파일(예: .bashrc 또는 .zshrc)에 이 스니펫을 추가하세요.

if [ "$VSCODE_INJECTION" = "1" ]; then
    export EDITOR="code --wait" # or 'code-insiders' if you're using VS Code Insiders
fi

Windows 호스트의 경우, 이에 해당하는 PowerShell입니다.

if ($env:VSCODE_INJECTION -eq "1") {
    $env:EDITOR = "code --wait"  # or 'code-insiders' for VS Code Insiders
}

이제 git commit과 같이 $EDITOR 변수를 사용하는 터미널 명령을 실행하면 기본 터미널 기반 편집기(예: vim 또는 nano) 대신 VS Code에서 파일이 열립니다.

키 기반 인증 구성

SSH 공개 키 인증은 로컬 "개인" 키와 SSH 호스트의 사용자 계정에 연결된 "공개" 키를 결합하는 편리하고 높은 보안 인증 방법입니다. 이 섹션에서는 이러한 키를 생성하고 호스트에 추가하는 방법을 안내합니다.

팁: Windows용 PuTTY는 지원되는 클라이언트가 아니지만 PuTTYGen 키를 변환할 수 있습니다.

빠른 시작: SSH 키 사용

원격 호스트에 대해 SSH 키 기반 인증을 설정하려면 먼저 키 쌍을 생성한 다음 공개 키를 호스트로 복사합니다.

로컬 SSH 키 쌍 생성

로컬 머신에 SSH 키가 이미 있는지 확인합니다. 일반적으로 macOS / Linux에서는 ~/.ssh/id_ed25519.pub에, Windows에서는 사용자 프로필 폴더의 .ssh 디렉토리(예: C:\Users\your-user\.ssh\id_ed25519.pub)에 있습니다.

키가 없으면 로컬 터미널 / PowerShell에서 다음 명령을 실행하여 SSH 키 쌍을 생성합니다.

ssh-keygen -t ed25519 -b 4096

팁: ssh-keygen이 없으신가요? 지원되는 SSH 클라이언트를 설치하세요.

개인 키 파일의 권한 제한

• macOS / Linux의 경우, 개인 키 경로를 필요에 따라 변경하여 다음 셸 명령을 실행합니다.

  chmod 400 ~/.ssh/id_ed25519
  

• Windows의 경우, PowerShell에서 다음 명령을 실행하여 사용자 이름에 대한 명시적 읽기 액세스 권한을 부여합니다.

  icacls "privateKeyPath" /grant <username>:R
  

  그런 다음 Windows 탐색기에서 개인 키 파일로 이동하여 마우스 오른쪽 버튼을 클릭하고 속성을 선택합니다. 보안 탭 > 고급 > 상속 사용 안 함 > 이 개체의 모든 상속된 권한 제거를 선택합니다.

macOS 또는 Linux 머신이 연결되도록 승인

로컬 터미널 창에서 다음 명령 중 하나를 실행하고 사용자 및 호스트 이름을 적절하게 변경하여 로컬 공개 키를 SSH 호스트로 복사합니다.

• macOS 또는 Linux SSH 호스트에 연결

  export USER_AT_HOST="your-user-name-on-host@hostname"
  export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
  
  ssh-copy-id -i "$PUBKEYPATH" "$USER_AT_HOST"
  

• Windows SSH 호스트에 연결

  • 호스트가 OpenSSH 서버를 사용하고 사용자가 관리자 그룹에 속해 있는 경우

    export USER_AT_HOST="your-user-name-on-host@hostname"
    export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
    
    ssh $USER_AT_HOST "powershell Add-Content -Force -Path \"\$Env:PROGRAMDATA\\ssh\\administrators_authorized_keys\" -Value '$(tr -d '\n\r' < "$PUBKEYPATH")'"
    

  • 그렇지 않은 경우

    export USER_AT_HOST="your-user-name-on-host@hostname"
    export PUBKEYPATH="$HOME/.ssh/id_ed25519.pub"
    
    ssh $USER_AT_HOST "powershell New-Item -Force -ItemType Directory -Path \"\$HOME\\.ssh\"; Add-Content -Force -Path \"\$HOME\\.ssh\\authorized_keys\" -Value '$(tr -d '\n\r' < "$PUBKEYPATH")'"
    

    SSH 호스트의 원격 사용자에 대한 .ssh 폴더에 있는 authorized_keys 파일이 본인에게 속해 있고 다른 사용자에게 접근 권한이 없는지 확인하는 것이 좋습니다. 자세한 내용은 OpenSSH 위키를 참조하세요.

Windows 머신이 연결되도록 승인

로컬 PowerShell 창에서 다음 명령 중 하나를 실행하고 사용자 및 호스트 이름을 적절하게 변경하여 로컬 공개 키를 SSH 호스트로 복사합니다.

• macOS 또는 Linux SSH 호스트에 연결

  $USER_AT_HOST="your-user-name-on-host@hostname"
  $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
  
  $pubKey=(Get-Content "$PUBKEYPATH" | Out-String); ssh "$USER_AT_HOST" "mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo '${pubKey}' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
  

• Windows SSH 호스트에 연결

  • 호스트가 OpenSSH 서버를 사용하고 사용자가 관리자 그룹에 속해 있는 경우

    $USER_AT_HOST="your-user-name-on-host@hostname"
    $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
    
    Get-Content "$PUBKEYPATH" | Out-String | ssh $USER_AT_HOST "powershell `"Add-Content -Force -Path `"`$Env:PROGRAMDATA\ssh\administrators_authorized_keys`" `""
    

  • 그렇지 않은 경우

    $USER_AT_HOST="your-user-name-on-host@hostname"
    $PUBKEYPATH="$HOME\.ssh\id_ed25519.pub"
    
    Get-Content "$PUBKEYPATH" | Out-String | ssh $USER_AT_HOST "powershell `"New-Item -Force -ItemType Directory -Path `"`$HOME\.ssh`"; Add-Content -Force -Path `"`$HOME\.ssh\authorized_keys`" `""
    

    SSH 호스트의 원격 사용자에 대한 .ssh 폴더에 있는 authorized_keys 파일이 본인에게 속해 있고 다른 사용자에게 접근 권한이 없는지 확인합니다. 자세한 내용은 OpenSSH 위키를 참조하세요.

전용 키로 보안 강화

모든 SSH 호스트에 대해 단일 SSH 키를 사용하는 것이 편리할 수 있지만, 누군가 개인 키에 액세스하면 모든 호스트에 액세스할 수 있습니다. 개발 호스트에 대해 별도의 SSH 키를 생성하여 이를 방지할 수 있습니다. 다음 단계를 따르세요.

1. 별도의 SSH 키를 다른 파일에 생성합니다.

   macOS / Linux: 로컬 터미널에서 다음 명령을 실행합니다.

   ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519-remote-ssh
   

   Windows: 로컬 PowerShell에서 다음 명령을 실행합니다.

   ssh-keygen -t ed25519 -f "$HOME\.ssh\id_ed25519-remote-ssh"
   

2. PUBKEYPATH를 id_ed25519-remote-ssh.pub 파일로 설정하여 빠른 시작의 동일한 단계를 따르고 키를 SSH 호스트에 승인합니다.

3. VS Code에서 명령 팔레트(F1)에서 Remote-SSH: Open Configuration File...을 실행하고 SSH 구성 파일을 선택한 후 다음과 같이 호스트 항목을 추가(또는 수정)합니다.

   Host name-of-ssh-host-here
       User your-user-name-on-host
       HostName host-fqdn-or-ip-goes-here
       IdentityFile ~/.ssh/id_ed25519-remote-ssh
   

   팁: Windows 경로에도 /를 사용할 수 있습니다. \를 사용하는 경우 두 개의 슬래시를 사용해야 합니다. 예를 들어, C:\\path\\to\\my\\id_ed25519입니다.

PuTTYGen에서 생성된 키 재사용

호스트에 연결하기 위해 PuTTYGen을 사용하여 SSH 공개 키 인증을 설정한 경우, 다른 SSH 클라이언트에서 사용할 수 있도록 개인 키를 변환해야 합니다. 이를 위해

1. 로컬에서 PuTTYGen을 열고 변환하려는 개인 키를 로드합니다.

2. 애플리케이션 메뉴에서 Conversions > Export OpenSSH key를 선택합니다. 변환된 키를 사용자 프로필 폴더의 .ssh 디렉터리 아래의 로컬 위치에 저장합니다(예: C:\Users\youruser\.ssh).

3. 이 새 로컬 파일이 본인에게 속해 있고 다른 사용자가 액세스할 수 있는 권한이 없는지 확인합니다.

4. VS Code에서 명령 팔레트(F1)에서 Remote-SSH: Open Configuration File...을 실행하고 변경하려는 SSH 구성 파일을 선택한 후 구성 파일에 다음과 같이 호스트 항목을 추가(또는 수정)하여 해당 파일을 가리킵니다.

   Host name-of-ssh-host-here
       User your-user-name-on-host
       HostName host-fqdn-or-ip-goes-here
       IdentityFile ~/.ssh/exported-keyfile-from-putty
   

다중 사용자 서버의 보안 강화

Remote - SSH 확장 프로그램은 "VS Code Server"를 설치하고 유지 관리합니다. 이 서버는 무작위로 생성된 키로 시작되며, 서버에 대한 모든 새 연결은 키를 제공해야 합니다. 이 키는 원격 디스크에 저장되며 현재 사용자만 읽을 수 있습니다. 인증 없이 사용할 수 있는 HTTP 경로는 /version 하나입니다.

기본적으로 서버는 무작위 TCP 포트에서 localhost를 수신하고 해당 포트는 로컬 머신으로 전달됩니다. Linux 또는 macOS 호스트에 연결하는 경우 특정 사용자에게 잠긴 Unix 소켓을 사용하도록 전환할 수 있습니다. 이 소켓은 포트 대신 전달됩니다.

참고: 이 설정은 연결 다중화를 비활성화하므로 공개 키 인증 구성을 권장합니다.

구성하려면

1. Windows, macOS 또는 Linux에 로컬 OpenSSH 6.7+ SSH 클라이언트와 OpenSSH 6.7+ Linux 또는 macOS 호스트(Windows는 이 모드를 지원하지 않음)가 있는지 확인합니다.

2. 로컬 VS Code 사용자 설정에서 Remote.SSH: Remote Server Listen On Socket을 활성화하여 Remote - SSH를 소켓 모드로 전환합니다.

   

3. SSH 호스트에 이미 연결한 경우, 설정을 적용하기 위해 명령 팔레트(F1)에서 Remote-SSH: Kill VS Code Server on Host...를 선택합니다.

연결 시 오류가 발생하는 경우, SSH 호스트의 sshd 구성에서 소켓 전달을 활성화해야 할 수 있습니다. 이를 위해

1. SSH 호스트(로컬 아님)에서 텍스트 편집기(vi, nano, pico 등)로 /etc/ssh/sshd_config를 엽니다.
2. AllowStreamLocalForwarding yes 설정을 추가합니다.
3. SSH 서버를 다시 시작합니다. (Ubuntu의 경우, sudo systemctl restart sshd를 실행합니다.)
4. 다시 시도합니다.

연결 지연 또는 실패 문제 해결

VS Code가 연결을 시도하는 동안 멈추는 문제(잠재적으로 시간 초과)가 발생하는 경우 문제를 해결하기 위해 몇 가지 작업을 시도할 수 있습니다.

일반 문제 해결: 서버 제거

다양한 Remote-SSH 문제를 해결하는 데 유용한 명령은 Remote-SSH: Kill VS Code Server on Host입니다. 이 명령은 서버를 제거하며, "Could not establish connection to server_name: The VS Code Server failed to start."와 같은 다양한 문제 및 오류 메시지를 해결할 수 있습니다.

VS Code가 프롬프트를 기다리고 있는지 확인

VS Code에서 remote.SSH.showLoginTerminal 설정을 활성화하고 다시 시도합니다. 암호 또는 토큰을 입력하라는 메시지가 표시되면 대체 SSH 인증 방법 활성화 섹션에서 프롬프트 빈도를 줄이는 방법에 대한 자세한 내용을 참조하세요.

문제가 계속되면 settings.json에서 다음 속성을 설정하고 다시 시도하세요.

"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false

일부 버전의 Windows OpenSSH 서버 버그 해결

Windows용 OpenSSH 서버의 특정 버전 버그로 인해 호스트가 Windows인지 확인하는 기본 검사가 제대로 작동하지 않을 수 있습니다. 이는 Windows에 포함된 OpenSSH 서버(1909 이하)에서는 발생하지 않습니다.

다행히 settings.json에 다음을 추가하여 SSH 호스트가 Windows를 실행하고 있는지 VS Code에 명시적으로 알림으로써 이 문제를 해결할 수 있습니다.

"remote.SSH.useLocalServer": false

다음 속성을 사용하여 특정 호스트를 Windows로 식별하도록 VS Code를 강제할 수도 있습니다.

"remote.SSH.remotePlatform": {
    "host-in-ssh-config-or-fqdn": "windows"
}

수정이 병합되어 8.1.0.0보다 높은 버전의 서버에서는 이 문제가 해결될 것입니다.

원격 호스트에서 TCP 전달 활성화

Remote - SSH 확장 프로그램은 SSH 터널을 사용하여 호스트와 통신합니다. 경우에 따라 SSH 서버에서 이 기능이 비활성화될 수 있습니다. 이것이 문제인지 확인하려면 출력 창의 Remote - SSH 범주를 열고 다음 메시지를 확인하세요.

open failed: administratively prohibited: open failed

메시지가 표시되면 다음 단계를 따라 SSH 서버의 sshd 구성을 업데이트하세요.

1. SSH 호스트(로컬 아님)에서 텍스트 편집기(Vim, nano, Pico 또는 메모장 등)로 /etc/ssh/sshd_config 또는 C:\ProgramData\ssh\sshd_config를 엽니다.
2. AllowTcpForwarding yes 설정을 추가합니다.
3. SSH 서버를 다시 시작합니다. (Ubuntu의 경우, sudo systemctl restart sshd를 실행합니다. Windows의 경우, 관리자 PowerShell에서 Restart-Service sshd를 실행합니다.)
4. 다시 시도합니다.

SSH 구성 파일에서 ProxyCommand 매개변수 설정

프록시 뒤에 있고 SSH 호스트에 연결할 수 없는 경우, 로컬 SSH 구성 파일의 호스트에 대한 ProxyCommand 매개변수를 사용해야 할 수 있습니다. 사용 예는 이 SSH ProxyCommand 문서를 참조할 수 있습니다.

원격 머신에 인터넷 액세스 권한이 있는지 확인

원격 머신은 Marketplace에서 VS Code Server 및 확장 프로그램을 다운로드하려면 인터넷 액세스 권한이 있어야 합니다. 연결 요구 사항에 대한 자세한 내용은 FAQ를 참조하세요.

원격 호스트에서 HTTP_PROXY / HTTPS_PROXY 설정

원격 호스트가 프록시 뒤에 있는 경우, SSH 호스트에서 HTTP_PROXY 또는 HTTPS_PROXY 환경 변수를 설정해야 할 수 있습니다. ~/.bashrc 파일을 열고 다음을 추가합니다(적절한 호스트 이름/IP 및 포트로 proxy.fqdn.or.ip:3128을 대체).

export HTTP_PROXY=http://proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

# Or if an authenticated proxy
export HTTP_PROXY=http://username:password@proxy.fqdn.or.ip:3128
export HTTPS_PROXY=$HTTP_PROXY

/tmp가 noexec으로 마운트된 경우 해결

일부 원격 서버는 /tmp에서 스크립트 실행을 허용하지 않도록 설정되어 있습니다. VS Code는 시스템 임시 디렉터리에 설치 스크립트를 작성하고 거기서 실행하려고 시도합니다. 이 문제를 해결할 수 있는지 여부를 결정하기 위해 시스템 관리자와 상의할 수 있습니다.

설치 중에 다른 셸이 시작되는지 확인

일부 사용자는 다른 셸을 사용하기 위해 SSH 호스트의 .bash_profile 또는 다른 시작 스크립트에서 다른 셸을 시작합니다. 이는 VS Code의 원격 서버 설치 스크립트를 손상시킬 수 있으며 권장되지 않습니다. 대신, chsh를 사용하여 원격 머신에서 기본 셸을 변경하세요.

연결당 동적으로 머신을 할당하는 시스템에 연결

일부 시스템은 SSH 연결이 만들어질 때마다 클러스터의 한 노드로 SSH 연결을 동적으로 라우팅합니다. VS Code는 원격 창을 열기 위해 두 번 연결하므로(첫 번째는 VS Code Server를 설치/시작하거나 이미 실행 중인 인스턴스를 찾기 위함이고, 두 번째는 VS Code가 서버와 통신하는 데 사용하는 SSH 포트 터널을 생성하기 위함) 이로 인해 문제가 발생합니다. 두 번째 연결을 만들 때 VS Code가 다른 머신으로 라우팅되면 VS Code 서버와 통신할 수 없습니다.

이 문제를 해결하기 위한 한 가지 방법은 OpenSSH(macOS/Linux 클라이언트만 해당)의 ControlMaster 옵션을 사용하는 것입니다. 이 옵션은 대체 SSH 인증 방법 활성화 섹션에서 설명하며, VS Code의 두 연결이 동일한 노드에 대한 단일 SSH 연결을 통해 다중화되도록 합니다.

시스템 관리자에게 구성 지원 문의

SSH는 매우 유연한 프로토콜이며 다양한 구성을 지원합니다. 로그인 터미널 또는 Remote-SSH 출력 창에서 다른 오류가 발생하는 경우 누락된 설정 때문일 수 있습니다.

SSH 호스트 및 클라이언트에 필요한 설정에 대한 정보는 시스템 관리자에게 문의하세요. SSH 호스트에 연결하기 위한 특정 명령줄 인수는 SSH 구성 파일에 추가할 수 있습니다.

구성 파일에 액세스하려면 명령 팔레트(F1)에서 Remote-SSH: Open Configuration File...을 실행합니다. 그런 다음 관리자와 협력하여 필요한 설정을 추가할 수 있습니다.

대체 SSH 인증 방법 활성화

SSH 원격 호스트에 연결하고 다음 중 하나를 수행하는 경우:

• 2단계 인증으로 연결
• 암호 인증 사용
• SSH 에이전트가 실행 중이거나 액세스할 수 없을 때 암호가 있는 SSH 키 사용

그러면 VS Code는 필요한 정보를 입력하라는 메시지를 자동으로 표시해야 합니다. 메시지가 표시되지 않으면 VS Code에서 remote.SSH.showLoginTerminal 설정을 활성화하세요. 이 설정은 VS Code가 SSH 명령을 실행할 때마다 터미널을 표시합니다. 그러면 터미널이 나타날 때 인증 코드, 암호 또는 암호를 입력할 수 있습니다.

문제가 계속되면 settings.json에 다음 속성을 추가하고 다시 시도해야 할 수 있습니다.

"remote.SSH.showLoginTerminal": true,
"remote.SSH.useLocalServer": false

macOS 및 Linux를 사용하고 암호 또는 토큰 입력 빈도를 줄이고 싶다면 로컬 머신에서 ControlMaster 기능을 활성화하여 OpenSSH가 단일 연결을 통해 여러 SSH 세션을 실행하도록 할 수 있습니다.

ControlMaster 활성화

1. SSH 구성 파일에 다음과 같은 항목을 추가합니다.

   Host *
       ControlMaster auto
       ControlPath  ~/.ssh/sockets/%r@%h-%p
       ControlPersist  600
   

2. 그런 다음 mkdir -p ~/.ssh/sockets를 실행하여 소켓 폴더를 만듭니다.

SSH 에이전트 설정

암호가 있는 키를 사용하여 SSH 호스트에 연결하는 경우, 로컬에서 SSH 에이전트가 실행 중인지 확인해야 합니다. VS Code는 자동으로 키를 에이전트에 추가하여 원격 VS Code 창을 열 때마다 암호를 입력할 필요가 없습니다.

에이전트가 실행 중이고 VS Code 환경에서 액세스 가능한지 확인하려면 로컬 VS Code 창의 터미널에서 ssh-add -l을 실행합니다. 에이전트의 키 목록(또는 키가 없다는 메시지)이 표시되어야 합니다. 에이전트가 실행 중이 아니면 다음 지침에 따라 시작하세요. 에이전트를 시작한 후 VS Code를 다시 시작해야 합니다.

Windows

Windows에서 SSH 에이전트를 자동으로 활성화하려면 로컬 관리자 PowerShell을 시작하고 다음 명령을 실행합니다.

# Make sure you're running as an Administrator
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent

이제 로그인 시 에이전트가 자동으로 시작됩니다.

Linux

SSH 에이전트를 백그라운드에서 시작하려면 다음을 실행합니다.

eval "$(ssh-agent -s)"

로그인 시 SSH 에이전트를 자동으로 시작하려면 ~/.bash_profile에 다음 줄을 추가합니다.

if [ -z "$SSH_AUTH_SOCK" ]; then
   # Check for a currently running instance of the agent
   RUNNING_AGENT="`ps -ax | grep 'ssh-agent -s' | grep -v grep | wc -l | tr -d '[:space:]'`"
   if [ "$RUNNING_AGENT" = "0" ]; then
        # Launch a new instance of the agent
        ssh-agent -s &> .ssh/ssh-agent
   fi
   eval `cat .ssh/ssh-agent`
fi

macOS

macOS에서는 기본적으로 에이전트가 실행됩니다.

로컬 SSH 에이전트를 원격에서 사용 가능하게 하기

로컬 머신의 SSH 에이전트를 사용하면 Remote - SSH 확장 프로그램이 암호를 반복해서 묻지 않고도 선택한 원격 시스템에 연결할 수 있지만, 원격에서 실행되는 Git과 같은 도구는 로컬에서 잠금 해제된 개인 키에 액세스할 수 없습니다.

원격에서 통합 터미널을 열고 ssh-add -l을 실행하여 이를 확인할 수 있습니다. 명령은 잠금 해제된 키를 나열해야 하지만, 대신 인증 에이전트에 연결할 수 없다는 오류를 보고합니다. ForwardAgent yes를 설정하면 로컬 SSH 에이전트를 원격 환경에서 사용할 수 있게 되어 이 문제가 해결됩니다.

.ssh/config 파일(또는 Remote.SSH.configFile이 설정된 다른 파일 - Remote-SSH: Open SSH Configuration File... 명령을 사용하여 확실히 확인하세요)을 편집하고 다음을 추가하여 이 작업을 수행할 수 있습니다.

Host *
    ForwardAgent yes

특정 명명된 호스트에만 옵션을 설정하도록 더 제한적으로 설정할 수 있습니다.

SSH 파일 권한 오류 수정

SSH는 파일 권한에 대해 엄격할 수 있으며, 잘못 설정된 경우 "WARNING: UNPROTECTED PRIVATE KEY FILE!"과 같은 오류가 표시될 수 있습니다. 이를 해결하기 위해 파일 권한을 업데이트하는 몇 가지 방법이 있으며, 이는 아래 섹션에 설명되어 있습니다.

로컬 SSH 파일 및 폴더 권한

macOS / Linux

로컬 머신에서 다음 권한이 설정되었는지 확인하세요.

Windows

예상되는 특정 권한은 사용하는 SSH 구현에 따라 다를 수 있습니다. 기본 제공 Windows 10 OpenSSH 클라이언트 사용을 권장합니다.

이 경우, SSH 호스트의 원격 사용자에 대한 .ssh 폴더에 있는 모든 파일이 본인에게 속해 있고 다른 사용자가 액세스할 수 있는 권한이 없는지 확인하세요. 자세한 내용은 Windows OpenSSH 위키를 참조하세요.

다른 모든 클라이언트는 구현에서 예상하는 바에 대해 클라이언트의 설명서를 참조하세요.

서버 SSH 파일 및 폴더 권한

macOS / Linux

연결하려는 원격 머신에서 다음 권한이 설정되었는지 확인하세요.

현재 Linux 호스트만 지원되므로 macOS 및 Windows 10에 대한 권한은 생략되었습니다.

Windows

Windows OpenSSH 서버에 대한 적절한 파일 권한 설정에 대한 자세한 내용은 Windows OpenSSH 위키를 참조하세요.

지원되는 SSH 클라이언트 설치

VS Code는 PATH에서 ssh 명령을 찾습니다. 실패하는 경우, Windows에서는 Git for Windows의 기본 설치 경로에서 ssh.exe를 찾으려고 시도합니다. settings.json에 remote.SSH.path 속성을 추가하여 SSH 클라이언트를 찾을 위치를 VS Code에 명시적으로 알릴 수도 있습니다.

지원되는 SSH 서버 설치

SSH 호스트에서 Git 푸시 또는 동기화 시 중단 문제 해결

SSH를 사용하여 Git 리포지토리를 복제하고 SSH 키에 암호가 있는 경우, VS Code의 풀 및 동기화 기능이 원격에서 실행될 때 멈출 수 있습니다.

암호가 없는 SSH 키를 사용하거나, HTTPS를 사용하여 복제하거나, 명령줄에서 git push를 실행하여 문제를 해결하세요.

SSHFS를 사용하여 원격 호스트의 파일에 액세스

SSHFS는 SFTP를 기반으로 하는 안전한 원격 파일 시스템 액세스 프로토콜입니다. CIFS / Samba 공유와 같은 것보다 이점이 있는데, 모든 필요한 것이 해당 머신에 대한 SSH 액세스이기 때문입니다.

참고: 성능상의 이유로 SSHFS는 단일 파일 편집 및 콘텐츠 업로드/다운로드에 가장 적합합니다. 많은 파일을 한 번에 대량으로 읽기/쓰는 애플리케이션(예: 로컬 소스 제어 도구)을 사용해야 하는 경우, rsync가 더 나은 선택입니다.

macOS / Linux:

Linux에서는 배포판의 패키지 관리자를 사용하여 SSHFS를 설치할 수 있습니다. Debian/Ubuntu의 경우: sudo apt-get install sshfs

참고: WSL 1은 FUSE 또는 SSHFS를 지원하지 않으므로 현재 Windows에 대한 지침이 다릅니다. WSL 2는 FUSE 및 SSHFS 지원을 포함하므로 곧 변경될 것입니다.

macOS에서는 Homebrew를 사용하여 SSHFS를 설치할 수 있습니다.

brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac
brew link --overwrite sshfs-mac

또한, 원격 파일 시스템을 마운트하기 위해 명령줄을 사용하지 않으려면 SSHFS GUI를 설치할 수도 있습니다.

명령줄을 사용하려면 로컬 터미널에서 다음 명령을 실행합니다(user@hostname을 원격 사용자 및 호스트 이름/IP로 대체).

export USER_AT_HOST=user@hostname
# Make the directory where the remote filesystem will be mounted
mkdir -p "$HOME/sshfs/$USER_AT_HOST"
# Mount the remote filesystem
sshfs "$USER_AT_HOST:" "$HOME/sshfs/$USER_AT_HOST" -ovolname="$USER_AT_HOST" -p 22  \
    -o workaround=nonodelay -o transform_symlinks -o idmap=user  -C

그러면 원격 머신의 홈 폴더가 ~/sshfs 아래에 액세스 가능하게 됩니다. 완료되면 OS의 Finder / 파일 탐색기를 사용하거나 명령줄을 사용하여 마운트 해제할 수 있습니다.

umount "$HOME/sshfs/$USER_AT_HOST"

Windows

다음 단계를 따르세요.

1. Linux에서는 프로젝트에 .gitattributes 파일을 추가하여 Linux와 Windows 간의 일관된 줄 끝을 강제하여 두 운영 체제 간의 CRLF/LF 차이로 인한 예기치 않은 문제를 방지합니다. 자세한 내용은 WSL에서 Git 줄 끝 문제 해결을 참조하세요.

2. 다음으로, Chocolatey를 사용하여 SSHFS-Win을 설치합니다: choco install sshfs

3. Windows용 SSHFS를 설치한 후, 파일 탐색기의 네트워크 드라이브 연결... 옵션을 \\sshfs\user@hostname 경로로 사용할 수 있습니다. 여기서 user@hostname은 원격 사용자와 호스트 이름/IP입니다. 명령 프롬프트를 사용하여 이 작업을 스크립팅할 수 있습니다: net use /PERSISTENT:NO X: \\sshfs\user@hostname

4. 완료되면 파일 탐색기에서 드라이브를 마우스 오른쪽 버튼으로 클릭하고 연결 끊기를 선택하여 연결을 해제합니다.

터미널에서 원격 호스트에 연결

호스트가 구성되면 원격 URI를 전달하여 터미널에서 직접 연결할 수 있습니다.

예를 들어, remote_server에 연결하고 /code/my_project 폴더를 열려면 다음을 실행합니다.

code --remote ssh-remote+remote_server /code/my_project

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

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

code --folder-uri vscode-remote://ssh-remote+remote_server/code/folder.with.dot

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

code --file-uri vscode-remote://ssh-remote+remote_server/code/fileWithoutExtension

rsync를 사용하여 소스 코드 로컬 복사본 유지

원격 파일에 액세스하기 위해 SSHFS를 사용하는 것의 대안은 rsync를 사용하여 원격 호스트의 폴더 전체 내용을 로컬 머신으로 복사하는 것입니다. rsync 명령은 실행될 때마다 업데이트해야 하는 파일을 결정하므로 scp 또는 sftp와 같은 것을 사용하는 것보다 훨씬 효율적이고 편리합니다. 이는 주로 다중 파일 또는 성능 집약적인 로컬 도구를 사용해야 하는 경우 고려할 사항입니다.

rsync 명령은 macOS에서 기본적으로 제공되며 Linux 패키지 관리자(예: Debian/Ubuntu의 경우 sudo apt-get install rsync)를 사용하여 설치할 수 있습니다. Windows의 경우, 명령에 액세스하려면 WSL 또는 Cygwin을 사용해야 합니다.

명령을 사용하려면 동기화된 콘텐츠를 저장하려는 폴더로 이동하여 다음을 실행합니다(user@hostname을 원격 사용자 및 호스트 이름/IP로, /remote/source/code/path를 원격 소스 코드 위치로 대체).

macOS, Linux 또는 WSL 내부

rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" .

또는 Windows의 WSL을 PowerShell에서 사용

wsl rsync -rlptzv --progress --delete --exclude=.git "user@hostname:/remote/source/code/path" "`$(wslpath -a '$PWD')"

이 명령을 실행할 때마다 최신 파일 복사본을 가져올 수 있으며, 변경된 내용만 전송됩니다. .git 폴더는 성능상의 이유로, 그리고 원격 호스트의 상태에 대한 걱정 없이 로컬 Git 도구를 사용할 수 있도록 의도적으로 제외됩니다.

콘텐츠를 푸시하려면 명령의 소스 및 대상 매개변수를 반대로 하십시오. 그러나 Windows에서는 푸시하기 전에 프로젝트에 .gitattributes 파일을 추가하여 일관된 줄 끝을 강제해야 합니다. 자세한 내용은 WSL에서 Git 줄 끝 문제 해결(많은 파일 수정 발생)을 참조하십시오.

rsync -rlptzv --progress --delete --exclude=.git . "user@hostname:/remote/source/code/path"

원격에서 VS Code 서버 정리

SSH 확장은 원격 머신에서 VS Code 서버를 정리하는 명령인 Remote-SSH: Uninstall VS Code Server from Host...를 제공합니다. 이 명령은 실행 중인 VS Code 서버 프로세스를 종료하고 서버가 설치된 폴더를 삭제합니다.

이 단계를 수동으로 실행하거나 명령이 작동하지 않는 경우 다음과 같은 스크립트를 실행할 수 있습니다.

# Kill server processes
kill -9 $(ps aux | grep vscode-server | grep $USER | grep -v grep | awk '{print $2}')
# Delete related files and folder
rm -rf $HOME/.vscode-server # Or ~/.vscode-server-insiders

VS Code 서버는 이전에 ~/.vscode-remote 아래에 설치되었으므로 해당 위치도 확인할 수 있습니다.

원격 WSL 2 호스트에 SSH 연결

원격 머신에서 실행되는 WSL 배포판에 연결하기 위해 SSH를 사용하고 싶을 수 있습니다. Windows 10의 Bash 및 WSL 2에 외부 머신에서 SSH로 연결하는 방법에 대한 자세한 내용은 이 가이드를 확인하십시오.

이슈 제출

Remote-SSH 확장을 사용하는 데 문제가 있고 이슈를 제출해야 한다고 생각되면 먼저 이 사이트의 문서를 검토한 다음 문제 해결 위키 문서에서 로그 파일을 가져오고 문제의 원인을 좁히는 데 도움이 될 수 있는 추가 단계를 시도하는 방법에 대한 정보를 확인하십시오.

Dev Containers 팁

Dev Containers 사용 팁에 대해 읽고 싶다면 Dev Containers 팁 및 요령으로 이동할 수 있습니다.

WSL 팁

첫 시작: VS Code 서버 필수 구성 요소

일부 WSL Linux 배포판에는 VS Code 서버가 시작하는 데 필요한 라이브러리가 부족합니다. 패키지 관리자를 사용하여 Linux 배포판에 추가 라이브러리를 추가할 수 있습니다.

Debian 및 Ubuntu

wget 및 ca-certificates를 추가하려면 Debian 또는 Ubuntu WSL 셸을 엽니다.

sudo apt-get update && sudo apt-get install wget ca-certificates

Alpine

libstdc++를 추가하려면 루트로 Alpine WSL 셸을 엽니다(wsl -d Alpine -u root).

apk update && apk add libstdc++

Windows 10 2018년 4월 업데이트(빌드 1803) 이전 버전에서는 /bin/bash가 필요합니다.

apk update && apk add bash

WSL 확장에서 사용하는 배포판 선택

WSL: New Window는 기본값으로 등록된 WSL 배포판을 엽니다.

기본값이 아닌 배포판을 열려면 사용할 배포판의 WSL 셸에서 code .를 실행하거나 WSL: New Window using Distro를 사용하십시오.

Windows 10 2019년 5월 업데이트(버전 1903) 이전의 WSL 버전에서는 WSL 명령이 기본 배포판만 사용할 수 있습니다. 이러한 이유로 WSL 확장은 기본 배포판을 변경하는 데 동의하는지 묻는 메시지를 표시할 수 있습니다.

기본값을 변경하려면 언제든지 wslconfig.exe를 사용할 수 있습니다.

예를 들어,

wslconfig /setdefault Ubuntu

다음 명령을 실행하여 설치된 배포판을 볼 수 있습니다.

wslconfig /l

서버 시작 환경 구성

WSL 확장이 WSL에서 VS Code 서버를 시작할 때 사용자 지정 구성 스크립트가 시작을 방해할 수 있으므로 셸 구성 스크립트를 실행하지 않습니다.

시작 환경을 구성해야 하는 경우 여기에 설명된 환경 설정 스크립트를 사용할 수 있습니다.

원격 확장 호스트 환경 구성

원격 확장 호스트 및 터미널의 환경은 기본 셸의 구성 스크립트를 기반으로 합니다. 원격 확장 호스트 프로세스의 환경 변수를 평가하기 위해 서버는 기본 셸의 인스턴스를 대화형 로그인 셸로 생성합니다. 거기에서 환경 변수를 프로빙하고 원격 확장 호스트 프로세스의 초기 환경으로 사용합니다. 따라서 환경 변수의 값은 기본값으로 구성된 셸과 해당 셸의 구성 스크립트 내용에 따라 달라집니다.

각 셸의 구성 스크립트에 대한 개요는 Unix shell initialization을 참조하십시오. 대부분의 WSL 배포판에는 /bin/bash가 기본 셸로 구성되어 있습니다. /bin/bash는 먼저 /etc/profile 아래의 시작 파일을 찾고 ~/.bash_profile, ~/.bash_login, ~/.profile 아래의 모든 시작 파일을 찾습니다.

WSL 배포판의 기본 셸을 변경하려면 이 블로그 게시물의 지침을 따르십시오.

code 명령이 작동하지 않는 문제 해결

Windows의 WSL 터미널에서 code를 입력할 때 code를 찾을 수 없어 작동하지 않으면 WSL의 PATH에서 몇 가지 주요 위치가 누락되었을 수 있습니다.

WSL 터미널을 열고 echo $PATH를 입력하여 확인합니다. VS Code 설치 경로가 목록에 표시되어야 합니다. 기본적으로 다음과 같습니다.

/mnt/c/Users/Your Username/AppData/Local/Programs/Microsoft VS Code/bin

그러나 시스템 설치 프로그램을 사용한 경우 설치 경로는 다음과 같습니다.

/mnt/c/Program Files/Microsoft VS Code/bin

...또는...

/mnt/c/Program Files (x86)/Microsoft VS Code/bin

PATH 변수가 Windows에서 상속되는 것은 WSL의 기능입니다. Windows PATH 변수를 변경하려면 Windows의 시작 메뉴에서 계정에 대한 환경 변수 편집 명령을 사용하십시오.

.bashrc를 비활성화한 경우 .bashrc를 편집하고 다음을 추가한 다음 새 터미널을 시작합니다.

WINDOWS_USERNAME="Your Windows Alias"

export PATH="$PATH:/mnt/c/Windows/System32:/mnt/c/Users/${WINDOWS_USERNAME}/AppData/Local/Programs/Microsoft VS Code/bin"
# or...
# export PATH="$PATH:/mnt/c/Program Files/Microsoft VS Code/bin"
# or...
# export PATH="$PATH:/mnt/c/Program Files (x86)/Microsoft VS Code/bin"

참고: 디렉터리 이름의 공백 문자는 따옴표로 묶거나 이스케이프해야 합니다.

'code' 명령 문제 찾기

Windows 명령 프롬프트에서 code를 입력해도 VS Code가 실행되지 않으면 VSCODE_WSL_DEBUG_INFO=true code .를 실행하여 문제를 진단하는 데 도움이 될 수 있습니다.

이슈를 제출하고 전체 출력을 첨부해 주십시오.

서버 시작 또는 연결 문제 찾기

WSL 창이 원격 서버에 연결하지 못하면 WSL 로그에서 더 많은 정보를 얻을 수 있습니다. 이슈를 제출할 때는 항상 WSL 로그의 전체 내용을 보내는 것이 중요합니다.

WSL: Open Log 명령을 실행하여 WSL 로그를 엽니다. 로그는 WSL 탭 아래의 터미널 보기에서 표시됩니다.

더 자세한 로깅을 얻으려면 사용자 설정에서 remote.WSL.debug 설정을 활성화하십시오.

서버가 세그멘테이션 오류로 시작되지 않음

코어 덤프 파일을 보내서 이 문제를 조사하는 데 도움을 줄 수 있습니다. 코어 덤프 파일을 얻으려면 다음 단계를 따르십시오.

Windows 명령 프롬프트에서

• code --locate-extension ms-vscode-remote.remote-wsl을 실행하여 WSL 확장 폴더를 결정합니다.
• 반환된 경로로 cd합니다.
• wslServer.sh 스크립트를 VS Code로 엽니다. code .\scripts\wslServer.sh.
• 마지막 줄("$VSCODE_REMOTE_BIN/$COMMIT/bin/$SERVER_APPNAME" "$@" 이전) 앞에 ulimit -C unlimited를 추가합니다.
• 원격 서버를 실행하는 WSL 창을 시작하고 세그멘테이션 오류가 발생할 때까지 기다립니다.

코어 파일은 위의 WSL 확장 폴더에 있습니다.

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

이는 VS Code에서 활성화된 파일 감시자로 인해 발생하는 WSL 파일 시스템 구현(Microsoft/WSL#3395, Microsoft/WSL#1956)의 알려진 문제입니다. 이 문제는 WSL 2에서만 수정될 것입니다.

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

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

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

WSL에서 Git 줄 끝 문제 해결(많은 파일 수정 발생)

Windows와 Linux는 기본 줄 끝이 다르므로 Git은 줄 끝 외에는 차이가 없는 많은 수의 수정된 파일을 보고할 수 있습니다. 이를 방지하기 위해 .gitattributes 파일을 사용하거나 Windows 측에서 전역적으로 줄 끝 변환을 비활성화할 수 있습니다.

일반적으로 리포지토리에 .gitattributes 파일을 추가하거나 수정하는 것이 이 문제를 해결하는 가장 확실한 방법입니다. 이 파일을 소스 제어에 커밋하면 다른 사람에게 도움이 되며 리포지토리별로 동작을 적절하게 다양하게 적용할 수 있습니다. 예를 들어, 리포지토리의 루트에 있는 .gitattributes 파일에 다음을 추가하면 Windows 배치 파일(CRLF 필요)을 제외한 모든 항목이 LF로 강제됩니다.

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

이는 Git v2.10+에서 작동하므로 문제가 발생하는 경우 최신 Git 클라이언트가 설치되어 있는지 확인하십시오. CRLF가 필요한 다른 파일 형식을 이와 동일한 파일에 추가할 수 있습니다.

여전히 Unix 스타일 줄 끝(LF)을 항상 업로드하려면 input 옵션을 사용할 수 있습니다.

git config --global core.autocrlf input

줄 끝 변환을 완전히 비활성화하려면 대신 다음을 실행하십시오.

git config --global core.autocrlf false

마지막으로 이러한 설정이 적용되려면 리포지토리를 다시 복제해야 할 수 있습니다.

Windows와 WSL 간 Git 자격 증명 공유

리포지토리를 HTTPS로 복제하고 Windows에 자격 증명 도우미가 구성되어 있는 경우 WSL과 공유하여 입력하는 암호를 양쪽에서 지속시킬 수 있습니다. (SSH 키 사용에는 해당되지 않습니다.)

다음 단계를 따르십시오.

1. Windows 명령 프롬프트 또는 PowerShell에서 다음을 실행하여 Windows에서 자격 증명 관리자를 구성합니다.

    git config --global credential.helper wincred
   

2. WSL 터미널에서 다음을 실행하여 WSL이 동일한 자격 증명 도우미를 사용하도록 구성합니다.

    git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
   

Windows 측에서 Git을 작업할 때 입력하는 암호는 이제 WSL에서도 사용할 수 있으며 그 반대도 마찬가지입니다.

WSL에서 Git 푸시 또는 동기화 시 끊김 현상 해결

SSH를 사용하여 Git 리포지토리를 복제하고 SSH 키에 암호가 있는 경우, VS Code의 풀 및 동기화 기능이 원격에서 실행될 때 멈출 수 있습니다.

암호가 없는 SSH 키를 사용하거나, HTTPS를 사용하여 복제하거나, 명령줄에서 git push를 실행하여 문제를 해결하세요.

GitHub Codespaces 팁

GitHub Codespaces에 대한 팁과 질문은 GitHub Codespaces 설명서를 참조하십시오. Codespaces에 영향을 줄 수 있는 알려진 웹 제한 사항 및 적응도 확인할 수 있습니다.

확장 기능 팁

많은 확장이 수정 없이 작동하지만 특정 기능이 예상대로 작동하지 못하게 하는 몇 가지 문제가 있을 수 있습니다. 일부 경우에는 다른 명령을 사용하여 문제를 해결할 수 있고, 다른 경우에는 확장을 수정해야 할 수도 있습니다. 이 섹션에서는 일반적인 문제에 대한 빠른 참조와 해결 팁을 제공합니다. 확장 수정에 대한 자세한 내용은 원격 개발 지원의 메인 확장 문서를 참조하십시오.

누락된 종속성 오류 해결

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

로컬 절대 경로 설정이 원격에서 적용되지 않음

VS Code의 로컬 사용자 설정은 원격 엔드포인트에 연결할 때 재사용됩니다. 이렇게 하면 사용자 경험이 일관되게 유지되지만, 대상 위치가 다르기 때문에 로컬 머신과 각 호스트/컨테이너/WSL 간에 절대 경로 설정을 다르게 해야 할 수 있습니다.

해결 방법: 명령 팔레트( F1)에서 Preferences: Open Remote Settings 명령을 실행하거나 설정 편집기에서 Remote 탭을 선택하여 원격 엔드포인트에 연결한 후 엔드포인트별 설정을 지정할 수 있습니다. 이러한 설정은 연결할 때마다 적용되는 로컬 설정을 재정의합니다.

로컬 VSIX를 원격 엔드포인트에 설치해야 함

개발 중이거나 확장 작성자가 수정을 테스트하도록 요청하는 경우 로컬 VSIX를 원격 머신에 설치해야 하는 경우가 있습니다.

해결 방법: SSH 호스트, 컨테이너 또는 WSL에 연결한 후에는 로컬에서와 동일한 방식으로 VSIX를 설치할 수 있습니다. 명령 팔레트( F1)에서 Extensions: Install from VSIX... 명령을 실행합니다. settings.json에 "extensions.autoUpdate": false를 추가하여 최신 Marketplace 버전으로 자동 업데이트되는 것을 방지할 수도 있습니다. 원격 환경에서 확장을 개발하고 테스트하는 방법에 대한 자세한 내용은 Supporting Remote Development를 참조하십시오.

브라우저가 로컬에서 열리지 않음

일부 확장은 외부 노드 모듈 또는 사용자 지정 코드를 사용하여 브라우저 창을 엽니다. 불행히도 이로 인해 확장이 로컬이 아닌 원격으로 브라우저를 실행할 수 있습니다.

해결 방법: 확장은 이 문제를 해결하기 위해 vscode.env.openExternal API를 사용할 수 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

클립보드가 작동하지 않음

일부 확장은 clipboardy와 같은 노드 모듈을 사용하여 클립보드와 통합합니다. 불행히도 이로 인해 확장이 원격 측 클립보드와 올바르게 통합되지 않을 수 있습니다.

해결 방법: 확장은 문제를 해결하기 위해 VS Code 클립보드 API로 전환할 수 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

로컬 웹 서버에 브라우저 또는 애플리케이션에서 액세스할 수 없음

컨테이너, SSH 호스트 또는 GitHub Codespaces 내부에서 작업할 때 브라우저가 연결하는 포트가 차단될 수 있습니다.

해결 방법: 확장은 이 문제를 해결하기 위해 vscode.env.openExternal 또는 vscode.env.asExternalUri API(localhost 포트를 자동으로 전달함)를 사용할 수 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오. 해결 방법으로 Forward a Port 명령을 사용하여 수동으로 수행할 수 있습니다.

웹뷰 콘텐츠가 표시되지 않음

확장의 웹뷰 콘텐츠가 로컬 웹 서버에 연결하기 위해 iframe을 사용하는 경우 연결 중인 포트가 차단될 수 있습니다. 또한 확장이 asWebviewUri 대신 vscode-resource:// URI를 하드 코딩하는 경우 Codespaces 브라우저 편집기에 콘텐츠가 표시되지 않을 수 있습니다.

해결 방법: 확장은 vscode-resource:// URI 문제를 해결하기 위해 webview.asWebviewUri를 사용할 수 있습니다.

포트가 차단되는 경우 가장 좋은 방법은 대신 웹뷰 메시지 전달 API를 사용하는 것입니다. 해결 방법으로 vscode.env.asExternalUri를 사용하여 웹뷰가 VS Code에서 생성된 localhost 웹 서버에 연결하도록 허용할 수 있습니다. 그러나 현재 이 기능은 Codespaces 브라우저 기반 편집기(만 해당)에서 MicrosoftDocs/vscodespaces#11에 의해 차단됩니다. 해결 방법에 대한 자세한 내용은 확장 작성자 가이드를 참조하십시오.

차단된 localhost 포트

외부 애플리케이션에서 localhost 포트에 연결하려고 하면 포트가 차단될 수 있습니다.

해결 방법: VS Code 1.40부터 확장 기능이 임의 포트를 프로그래밍 방식으로 전달할 수 있도록 새로운 vscode.env.asExternalUri API가 도입되었습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오. 해결 방법으로 Forward a Port 명령을 사용하여 수동으로 수행할 수 있습니다.

확장 데이터 저장 오류

확장은 Linux에서 ~/.config/Code 폴더를 찾아 전역 데이터를 유지하려고 할 수 있습니다. 이 폴더가 존재하지 않으면 확장에서 ENOENT: no such file or directory, open '/root/.config/Code/User/filename-goes-here와 같은 오류가 발생할 수 있습니다.

해결 방법: 확장은 이 문제를 해결하기 위해 context.globalStorageUri 또는 context.storageUri 속성을 사용할 수 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

로그인할 수 없거나 새 엔드포인트에 연결할 때마다 로그인해야 함

로그인이 필요한 확장은 자체 코드를 사용하여 비밀을 유지할 수 있습니다. 이 코드는 누락된 종속성으로 인해 실패할 수 있습니다. 성공하더라도 비밀은 원격으로 저장되므로 새 엔드포인트마다 로그인해야 합니다.

해결 방법: 확장은 SecretStorage API를 사용하여 이 문제를 해결할 수 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

호환되지 않는 확장이 VS Code 연결을 방해함

호환되지 않는 확장이 원격 호스트, 컨테이너 또는 WSL에 설치된 경우 VS Code 서버가 비호환성으로 인해 중단되거나 충돌하는 사례를 보았습니다. 확장이 즉시 활성화되면 연결하지 못하고 확장을 제거할 수 없게 됩니다.

해결 방법: 다음 단계를 따라 원격 확장 폴더를 수동으로 삭제합니다.

1. 컨테이너의 경우 devcontainer.json에 결함이 있는 확장에 대한 참조가 더 이상 포함되지 않도록 하십시오.

2. 그런 다음 별도의 터미널/명령 프롬프트를 사용하여 원격 호스트, 컨테이너 또는 WSL에 연결합니다.

   • SSH 또는 WSL의 경우 해당 환경에 연결합니다(서버에 연결하려면 ssh를 실행하거나 WSL 터미널을 엽니다).
   • 컨테이너를 사용하는 경우 docker ps -a를 호출하고 목록에서 올바른 이름의 이미지를 찾아 컨테이너 ID를 식별합니다. 컨테이너가 중지된 경우 docker run -it <id> /bin/sh를 실행합니다. 실행 중인 경우 docker exec -it <id> /bin/sh를 실행합니다.

3. 연결되면 VS Code 안정 버전의 경우 rm -rf ~/.vscode-server/extensions 및/또는 VS Code Insiders의 경우 rm -rf ~/.vscode-server-insiders/extensions를 실행하여 모든 확장을 제거합니다.

빌드된 네이티브 모듈을 배포하거나 가져오는 확장 오류

VS Code 확장과 함께 번들로 제공되거나 동적으로 획득된 네이티브 모듈은 Electron의 electron-rebuild를 사용하여 다시 컴파일해야 합니다. 그러나 VS Code 서버는 표준(비-Electron) 버전의 Node.js를 실행하므로 원격으로 사용할 때 이진 파일에 오류가 발생할 수 있습니다.

해결 방법: 이 문제를 해결하려면 확장을 수정해야 합니다. VS Code가 제공하는 Node.js 버전의 "모듈"에 대한 두 세트의 이진 파일(Electron 및 표준 Node.js)을 포함하거나 동적으로 획득해야 하며, 활성화 함수에서 context.executionContext === vscode.ExtensionExecutionContext.Remote인지 확인하여 올바른 이진 파일을 설정해야 합니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

확장이 x86_64가 아닌 호스트 또는 Alpine Linux에서만 실패함

확장이 Debian 9+, Ubuntu 16.04+, 또는 RHEL/CentOS 7+ 원격 SSH 호스트, 컨테이너 또는 WSL에서 작동하지만 지원되는 x86_64가 아닌 호스트(예: ARMv7l) 또는 Alpine Linux 컨테이너에서 실패하는 경우, 확장은 이러한 플랫폼을 지원하지 않는 네이티브 코드 또는 런타임만 포함할 수 있습니다. 예를 들어, 확장은 x86_64로 컴파일된 네이티브 모듈 또는 런타임 버전만 포함할 수 있습니다. Alpine Linux의 경우 포함된 네이티브 코드 또는 런타임이 Alpine Linux(musl)와 다른 배포판(glibc)의 libc 구현 방식 간의 근본적인 차이 때문에 작동하지 않을 수 있습니다.

해결 방법: 확장은 이러한 추가 대상에 대한 이진 파일을 컴파일/포함하여 이러한 플랫폼을 지원하도록 선택해야 합니다. 일부 타사 npm 모듈에도 이 문제가 발생할 수 있는 네이티브 코드가 포함될 수 있습니다. 따라서 경우에 따라 npm 모듈 작성자와 협력하여 추가 컴파일 대상을 추가해야 할 수도 있습니다. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

누락된 모듈로 인해 확장 실패

대체 기능을 제공하지 않고 Electron 또는 VS Code 기본 모듈(확장 API에서 노출되지 않음)에 의존하는 확장은 원격으로 실행될 때 실패할 수 있습니다. 개발자 도구 콘솔에서 original-fs를 찾을 수 없다는 오류가 표시될 수 있습니다.

해결 방법: Electron 모듈에 대한 의존성을 제거하거나 대체 기능을 제공하십시오. 자세한 내용은 확장 작성자 가이드를 참조하십시오.

원격 작업 영역 파일에 액세스/로컬 머신으로 전송할 수 없음

외부 애플리케이션에서 작업 영역 파일을 여는 확장은 외부 애플리케이션이 원격 파일에 직접 액세스할 수 없기 때문에 오류가 발생할 수 있습니다.

해결 방법: 로컬에서 실행되도록 설계된 "UI" 확장을 만드는 경우 vscode.workspace.fs API를 사용하여 원격 작업 영역 파일 시스템과 상호 작용할 수 있습니다. 그런 다음 이를 "작업 영역" 확장에 대한 종속성으로 만들고 필요에 따라 명령을 사용하여 호출할 수 있습니다. 다양한 유형의 확장 및 명령을 사용하여 통신하는 방법에 대한 자세한 내용은 확장 작성자 가이드를 참조하십시오.

확장에서 연결된 장치에 액세스할 수 없음

로컬에 연결된 장치에 액세스하는 확장은 원격으로 실행될 때 해당 장치에 연결할 수 없습니다.

해결 방법: 현재 없음. 이 문제를 해결하기 위한 최상의 접근 방식을 조사 중입니다.

질문 및 피드백

문제 보고

원격 개발 확장에 문제가 발생하는 경우 문제를 진단할 수 있도록 올바른 로그를 수집하는 것이 중요합니다. 이슈 제출.

각 원격 확장은 로그를 보기 위한 명령을 제공합니다.

명령 팔레트( F1)에서 Remote-SSH: Show Log를 사용하여 Remote - SSH 확장 로그를 가져올 수 있습니다. Remote - SSH 문제를 보고할 때 Remote - SSH를 사용하지 않는 외부 터미널에서 머신에 SSH로 연결할 수 있는지 여부도 확인하십시오.

마찬가지로 Dev Containers: Show Container Log를 사용하여 Dev Containers 확장 로그를 가져올 수 있습니다.

위의 두 가지와 마찬가지로 WSL: Show Log를 사용하여 WSL 확장 로그를 가져올 수 있습니다. 또한 문제가 WSL 리포지토리에서 이미 추적 중이며(WSL 확장으로 인한 것이 아님) 문제가 추적 중인지 확인하십시오.

다른 확장을 원격으로 사용하는 데 문제가 발생하는 경우(예: 원격 컨텍스트에서 다른 확장이 로드되거나 설치되지 않는 경우) Output: Focus on Output View에서 Log (Remote Extension Host) 로그를 가져와 드롭다운에서 Log (Remote Extension Host)를 선택하는 것이 좋습니다.

참고: Log (Extension Host)만 보이는 경우, 이것은 로컬 확장 호스트이며 원격 확장 호스트가 시작되지 않은 것입니다. 로그 채널은 로그 파일이 생성된 후에만 생성되므로 원격 확장 호스트가 시작되지 않으면 원격 확장 호스트 로그 파일이 생성되지 않아 Output 뷰에 표시되지 않습니다. 이 정보도 이슈에 포함하면 도움이 됩니다.

원격 질문 및 피드백 리소스

다양한 원격 리소스가 있습니다.

• 원격 개발 FAQ를 참조하십시오.
• Stack Overflow에서 검색하십시오.
• 기능 요청을 추가하거나 문제 보고를 하십시오.