VS Code Remote SSH를 사용하면 윈도우 PC에서 작업하면서도 VS Code가 SSH를 통해 원격 Linux 서버에 연결하고, 서버의 파일 시스템을 VS Code 탐색기에서 열어 원격 환경에서 파일을 편집할 수 있습니다. 별도의 FTP 프로그램으로 파일을 업로드하거나 Xshell에서 vi 에디터를 사용하는 대신, Visual Studio Code의 강력한 코드 편집 기능을 그대로 활용할 수 있습니다.
이번 글에서는 VS Code Remote SSH 설정 방법부터 SSH Config 작성, SSH Key를 이용한 비밀번호 없는 로그인, 그리고 자주 발생하는 접속 오류 해결 방법까지 단계별로 알아보겠습니다.
1. 왜 VS Code Remote – SSH인가? (기존 방식과의 비교)
개발 및 시스템 운영 업무를 하다 보면 윈도우(Windows) PC를 로컬 작업 공간으로 사용하면서, 실제 코드 실행이나 데이터 저장은 리눅스(Linux) 서버에서 처리해야 하는 상황을 자주 접하게 됩니다.
과거에는 이러한 원격 개발을 위해 Xshell이나 Putty 같은 터미널 프로그램으로 리눅스 서버에 접속한 뒤, 서버에 내장된 vi/vim 에디터를 사용하는 것이 일반적이었습니다. 하지만 vi 에디터는 단일 파일 수정에는 유용할지 몰라도 다음과 같은 명확한 한계가 있습니다.
- 수십 개의 파일이 얽혀 있는 프로젝트 구조를 한눈에 파악하기 어렵습니다.
- 복잡한 코드 검색, 마우스 클릭을 통한 이동, 자동 완성과 같은 현대적인 IDE의 편의 기능을 사용할 수 없습니다.
- 클립보드 복사 및 붙여넣기 동작이 번거롭고 직관적이지 않습니다.
이러한 불편함을 깔끔하게 해결해 주는 도구가 바로 VS Code(Visual Studio Code)의 Remote – SSH 확장(Extension)입니다. 이 익스텐션을 사용하면 리눅스 서버에 있는 파일과 디렉터리를 윈도우 로컬 탐색기처럼 펼쳐놓고, VS Code의 강력한 에디터 기능을 그대로 활용하여 코딩할 수 있습니다.
2. Xshell + vi 환경 vs VS Code Remote – SSH 비교
두 방식의 차이를 비교하면 VS Code Remote – SSH의 생산성 우위를 한눈에 알 수 있습니다.
| 구분 | 기존 방식 (Xshell + vi) | VS Code 원격 접속 – SSH |
|---|---|---|
| 작업 환경 | CUI 기반 텍스트 터미널 | GUI 기반 현대적 IDE 화면 |
| 프로젝트 탐색 | cd, ls 명령어로 직접 이동 | 좌측 사이드바 파일 트리 제공 |
| 코드 수정 | vi 단축키 명령어 입력 필수 | 마우스 클릭 및 로컬 단축키 지원 |
| 부가 기능 | 플러그인 설정이 복잡함 | VS Code 익스텐션 생태계 활용 가능 |
| 터미널 지원 | 독립된 터미널 창 필요 | VS Code 내장 터미널 동시 활용 |
3. Remote – SSH 설치 및 SSH Config 설정 방법
VS Code에서 리눅스 서버로 원격 접속 환경을 구축하는 전체 과정은 크게 3단계로 나뉩니다.
1단계: Remote – SSH 확장 설치
- 윈도우에서 VS Code를 실행합니다.
- 단축키
Ctrl + Shift + X를 눌러 확장(Extensions) 탭을 엽니다. - 검색창에
Remote - SSH를 입력하고, Microsoft에서 공식 제공하는 확장의 [설치(Install)] 버튼을 클릭합니다.
2단계: SSH 설정 파일(config) 작성
매번 접속할 때마다 IP 주소, 계정명, 포트 번호를 직접 입력하는 번거로움을 줄이기 위해 SSH 설정 파일을 구성합니다.
- 단축키
F1또는Ctrl + Shift + P를 눌러 명령어 팔레트를 엽니다. Remote-SSH: Open SSH Configuration File...을 검색하여 선택합니다.- 사용자 계정 경로(예:
C:Users\사용자명\.ssh\config)의 파일을 선택합니다. - 파일 내부에 접속할 서버 정보를 아래 형식에 맞춰 입력하고 저장합니다.
Host my-linux-server
HostName 192.168.0.100
User ubuntu
Port 22
IdentityFile ~/.ssh/id_rsa- Host: VS Code에서 식별할 별칭(원하는 이름 지정)
- HostName: 리눅스 서버의 IP 주소 또는 도메인 주소
- User: 리눅스 서버 접속 계정명
- Port: SSH 접속 포트 번호 (기본값: 22)
- IdentityFile: (선택 사항) SSH 개인키 경로
3단계: 원격 서버 접속 및 폴더 열기
- VS Code 좌측 하단의 파란색 원격 링커 아이콘(
><)을 클릭하거나,F1을 누르고Remote-SSH: Connect to Host...를 선택합니다. - 방금 설정한 Host 이름(
my-linux-server)을 선택합니다. - 새로운 VS Code 창이 열리며 원격 OS 유형(Linux)을 선택하라는 안내가 뜨면 Linux를 선택합니다.
- 서버 비밀번호를 입력하면 접속이 완료됩니다.
- 접속 완료 후
Ctrl + K, Ctrl + O(폴더 열기)를 통해 리눅스 서버의 원하는 디렉터리 경로를 지정하여 프로젝트를 시작합니다.
4. SSH Key를 이용한 비밀번호 인증 생략하기 (SSH Key 인증)
접속할 때마다 비밀번호를 입력하는 과정마저 줄이고 싶다면, SSH 공개키/개인키 쌍을 생성하여 등록해 두는 것을 권장합니다.
1) 윈도우 로컬 PC에서 키 생성
윈도우 PowerShell 또는 명령 프롬프트(cmd)를 열고 다음 명령어를 입력합니다.
ssh-keygen -t ed25519엔터를 몇 번 치면 C:Users사용자명.ssh 경로에 id_ed25519(개인키)와 id_ed25519.pub(공개키) 파일이 생성됩니다.
2) 리눅스 서버에 공개키 등록
생성된 id_ed25519.pub( 파일의 텍스트 내용을 복사하여, 리눅스 서버의 ~/.ssh/authorized_keys 파일 끝에 붙여넣고 저장합니다.
authorized_keys에는 id_ed25519.pub의 전체 한 줄을 그대로 넣어야 합니다.
줄 중간에서 임의로 줄바꿈하거나 개인키(id_ed25519)를 서버에 복사하면 안 됩니다.
# 리눅스 서버 터미널 예시
mkdir -p ~/.ssh
nano ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
이 작업이 완료되면 이후 VS Code 접속 시 비밀번호 입력창 없이 바로 원격 환경에 연결됩니다.
5. 자주 발생하는 트러블슈팅
1) 권한 거부됨(공개키, 암호) 오류
원인: 계정명, 비밀번호가 틀렸거나, authorized_keys 파일의 권한 설정이 올바르지 않은 경우 발생합니다.해결: 리눅스 서버의 .ssh 디렉터리 권한이 700, authorized_keys 파일 권한이 600으로 설정되어 있는지 확인하세요.
2) Connection Timeout 오류
원인: 서버 IP 주소 입력 오류, 리눅스 방화벽(ufw, firewalld) 차단, 또는 SSH 서비스(sshd) 미실행 상태입니다.
Rocky Linux/RHEL 계열에서는 sshd, Ubuntu 계열에서는 ssh 서비스 이름을 사용하는 경우가 있습니다.
해결: 서버에서 sudo systemctl status sshd 명령어로 SSH 서비스 작동 여부를 확인하고, 포트 접근 권한을 점검하세요.
Ubuntu를 사용한다면 이렇게 사용하시면 됩니다.
해결: 서버에서 sudo systemctl status ssh 명령어로 SSH 서비스 작동 여부를 확인하고, 포트 접근 권한을 점검하세요.
3) Permission denied (publickey)
해결: 사용자명, SSH Key, authorized_keys 확인
4) Connection timed out
해결: IP, 포트, 방화벽 확인
5) Connection refused
해결: SSH 서비스 및 포트 확인
6) Could not establish connection
해결: SSH Config 확인
7) VS Code Server 설치 실패
해결: 서버의 디스크 공간, 권한, 네트워크 확인
8) Host key 관련 오류
해결: known_hosts 확인
9) 터미널에서는 SSH가 되는데 VS Code에서는 안 되는 경우
해결: VS Code가 사용하는 SSH Config와 IdentityFile 확인
6. 요약 및 결론
단순한 서버 설정 변경이나 긴급 장애 대응에는 Xshell과 vi/vim만으로도 충분합니다. 하지만 여러 파일로 구성된 PHP, Python, Node.js 등의 프로젝트를 지속적으로 개발한다면 VS Code Remote – SSH가 훨씬 편리합니다.
VS Code의 Remote – SSH 확장을 활용하면 리눅스의 강력한 서버 성능과 윈도우 UI 에디터의 편의성을 동시에 누릴 수 있어 원격 개발 생산성이 획기적으로 향상됩니다.
저는 Windows PC에서 PHP 개발을 하면서 실제 서비스 파일은 Linux 서버에 저장하는 방식으로 작업하고 있습니다. 처음에는 Xshell로 서버에 접속하고 vi로 파일을 수정하거나 FTP로 파일을 내려받아 수정한 뒤 다시 업로드했습니다.
하지만 프로젝트 파일이 많아지면서 파일을 찾아 수정하고 다시 업로드하는 과정이 번거로워졌습니다. Remote – SSH를 설정한 이후에는 VS Code에서 서버의 프로젝트 폴더를 바로 열어 수정할 수 있어 작업 과정이 상당히 단순해졌습니다.
이런 경우에는 Remote SSH가 적합하지 않을 수 있습니다.
- 단순히 서버 파일 하나만 수정하는 경우
- 서버에 SSH 접속 자체가 허용되지 않는 경우
- 공용 PC에서 개인 SSH Key를 사용하는 경우
- 네트워크가 불안정한 환경
- 서버에서 VS Code Server 구성요소를 실행할 수 없는 환경
