파일마다 다른 포맷팅 — VSCode 자동 포맷팅 설정 완전 가이드

VSCode 자동 포맷팅 설정 방법, 코드를 저장할 때마다 들여쓰기가 엉망이 되고 파일마다 포맷팅 옵션을 다르게 적용하고 싶었지만 설정이 전체에만 적용돼서 고민하는 상황이라면 지금 바로 확인해야 합니다. 이 문제는 대부분의 개발자가 VSCode를 처음 사용할 때 겪는 혼란으로, 에디터가 기본적으로 사용자의 개인 설정을 모든 파일과 프로젝트에 전역으로 적용하려는 속성 때문에 발생합니다. 특히 협업 프로젝트에서 A 개발자는 2칸 들여쓰기를, B 개발자는 4칸 들여쓰기를 선호할 때, 이 설정이 충돌하면 코드 리뷰 과정에서 불필요한 수정 사항이 늘어나고 Git에서의 Diff(차이점) 확인조차 어려워집니다. 이 글에서는 프로젝트별로 워크스페이스를 분리하고 EditorConfig와 Prettier를 활용하여 파일 확장자마다 최적화된 VSCode 자동 포맷팅 설정 방법을 구체적으로 제시합니다. 이를 통해 개발 환경의 혼란을 줄이고 코드의 일관성과 가독성을 획기적으로 높일 수 있습니다.

함께 보면 좋은 글: CI/CD 파이프라인 안 될 때 — GitHub Act

VSCode는 사용자 설정, 원격 설정, 워크스페이스 설정 등 여러 계층의 설정을 가지고 있어, 상위 설정이 하위 설정을 덮어쓰는 구조로 작동합니다. 따라서 전역 설정을 건드리지 않고도 특정 프로젝트나 파일 유형에만 독립적인 규칙을 적용할 수 있는 격리된 환경을 구축하는 것이 핵심 해결책입니다. 단순히 '예쁘게 만들어주는 도구' 그 이상으로, 자동 포맷팅은 개발자의 생산성을 결정짓는 중요한 인프라입니다. 본문을 통해 언어별로 상충될 수 있는 포맷팅 규칙을 조화롭게 통합하는 방법을 단계별로 마스터하십시오.

1. 글로벌 설정과 워크스페이스 설정의 차이점 이해하기

VSCode의 설정 시스템은 계층적 구조를 가지고 있어 사용자가 어떤 범위에서 설정을 변경하느냐에 따라 적용 범위가 결정됩니다. 가장 상위에 있는 것은 사용자 설정(User Settings)으로, 이는 에디터를 사용하는 모든 프로젝트에 영향을 미치는 전역 설정입니다. 반면 워크스페이스 설정(Workspace Settings)은 현재 열려 있는 특정 프로젝트 폴더에만 적용되며, 동일한 옵션이 존재할 경우 사용자 설정보다 우선순위가 높습니다. 이 구조를 이해하지 못하면 내 개인 설정이 팀 프로젝트의 코드 스타일을 망치거나, 반대로 회사 설정이 내 개인 프로젝트에 강제로 적용되는 불편함을 겪게 됩니다.

파일마다 다른 포맷팅을 구현하기 위해서는 전역 설정을 최소한으로 유지하고, 필요한 경우에만 워크스페이스 설정을 덮어쓰는 방식을 취해야 합니다. 예를 들어, Python 프로젝트에서는 4칸 들여쓰기를 사용하지만, JavaScript 프로젝트에서는 2칸 들여쓰기를 사용하는 것이 일반적입니다. 만약 이를 전역 설정에서 관리하려 한다면 프로젝트를 바꿀 때마다 설정 값을 수동으로 토글해야 하는 번거로움이 발생합니다. 하지만 워크스페이스 설정을 활용하면 Python 폴더에서는 자동으로 4칸이 적용되고, JavaScript 폴더에서는 2칸이 적용되도록 완벽하게 분리할 수 있습니다.

이러한 설정 계층을 실제로 체감하는 방법은 간단합니다. VSCode 하단의 상태 바(Status Bar)에 보이는 톱니바퀴 아이콘을 클릭하거나, 단축키(Ctrl+,)를 눌러 설정 창을 연 후, 우측 상단의 '사용자', '작업 영역' 탭을 전환해보십시오. '사용자' 탭은 settings.json 파일의 기본 경로에 저장되어 모든 창에 영향을 주지만, '작업 영역' 탭은 현재 프로젝트 폴더 내의 .vscode라는 숨김 폴더에 설정 파일을 생성합니다. 즉, 워크스페이스 설정은 프로젝트 폴더를 이동하거나 Git으로 공유할 때 다른 팀원에게도 동일한 환경을 강제할 수 있는 강력한 수단이 됩니다.

Photo by anshul kumar on Pexels

2. 프로젝트 단위 설정 적용하기 (.vscode 폴더 활용)

이제 본격적으로 프로젝트 단위의 독립적인 환경을 구축해 보겠습니다. 핵심은 프로젝트의 최상위 루트 폴더에 .vscode 폴더를 생성하고 그 안에 settings.json 파일을 만드는 것입니다. 이 파일은 VSCode가 해당 폴더를 열면 자동으로 참조하는 지역 법률과 같습니다. 여기에 정의된 설정은 사용자의 전역 설정보다 우선 적용되므로, 팀 프로젝트에서 "반드시 이 규칙을 따르십시오"라고 강제하고 싶을 때 사용합니다. 이 방식은 에디터 종류에 상관없이 프로젝트 설정을 동기화할 수 있는 가장 확실한 첫 단계입니다.

.vscode/settings.json을 활용한 5단계 설정 절차는 다음과 같습니다. 첫째, 프로젝트 루트 폴더에 .vscode라는 이름의 폴더를 만듭니다(폴더 이름 앞의 점은 숨김 폴더임을 의미합니다). 둘째, 그 안에 settings.json 파일을 생성합니다. 셋째, 파일을 열고 기본적인 JSON 형식을 갖춥니다. 넷째, 프로젝트에 필요한 특정 옵션을 입력합니다. 예를 들어, 이 프로젝트에서는 저장 시 자동으로 포맷팅을 하고 싶다면 "editor.formatOnSave": true를 추가합니다. 다섯째, 파일을 저장하고 VSCode를 재시작하거나 설정 창을 닫았다 다시 열어 적용을 확인합니다.

{
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}

위 JSON 예시는 저장 시 공백을 제거하고 파일 끝에 새 줄을 추가하는 등 깔끔한 코드 관리를 위한 기본 설정입니다. 이렇게 설정된 파일을 Git에 커밋하여 팀원과 공유하면, 누가 프로젝트를 클론하더라도 동일한 에디터 환경을 즉시 갖추게 됩니다. 특히 editor.tabSize와 같은 설정은 언어마다 다를 수 있으므로, 워크스페이스 설정을 통해 JavaScript 파일에서는 2칸, HTML 파일에서는 4칸을 쓰도록 세분화할 수도 있습니다. 이는 단순히 개인의 취향을 넘어, 코드 리뷰 시 발생할 수 있는 사소한 잡음을 줄여주는 효과적인 전략입니다.

또한 워크스페이스 설정은 언어 식별자(Language ID)를 기반으로 더 정교한 제어가 가능합니다. 예를 들어, [javascript] 블록을 만들어 자바스크립트 파일에만 특정 린터(Linter)를 비활성화하거나, [python] 블록을 통해 파이썬 파일의 인터프리터 경로를 지정할 수 있습니다. 이렇게 되면 하나의 settings.json 파일 안에서도 마치 여러 개의 설정 파일이 존재하는 것처럼 파일 유형별로 촘촘한 환경 설정을 구축할 수 있습니다.

3. EditorConfig로 파일 유형별 포맷팅 규칙 정의

VSCode의 기본 설정 기능만으로도 충분히 강력하지만, 에디터에 종속되지 않고 더 근본적인 스타일(들여쓰기 스타일, 문자 인코딩, 줄 바꿈 문자 등)을 통제하려면 EditorConfig를 사용하는 것이 좋습니다. EditorConfig는 Sublime Text, Atom, Vim, Notepad++ 등 다양한 에디터에서 지원하는 표준화된 설정 파일 형식입니다. 즉, VSCode 사용자가 아니더라도 .editorconfig 파일만 프로젝트에 포함되어 있다면, 누구나 동일한 기본 포맷팅을 적용받을 수 있어 협업 효율이 극대화됩니다.

EditorConfig를 설정하는 과정은 크게 확장 프로그램 설치와 설정 파일 작성 두 단계로 나뉩니다. 첫째, VSCode의 확장 패넷에서 'EditorConfig for VS Code'를 검색하여 설치합니다. 둘째, 프로젝트 루트에 .editorconfig 파일을 생성합니다. 셋째, 파일 내에 root = true를 선언하여 상위 폴더의 설정을 무시하고 이 파일이 최상위 규칙임을 명시합니다. 넷째, [*] 와일드카드를 사용하여 모든 파일에 적용될 기본 규칙을 정의합니다. 다섯째, 특정 확장자(예: *.py, *.js)에 대해 별도의 섹션을 만들어 기본 규칙을 덮어씁니다.

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{js,jsx,html,css}]
indent_style = space
indent_size = 2

[*.py]
indent_style = space
indent_size = 4

[Makefile]
indent_style = tab

위 예시를 살펴보면, 모든 파일은 UTF-8 인코딩과 LF 줄 바꿈(Linux/Mac 표준)을 사용하도록 강제하고 있습니다. 이는 윈도우 사용자가 실수로 CRLF 줄 바꿈을 섞어 넣어 Git Diff가 꼬이는 문제를 방지해 줍니다. 또한 JavaScript와 CSS 파일은 2칸 스페이스를, Python 파일은 4칸 스페이스를 사용하도록 명확히 구분하고 있습니다. 심지어 Makefile처럼 탭(Tab) 들여쓰기가 필수적인 경우에도 대응할 수 있습니다. EditorConfig는 이처럼 복잡한 VSCode의 JSON 설정보다 훨씬 직관적이고 간결하게 문법적 기초를 다지는 데 특화되어 있습니다.

Prettier와 같은 고급 포맷