다른 프로젝트를 열 때마다 단축키가 꼬여 작업 흐름이 끊기는 상황에서 VSCode 맥 단축키 완벽 설정 가이드가 절실하게 느껴지는데, 매번 키맵을 일일이 바꾸는 작업이 얼마나 막막한지 모릅니다. 이 문제는 VSCode가 기본적으로 전역 사용자 설정을 우선 적용하기 때문에, 프로젝트의 특성이나 개발 언어에 따라 요구되는 상이한 키 조합을 즉각적으로 반영하지 못해서 발생합니다. 이 글에서는 워크스페이스와 프로필, 그리고 JSON 설정 파일을 체계적으로 활용하여 환경마다 최적화된 키를 자동으로 로드하는 방법을 통해 수동 설정에 드는 시간을 획기적으로 줄이는 VSCode 맥 단축키 완벽 설정 가이드를 제시합니다.
함께 보면 좋은 글: 특정 앱마다 다른 맥북 단축키 설정하는 법 — 단계별
- 프로젝트 폴더 내 .vscode/keybindings.json을 생성하여 워크스페이스별 단축키 독립성 확보
- when 절을 사용하여 언어 모드나 파일 확장자에 따라 조건부로 단축키 동작 제어
- VSCode 프로필 기능을 활용해 전체 개발 환경 설정을 하나의 단축키로 즉시 전환
- 충돌 방지를 위한 기본 키맵 삭제 및 우선순위 명시적 설정 방법
프로젝트별 VSCode 맥 단축키를 한 번에 설정해 생산성을 3배 높이고, 초기 설정 시간을 5분 이내로 줄이며, 30개의 핵심 단축키를 자동 적용해 무료로 관리할 수 있습니다.
VSCode 맥 단축키 완벽 설정 가이드의 기본 원리 이해
VSCode의 단축키 시스템은 기본적으로 전역 사용자 설정과 워크스페이스 설정, 그리고 기본값(Default)이라는 세 가지 계층으로 구성됩니다. 대부분의 사용자는 Cmd+K 후 Cmd+S를 눌러 열리는 키보드 단축키 UI에서 변경을 하지만, 이는 기본적으로 사용자 전역 설정인 keybindings.json 파일을 수정하는 방식입니다. 이 파일은 macOS Sequoia 15.2 기준으로 ~/Library/Application Support/Code/User/keybindings.json 경로에 위치하며, 여기서 설정한 키는 에디터를 실행하는 모든 프로젝트에 동일하게 적용됩니다.
문제는 A 프로젝트에서는 Vim 모드를 사용하고 B 프로젝트에서는 VSCode 기본 단축키를 사용해야 할 때 발생합니다. 단순히 전역 설정을 바꾸면 다른 프로젝트에서 작업할 때 다시 원래대로 돌려놓아야 하는 번거로움이 생깁니다. 따라서 프로젝트별로 독립적인 설정을 적용하기 위해서는 워크스페이스 수준에서 단축키를 오버라이드(Override)하는 것이 핵심입니다. 워크스페이스 설정은 해당 프로젝트 폴더 내에 저장되기 때문에, 다른 폴더에서 작업할 때 영향을 주지 않습니다.
Apple 개발자 문서에 따르면 macOS 애플리케이션은 단축키 처리에 있어 시스템 전역 우선순위보다 애플리케이션 내부 우선순위를 따르도록 설계되어 있습니다. 이 원리를 이용하면 VSCode 내부적으로 워크스페이스 설정이 전역 설정보다 높은 우선순위를 가지게 하여, 특정 폴더에서만 다른 단축키가 작동하도록 구성할 수 있습니다. 이것이 바로 효율적인 개발을 위한 VSCode 맥 단축키 완벽 설정 가이드의 출발점입니다.
또한 단축키 설정의 깊이를 이해하려면 키바인딩(Keybinding)의 중량(Weight) 개념을 알아야 합니다. VSCode는 사용자가 정의한 키가 기본 제공 키보드 단축키보다 항상 우선시되도록 설계되었지만, 동일한 사용자 설정 파일 내에서도 여러 규칙이 충돌할 수 있습니다. 이때 when 조건절이 더 구체적인 명령어가 우선순위를 갖게 됩니다. 즉, 단순히 '이 키를 이 명령어로 매핑'하는 것을 넘어, '언제(When)' 이 키가 작동해야 하는지를 정밀하게 제어하는 것이 고급 사용자로 가는 지름길입니다.
VSCode 버전 1.95 기준으로 단축키 충돌 시 UI상에서 가장 높은 우선순위를 가진 키 조합이 굵게 표시됩니다. 만약 예상치 못한 키가 동작한다면
Cmd+K Cmd+S 창에서 해당 단축키를 검색하여 어떤 설정이 우선순위를 점령하고 있는지 확인해야 합니다.
Photo by Daniil Komov on Pexels
워크스페이스별로 단축키 자동 분리하는 설정법
가장 확실하고 간편한 방법은 프로젝트 폴더 내에 .vscode 디렉터리를 생성하고 그 안에 워크스페이스용 단축키 설정 파일을 두는 것입니다. 이 방식을 사용하면 팀원들과 Git을 통해 설정을 공유할 수 있다는 장점도 있습니다. 예를 들어, 내 로컬 M2 맥북에서만 작업하는 것이 아니라 팀 전체가 특정 단축키 세트를 사용해야 한다면 이 방법이 필수적입니다.
설정 파일 생성
프로젝트의 최상위 루트 폴더에 .vscode라는 이름의 폴더를 생성합니다. macOS Finder에서는 점(.)으로 시작하는 폴더가 숨김 폴더로 처리되므로, 터미널에서 mkdir .vscode 명령어를 사용하거나 VSCode 내부의 사이드바에서 새 폴더를 만든 뒤 이름을 직접 입력하는 것이 좋습니다. 그 후 해당 폴더 내에 keybindings.json 파일을 생성합니다.
JSON 구조 작성
파일이 생성되면 기본적으로 빈 상태입니다. 여기에 JSON 배열 형태로 단축키 규칙을 입력해야 합니다. 가장 기본적인 형태는 [{ "key": "cmd+/", "command": "editor.action.commentLine" }]와 같습니다. 이 구조는 전역 설정 파일과 동일하지만, 이 파일이 위치한 곳이 워크스페이스 내부라는 점이 결정적인 차이입니다.
단축키 재정의(Override) 확인
이제 VSCode가 해당 폴더를 워크스페이스로 인식하고 있는지 확인해야 합니다. VSCode 하단의 상태 표시줄(Status Bar)이나 사이드바 제목에 프로젝트 이름이 정확히 표시되는지 확인하세요. 만약 제대로 로드되지 않는다면 VSCode를 재시작(Cmd+Q)하고 프로젝트 폴더를 다시 열어야 합니다.
우선순위 테스트
전역 설정에서 Cmd+B를 사이드바 토글이 아닌 다른 기능(예: 빌드)으로 설정해 두었다고 가정해 봅시다. 이 상태에서 워크스페이스 keybindings.json에 Cmd+B를 사이드바 토글로 설정하는 코드를 추가하면, 해당 프로젝트에서는 사이드바 토글이 작동합니다. 이를 통해 워크스페이스 설정이 전역 설정보다 강력함을 확인할 수 있습니다.
Git 공유 및 협업
이 .vscode/keybindings.json 파일은 프로젝트 소스 코드와 함께 커밋됩니다. 즉, 팀원들이 이 프로젝트를 git clone하거나 pull 받아서 열기만 하면 별도의 설정 없이 내가 정의한 단축키 환경을 그대로 사용할 수 있습니다. 이는 '내 컴퓨터에서는 되는데 네 컴퓨터는 안 되는' 불상사를 막아주는 가장 강력한 표준화 도구입니다.
이 방법의 또 다른 장점은 프로젝트의 성격에 따라 아예 사용하는 키보드 레이아웃 자체를 바꿀 수 있다는 점입니다. 예를 들어, 레거시 프로젝트를 유지보수할 때는 숫자 키패드를 자주 쓰는 단축키로 셋팅하고, 최신 프론트엔드 프로젝트에서는 Vim 키바인딩을 기본으로 깔아두는 식의 세분화가 가능합니다. 이는 단순한 편의를 넘어 장기적인 프로젝트 관리 효율성을 극대화하는 전략이 됩니다.
-
.vscode 폴더가 .gitignore에 포함되어 있지 않은지 확인하세요.- JSON 파일 작성 시 쉼표(,)나 중괄호({}) 누락 문법 오류가 없는지 검증하세요.
- 워크스페이스 단축키가 적용되고 있는지
Cmd+K Cmd+S에서 'User'가 아닌 'Workspace' 항목에 표시되는지 확인하세요.
JSON 파일로 고급 단축키 조건 제어 마스터하기
동영상으로 보는 VSCode 맥 단축키 완벽 설정 가이드
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
단순히 키를 재정의하는 것을 넘어, 특정 상황에서만 특정 단축키가 작동하도록 만드는 것이 진정한 단축키 마스터의 경지입니다. VSCode는 JSON 설정 내에 "when" 절을 사용하여 이러한 조건부 로직을 구현할 수 있습니다. 예를 들어, 파이썬 파일을 편집할 때는 Cmd+/가 주석 처리를 하지만, 마크다운 파일을 편집할 때는 다른 기능을 수행하게 할 수 있습니다.
가장 흔하게 사용되는 조건은 editorLangId입니다. 이 조건은 현재 활성화된 에디터의 언어 모드를 감지합니다. JSON 설정 예시로 "when": "editorLangId == 'python'"을 추가하면, 해당 단축키는 파이썬 코드를 작성할 때만 활성화됩니다. 만약 모든 언어에서 적용하되 특정 언어에서만 제외하고 싶다면 editorLangId != 'javascript'와 같이 부정 연산자를 사용할 수도 있습니다.
더욱 고급진 제어를 위해서는 resourceExtname을 활용할 수 있습니다. 이는 파일 확장자를 기준으로 단축키를 제어합니다. 예를 들어 .env 파일이나 .config 파일 같은 특정 설정 파일에서만 엔터키의 동작을 변경하거나, 특정 포맷팅 단축키를 강제하려 할 때 유용합니다. "when": "resourceExtname == '.md'"와 같이 설정하면 마크다운 파일에만 특정 키맵이 적용됩니다.
또한 터미널과 에디터 사이의 전환에도 when 절은 필수적입니다. 많은 개발자들이 터미널 포커스 여부에 따라 같은 단축키를 다르게 사용하길 원합니다. 이때 "when": "terminalFocus" 조건을
함께 읽으면 좋은 글