VS Code 설정, 사용자 설정과 워크스페이스 설정 구분

VS Code 설정을 바꿨는데 다른 프로젝트에서도 그대로 적용돼 곤란했던 적이 있다면, 사용자 설정과 워크스페이스 설정을 구분하지 않고 있는 것이다. 이 글은 두 설정이 어떻게 다르고 어느 쪽에 무엇을 넣어야 하는지, 그리고 팀과 설정을 공유할 때 실제로 겪는 문제를 다룬다. 결론부터 말하면 개인 취향은 사용자 설정에, 프로젝트 규칙은 워크스페이스 설정에 넣는 것이 기준이다.

두 설정은 적용 범위가 다르다

공식 문서의 정의가 명확하다. 사용자 설정은 "열려 있는 모든 VS Code 인스턴스에 전역으로 적용"되고, 워크스페이스 설정은 "특정 프로젝트에만 해당하며 사용자 설정을 덮어쓴다".

파일 위치도 다르다. 사용자 설정은 운영체제별로 정해진 자리에 있다.

Windows   %APPDATA%\Code\User\settings.json
macOS     $HOME/Library/Application Support/Code/User/settings.json
Linux     $HOME/.config/Code/User/settings.json

워크스페이스 설정은 프로젝트 루트의 .vscode/settings.json이다. 문서는 이 위치의 장점을 "Git 같은 버전 관리 프로젝트에서 다른 사람과 설정을 공유하기 쉽다"고 설명한다. 이게 핵심이다. 워크스페이스 설정은 커밋된다.

설정 화면에서 둘을 오가는 방법도 알아두면 좋다. Ctrl+,로 설정을 열면 위쪽에 User와 Workspace 탭이 있다. 어느 탭에서 값을 바꾸느냐에 따라 저장되는 파일이 달라진다. JSON을 직접 보고 싶으면 명령 팔레트(Ctrl+Shift+P)에서 Preferences: Open User Settings (JSON) 또는 Preferences: Open Workspace Settings (JSON)을 고른다.

우선순위는 일곱 단계이고 정책 설정이 가장 강하다

값이 여러 곳에 있으면 무엇이 이기는가. 문서가 명시한 순서는 이렇다. 뒤로 갈수록 우선한다.

1. 기본 설정
2. 사용자 설정
3. 원격 설정
4. 워크스페이스 설정
5. 워크스페이스 폴더 설정
6. 각 단계의 언어별 설정
7. 정책 설정

실무에서 헷갈리는 지점은 3번 원격 설정이다. Remote-SSH나 WSL, Dev Containers로 접속하면 원격 쪽에도 별도의 사용자 설정이 생긴다. 로컬에서 바꾼 설정이 원격 창에서 안 먹는 것 같다면 대개 이 때문이다. 원격 창에서 설정을 열면 Remote 탭이 따로 보인다.

그리고 문서가 덧붙이는 제약이 하나 있다. "모든 사용자 설정을 워크스페이스 설정으로 쓸 수 있는 것은 아니다. 예를 들어 업데이트나 보안에 관련된 애플리케이션 전역 설정은 워크스페이스 설정으로 덮어쓸 수 없다." 이건 안전장치다. 남이 만든 저장소를 열었는데 그 저장소의 .vscode/settings.json이 내 보안 설정을 꺼버리면 곤란하니까.

언어별 설정이 실제로 가장 자주 쓰인다

프로젝트 하나에 여러 언어가 섞여 있으면 포매팅 규칙을 언어마다 다르게 줘야 한다. 대괄호 표기법을 쓴다.

{
  "editor.formatOnSave": false,
  "[typescript]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[python]": {
    "editor.formatOnSave": true,
    "editor.tabSize": 4
  },
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": false
  }
}

여러 언어를 한꺼번에 지정할 수도 있다. 문서 예시는 이렇다.

{
  "[javascript][typescript]": {
    "editor.maxTokenizationLineLength": 2500
  }
}

여기서 실무적인 조언 하나. editor.formatOnSave를 전역으로 켜지 않는 편이 낫다. 포매터가 설정되지 않은 언어의 파일을 저장하는 순간 의도치 않은 변경이 들어가고, 그게 커밋에 섞이면 리뷰가 지저분해진다. 언어별로 켜는 쪽이 안전하다.

editor.tabSize를 워크스페이스 설정에 넣을지도 자주 논쟁거리다. 나는 넣는 쪽이다. 들여쓰기는 취향이 아니라 프로젝트 규칙이고, 사람마다 다르면 diff가 오염된다. 다만 .editorconfig가 이미 있다면 그쪽이 더 낫다. 에디터를 가리지 않기 때문이다.

워크스페이스 설정에 넣으면 안 되는 것

.vscode/settings.json은 커밋되므로, 넣는 순간 팀 전체에 강제된다. 여기에 무엇을 넣을지가 실제 갈등 지점이다.

넣어야 하는 것은 프로젝트의 정답이 정해진 항목이다. 들여쓰기 크기, 줄 끝 문자, 파일 인코딩, 언어별 기본 포매터, 검색에서 제외할 폴더(search.exclude), 파일 탐색기에서 숨길 산출물(files.exclude) 같은 것이다. 누가 열어도 같아야 하는 값이다.

넣으면 안 되는 것은 개인 취향이다. 테마, 폰트 크기, 미니맵 표시 여부, 커서 깜빡임, 단축키. 이걸 워크스페이스에 넣으면 그 저장소를 여는 사람의 화면이 제멋대로 바뀐다. 자기 설정으로 돌리려면 워크스페이스 설정을 고쳐야 하는데, 그건 커밋 대상이라 되돌리기도 애매하다. 남의 에디터를 함부로 바꾸는 짓이다.

애매한 것도 있다. 확장 프로그램 추천은 설정이 아니라 .vscode/extensions.json에 따로 넣는다.

{
  "recommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
}

이러면 저장소를 연 사람에게 설치를 권하는 알림이 뜬다. 강제가 아니라 권유라서 부담이 적다.

실제로 쓰는 워크스페이스 설정 한 벌

말로만 하면 감이 안 오니, 내가 새 프로젝트를 시작할 때 .vscode/settings.json에 넣는 것을 주석과 함께 옮긴다. JSON에 주석을 쓸 수 있는 이유는 VS Code가 JSONC 형식을 쓰기 때문이다.

{
  // 들여쓰기는 취향이 아니라 규칙이다. 사람마다 다르면 diff 가 오염된다
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  // 줄 끝 공백과 파일 끝 개행 — 이것만 맞춰도 불필요한 diff 가 크게 준다
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.eol": "\n",

  // 저장 시 포매팅은 언어별로만 켠다
  "editor.formatOnSave": false,
  "[typescript]": { "editor.formatOnSave": true },
  "[javascript]": { "editor.formatOnSave": true },

  // 검색 결과와 탐색기에서 산출물을 숨긴다. 검색 속도에도 도움이 된다
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.venv": true,
    "**/*.lock": true
  },
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true
  }
}

files.watcherExclude는 설명이 필요하다. VS Code는 파일 변경을 감지하려고 워크스페이스를 감시하는데, node_modules처럼 파일이 수만 개인 폴더가 있으면 이 감시가 CPU와 메모리를 잡아먹는다. 프로젝트를 열어두기만 해도 팬이 도는 경험이 있다면 이 설정을 의심해 볼 만하다.

반대로 files.exclude는 신중하게 써야 한다. 탐색기에서 아예 안 보이게 만들기 때문에, 그 파일을 찾던 사람이 "왜 없지" 하고 헤맨다. .env.example 같은 걸 실수로 숨기면 신규 입사자가 고생한다. 나는 빌드 산출물처럼 누가 봐도 필요 없는 것만 숨긴다.

설정이 안 먹힐 때 확인하는 순서

바꿨는데 적용이 안 되는 것 같을 때 확인 순서를 정해두면 시간이 절약된다.

먼저 어느 탭에서 바꿨는지 본다. 사용자 탭에서 바꿨는데 워크스페이스 설정이 같은 값을 다르게 지정하고 있으면 워크스페이스가 이긴다. 설정 검색창에 해당 항목을 치고 워크스페이스 탭으로 옮겨 보면 바로 드러난다.

다음으로 언어별 설정에 가려져 있는지 본다. 전역으로 editor.tabSize를 4로 했는데 "[python]" 블록에 2가 들어 있으면 파이썬 파일에서는 2다. 우선순위 목록에서 언어별 설정이 일반 설정보다 뒤에 있다는 것을 기억하면 된다.

그다음이 원격 여부다. 원격 창인지는 왼쪽 아래 초록색 표시로 확인한다. 원격이면 설정 화면에 Remote 탭이 따로 생긴다.

마지막은 확장이 덮어쓰는 경우다. 포매터 확장이 자기 규칙을 강제하는 일이 있다. editor.defaultFormatter를 명시적으로 지정하고, 그래도 이상하면 Format Document With... 명령으로 어떤 포매터가 붙어 있는지 확인한다.

이 네 가지로 대부분 해결된다. 그래도 안 되면 명령 팔레트의 Developer: Reload Window로 창을 다시 로드해 본다. 확장이 설정을 시작할 때만 읽는 경우가 있다.

설정 동기화는 켜되 워크스페이스 설정은 따라가지 않는다

여러 대의 컴퓨터를 쓴다면 Settings Sync를 켜는 것이 좋다. 문서 설명대로 "여러 기기의 VS Code 설치본 사이에서 설정, 단축키, 설치된 확장을 공유"한다. 계정 아이콘 메뉴에서 켠다.

주의할 점은 동기화되는 것이 사용자 설정이라는 것이다. 워크스페이스 설정은 저장소에 들어 있으니 Git이 알아서 옮긴다. 이 구분이 오히려 편하다. 개인 환경은 계정을 따라다니고, 프로젝트 규칙은 저장소를 따라다닌다.

동기화를 켤 때 한 가지만 확인하자. 회사 계정과 개인 계정을 섞어 쓰면 설정이 엉킨다. 어느 계정으로 로그인했는지는 계정 메뉴에서 볼 수 있다.

설정이 어디서 왔는지 추적하는 법

값이 이상한데 어디서 온 건지 모를 때가 있다. 설정 화면에서 해당 항목을 찾으면 왼쪽에 파란 선이 표시되고, 기본값과 다르면 톱니 아이콘에 표시가 뜬다. 더 확실한 방법은 설정 검색창에 @modified를 치는 것이다. 기본값에서 바뀐 항목만 걸러준다.

워크스페이스 탭에서 @modified를 치면 이 프로젝트가 강제하는 설정만 딱 보인다. 새 저장소를 클론했을 때 한 번 훑어보면, 그 팀이 무엇을 규칙으로 정해뒀는지 빠르게 파악할 수 있다. 나는 낯선 프로젝트를 받으면 .vscode/settings.json부터 열어본다. README보다 정직한 문서일 때가 많다.

참고 자료

• User and workspace settings — Visual Studio Code Docs — 설정 파일 위치, 우선순위 일곱 단계, 언어별 설정 문법
• Managing Extensions — Visual Studio Code Docs — .vscode/extensions.json으로 팀에 확장을 추천하는 방법
• Key Bindings for Visual Studio Code — 단축키는 설정과 별도 파일로 관리된다