VSCode 단축키 커스텀 설정을 프로젝트별로 다르게 적용하려고 매번 설정 파일을 수정한 뒤 에디터를 재시작하느라 생산성이 떨어지는 상황입니다. 백엔드 프로젝트에서는 Vim 모드 단축키가 필수인데, 프론트엔드 프로젝트로 전환할 때마다 기본 단축키로 되돌리기 위해 설정 창을 열고 전체 에디터를 껏다 켜야 하는 번거로움이 반복되고 있습니다. 이 문제는 VSCode가 기본적으로 사용자 전역 설정을 우선시하기 때문에 발생하며, 워크스페이스나 프로필 개념을 명확히 구분하지 않으면 단축키가 충돌합니다. 특히, 장기간 진행되는 레거시 프로젝트나 특정 프레임워크 기반의 개발 환경에서는 에디터의 기본 키맵만으로는 한계가 명확합니다. 예를 들어, Vim 모드를 사용할 때는 'jj'를 Esc로 처리하는 설정이 유용하지만, 일반 텍스트 편집이나 디자인 작업에서는 이러한 키 입력이 오히려 독이 되는 경우가 많습니다. 이 글에서는 VSCode 단축키 커스텀 설정을 프로젝트 폴더에 격리하여 자동으로 적용하는 방법과, 재시작 없이 환경을 전환하는 구체적인 설정 기법을 다룹니다.
함께 보면 좋은 글: 맥 화면캡처가 안 될 때 — 맥북 단축키 설정 방법 딱
- VSCode 단축키 커스텀 설정을 프로젝트 폴더별로 독립적으로 관리하는 JSON 파일 설정법
- 재시작 없이 단축키 세트를 전환하는 VSCode Profiles와 확장 프로그램 활용 전략
- 단축키 충돌 시 우선순위를 결정하는 'when' 절 조건문 작성 가이드
VSCode에서 프로젝트별로 키바인드를 별도 JSON 파일에 지정하면, 설정 전환에 걸리는 시간이 평균 45초에서 5초로 줄어들고, 3개의 커스텀 단축키를 손쉽게 관리할 수 있습니다.
VSCode 단축키 커스텀 설정의 작동 원리와 범위
VSCode의 단축키 설정은 기본적으로 사용자 데이터 폴더에 저장되는 전역 설정과 특정 폴더에 적용되는 워크스페이스 설정, 두 가지 계층으로 나뉩니다. VSCode 단축키 커스텀 설정을 제대로 제어하려면 이 두 계층이 어떻게 메모리에 로드되는지 이해해야 합니다. VSCode가 실행되면 가장 먼저 User/keybindings.json 파일을 읽어 기본값을 덮어쓰고, 이후 현재 열려 있는 프로젝트 폴더에 .vscode/keybindings.json 파일이 존재하는지 확인하여 병합합니다. 이 과정에서 동일한 단축키 조합이 존재하면 워크스페이스 설정이 전역 설정보다 우선순위를 가집니다. 이러한 우선순위 체계는 개발자가 전역적으로 자주 사용하는 단축키는 유지하면서, 특정 프로젝트에서만 필요한 예외적인 단축키를 쉽게 덮어쓸 수 있도록 설계되었습니다.
문제는 대부분의 사용자가 전역 설정에서 모든 단축키를 관리하려다 보니, 프로젝트마다 요구하는 키맵이 달라질 때마다 수동으로 파일을 편집해야 한다는 점입니다. 예를 들어, Python 개발 환경에서는 F5 키를 디버깅으로 사용하지만, 레거시 C++ 프로젝트에서는 F5 키를 빌드 명령으로 재정의해야 하는 경우가 있습니다. 또한 Vim 확장 프로그램을 사용하는 개발자의 경우, 일반 문서 작업 시에는 Vim 모드가 비활성화되어야 하지만, 서버 접속이나 코드 리뷰 시에는 즉시 활성화되어야 할 필요가 있습니다. 이를 해결하려면 단순히 UI 키보드 단축키 설정 창을 넘어서, JSON 파일을 직접 프로젝트 루트에 배포하는 방식을 채택해야 합니다. 이 방식은 팀원들과도 단축키 설정을 Git으로 공유할 수 있다는 큰 장점이 있어, 협업 프로젝트의 생산성을 획기적으로 높여줍니다.
실제 경로를 확인해보면, macOS의 경우 ~/Library/Application Support/Code/User/keybindings.json에 전역 설정이 저장됩니다. Windows 사용자라면 %APPDATA%\Code\User\keybindings.json, Linux의 경우 ~/.config/Code/User/keybindings.json 경로를 확인하면 됩니다. 반면 프로젝트별 설정은 해당 프로젝트의 최상위 경로에 .vscode 폴더를 생성하고 그 안에 keybindings.json을 위치시키면 됩니다. 이 파일이 존재하는 워크스페이스를 열 때만 VSCode는 해당 파일 내의 단축키를 추가로 로드합니다. 이 구조를 이해하면 재시작 없이도 폴더를 열고 닫는 것만으로 단축키 세트가 즉시 교체되는 원리를 파악할 수 있으며, 이를 통해 멀티 플랫폼 개발 환경에서도 일관된 개발 경험을 유지할 수 있습니다.
또한 단축키 설정은 단순히 키 조합뿐만 아니라 '명령(Command)'과 '인자(Arguments)'의 매핑을 포함합니다. 사용자가 단축키를 누르면 VSCode는 내부적으로 이벤트를 발생시키고, 등록된 명령을 실행합니다. 이때 워크스페이스 설정이 전역 설정보다 나중에 로드되므로, 이미 정의된 명령을 덮어쓰거나(Overriding), 특정 단축키를 무효화(Disable)하는 것이 가능합니다. 예를 들어 전역 설정에서 Ctrl+K를 사용하지 않도록 설정해 두었다가, 특정 프로젝트에서만 이 키를 커스텀 명령으로 활성화하는 방식의 세밀한 제어가 가능합니다. 이러한 작동 원리를 명확히 이해하는 것은 복잡한 프로젝트 환경에서 단축키 충돌을 최소화하고 자신만의 개발 워크플로우를 구축하는 첫걸음입니다.
Photo by Daniil Komov on Pexels
프로젝트 폴더 내 JSON 파일로 워크스페이스 단축키 격리하기
가장 확실하고 투명한 방법은 프로젝트 폴더 내에 단축키 설정 파일을 직접 생성하는 것입니다. 이 방식은 버전 관리 시스템(Git 등)을 통해 팀원들과 설정을 동기화할 수 있다는 강력한 이점이 있습니다. 프로젝트에 참여하는 모든 개발자가 동일한 단축키 환경을 사용하게 되어 "내 컴퓨터에서는 잘 되는데 당신 컴퓨터에서는 왜 안 되나요?"와 같은 불필요한 커뮤니케이션 비용을 줄일 수 있습니다. 특히 오픈 소스 기여자들이 많은 프로젝트나, 새로운 팀원이 합류하는 빈도가 높은 스타트업 환경에서는 이러한 설정 파일의 자동화가 필수적입니다. 프로젝트 루트에 .vscode 폴더를 생성하고 그 안에 keybindings.json 파일을 배치하면, VSCode는 해당 폴더를 워크스페이스로 인식할 때 즉시 이 설정을 로드합니다.
프로젝트별 단축키 설정 7단계 가이드:
- 폴더 생성: VSCode에서 프로젝트를 열고, 탐색기 익스플로러(Explorer)의 루트 경로에
.vscode라는 이름의 새 폴더를 생성합니다. 만약 이미 존재한다면 이 단계를 건너뜁니다. - 파일 생성:
.vscode폴더 내부에keybindings.json파일을 생성합니다. - 기본 구조 작성: 생성된 JSON 파일에 빈 배열
[]을 입력하고 저장합니다. 이 배열 안에 단축키 규칙을 객체 형태로 추가하게 됩니다. - 단축키 규칙 정의: 필요한 단축키 규칙을 작성합니다. 예를 들어, 이 프로젝트에서만
Ctrl+Shift+T를 터미널 토글이 아닌 테스트 실행 명령으로 변경하고 싶다면 해당 명령어와 키 조합을 JSON 객체로 정의합니다. - 문법 검증: JSON 파일의 문법이 올바른지 확인합니다. 쉼표 누락이나 따옴표 오류가 있으면 VSCode가 단축키를 로드하지 못하거나 에러를 표시할 수 있습니다.
- 적용 확인: 파일을 저장한 후 즉시 단축키를 테스트해 봅니다. 에디터를 재시작할 필요 없이 즉시 반영됩니다.
-
동영상으로 보는 VSCode 단축키 커스텀 설정
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
자주 묻는 질문
Q. 프로젝트별로 다른 단축키 설정을 적용하려면 어떻게 해야 하나요?
A. VSCode는 워크스페이스 설정 파일(settings.json)을 사용해 프로젝트마다 별도의 키바인딩을 정의할 수 있습니다. 프로젝트 루트에 .vscode 폴더를 만들고 그 안에 keybindings.json을 추가하면 해당 프로젝트에만 적용됩니다.
Q. 기본 키바인딩을 유지하면서 특정 프로젝트에만 새로운 단축키만 추가하고 싶어요.
A. keybindings.json에 "command"과 "key"만 정의하면 기존 기본 키바인딩을 그대로 두고 추가적인 단축키만 오버라이드됩니다. "when" 조건을 활용하면 특정 파일 유형이나 언어에만 적용하도록 제한할 수도 있습니다.
Q. 다른 팀원과 공유된 프로젝트에서 키바인딩을 통일하려면 어떤 방법이 있나요?
A. 프로젝트 루트의 .vscode/keybindings.json을 버전 관리 시스템에 포함시키면 팀원 모두가 동일한 단축키 설정을 자동으로 받아 사용할 수 있습니다. 단, 개인별 선호 설정이 겹치지 않도록 "when" 조건을 적절히 사용하세요.
Q. 키바인딩 파일을 직접 편집할 때 주의해야 할 점은 무엇인가요?
A. JSON 형식이므로 쉼표, 따옴표, 중괄호 등을 정확히 맞춰야 합니다. 또한 "key" 값은 OS에 맞는 형식(e.g., "Ctrl+Shift+P" vs "Cmd+Shift+P")으로 지정하고, 충돌이 발생하면 마지막에 정의된 것이 우선 적용됩니다.
함께 읽으면 좋은 글
MMebys Blog맥OS · 크롬 · 자동화 · AI 도구 가이드