린트 설정은 맞는데 왜 안 되지? VSCode 설정 레이어 이해하기

린트 설정은 맞는데 왜 안 되지? VSCode 설정 레이어 이해하기

2026년 2월 12일

biome.json도 작성했고, 익스텐션도 깔았습니다.
근데 저장해도 포맷이 안 되고, CLI에서 biome check는 잘 되는 상황을 마주했습니다.

알고보니 규칙 파일을 고치는 게 답이 아니었습니다.
린트 도구의 설정과 VSCode가 그 도구를 실행하는 설정은 완전히 다른 레이어였습니다.

1. 문제 상황

린트 도구 설정까지는 끝났다. CLI에서는 잘 동작한다. 그런데 VSCode에서 이 중 하나 이상이 안 된다.

  • 저장해도 자동 포맷이 적용되지 않는다
  • eslint --fix나 biome check --write는 되는데, 저장 시 자동 수정만 안 된다
  • 빨간 줄(에러 표시)이 뜨지 않는다
  • 내 환경에서는 되는데 팀원 환경에서는 안 된다

2. 내가 처음 한 생각

CLI에서는 되니까 설정 파일 자체의 문제는 아닐 거라고 생각했다.
그래서 VSCode 설정을 건드리기 시작했다.

Cmd+,를 열어서 Format On Save를 켜봤다. 여전히 안 됐다.
Default Formatter를 바꿔봤다. 됐다가 안 됐다가 했다.

원인을 정확히 모른 채 설정을 바꾸니까, 왜 됐는지도 모른 채 넘어가게 됐다.
다음 프로젝트에서 또 같은 문제를 반복했다.

3. 핵심: 두 개의 분리된 레이어

린트가 VSCode에서 동작하려면 두 개의 레이어가 모두 올바르게 설정돼야 한다.

[린트 도구 레이어] biome.json / .eslintrc → "어떤 게 오류인가"를 정의
[VSCode 레이어] settings.json / 익스텐션 → "언제, 어떻게 도구를 실행할 것인가"를 정의

CLI에서는 되는데 VSCode에서 안 된다면, 문제는 항상 VSCode 레이어에 있다.
VSCode가 린트 도구를 실행할 방법을 모르거나, 잘못된 도구를 바라보고 있는 것이다.

4. VSCode 설정의 세 가지 범위

VSCode 레이어 안에서도 설정이 세 곳에 나뉜다. 우선순위가 있다.

전역 Settings UI / settings.json → 내 컴퓨터 모든 프로젝트에 적용, Git 공유 안 됨
.vscode/settings.json → 이 프로젝트에만 적용, Git 공유됨 ← 프로젝트 설정이 우선
.vscode/extensions.json → 익스텐션 추천 (설정 아님)

이 우선순위를 모르면 “분명히 전역에서 설정했는데 왜 안 되지”라는 상황이 생긴다.
.vscode/settings.json이 전역 설정을 조용히 덮어쓰고 있기 때문이다.

전역 설정: Settings UI와 settings.json

Cmd+, (Mac) / Ctrl+, (Windows)로 열리는 Settings UI와, Cmd+Shift+P → Preferences: Open User Settings (JSON)으로 열리는 JSON 파일은 같은 파일을 보는 두 가지 방법이다.

// 전역 settings.json — 내 컴퓨터 전체에 적용, Git에 올라가지 않음
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

editor.defaultFormatter는 저장 시 어떤 도구로 포맷할지 결정한다.
이 값이 없으면 Format On Save가 켜져 있어도 포맷터가 실행되지 않는다.

익스텐션 ID를 정확하게 써야 한다. Biome은 biomejs.biome, Prettier는 esbenp.prettier-vscode다.
설치된 익스텐션 이름이 아니라 익스텐션 ID가 들어가야 한다.

.vscode/settings.json — 프로젝트 전용 설정

전역 설정을 프로젝트 단위로 덮어쓰는 파일이다. Git에 커밋하면 팀 전체가 같은 환경을 갖게 된다.

// .vscode/settings.json — 이 프로젝트에만 적용, Git 공유
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

editor.codeActionsOnSave는 formatOnSave와 다르다.
formatOnSave는 포맷터를 실행하는 것이고, codeActionsOnSave는 린트 자동 수정(fixAll)과 import 정렬(organizeImports)을 실행한다.
”저장해도 --fix가 안 된다”는 문제는 대부분 codeActionsOnSave가 빠진 경우다.

ESLint를 쓴다면 키가 달라진다.

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

.vscode/extensions.json — 익스텐션 추천

설정 파일이 아니라 추천 파일이다. 프로젝트를 열면 VSCode가 설치를 권유하는 팝업을 띄워준다.

{
  "recommendations": ["biomejs.biome"]
}

이 파일이 없으면 팀원이 익스텐션을 안 깔아도 VSCode가 알려주지 않는다.
”내 컴퓨터에서는 되는데 팀원 컴퓨터에서는 안 된다”는 상황의 절반은 익스텐션 미설치다.

5. 상황별 원인과 해결

CLI에서는 되는데 VSCode 저장 시 자동 수정이 안 된다

린트 도구 레이어는 정상이고 VSCode 레이어가 문제다. 순서대로 확인한다.

1단계 — 익스텐션 확인
Biome이라면 biomejs.biome, ESLint라면 dbaeumer.vscode-eslint가 설치돼 있어야 한다.
VSCode 좌측 익스텐션 탭에서 이름으로 검색해 활성화 상태를 확인한다.

2단계 — editor.defaultFormatter 확인
Cmd+Shift+P → Preferences: Open User Settings (JSON)을 열어 확인한다.
값이 없거나 다른 포맷터 ID가 들어가 있으면 해당 도구가 실행되지 않는다.

3단계 — 프로젝트 설정이 전역을 덮어쓰고 있는지 확인
.vscode/settings.json에 "editor.defaultFormatter"가 다른 값으로 설정돼 있으면 그쪽이 이긴다.
전역에서 Biome으로 설정해놔도 프로젝트에서 Prettier로 덮어쓰고 있다면 Prettier가 실행된다.

4단계 — codeActionsOnSave 확인
포맷(formatOnSave)과 자동 수정(fixAll)은 별개다.
fixAll.biome 또는 fixAll.eslint가 .vscode/settings.json에 있는지 확인한다.

빨간 줄이 안 뜬다

익스텐션이 실행은 되지만 오류를 못 읽는 경우다.
VSCode 하단 상태바에서 Biome 또는 ESLint 아이콘을 클릭하면 출력 패널에 로그가 뜬다.

자주 나오는 로그와 원인이다.

  • Cannot find module 'eslint' → 로컬에 패키지가 설치되지 않은 것. npm install을 먼저 실행한다.
  • No config file found → 설정 파일 경로 문제. 모노레포 구조에서 루트가 아닌 서브패키지에서 실행되는 경우 발생한다.
  • Biome not found → 로컬 설치 없이 전역 명령어만 있는 경우. npm install --save-dev @biomejs/biome로 로컬에 설치한다.

특정 파일에서만 포맷이 안 된다

린트 도구 레이어의 ignore 설정을 확인한다.

// biome.json
{
  "files": {
    "ignore": ["dist/**", "node_modules/**", "*.generated.ts"]
  }
}

의도치 않게 패턴이 넓게 잡혀 있어서 정상 파일까지 ignore되는 경우가 있다.
ESLint라면 .eslintignore 파일을, Prettier라면 .prettierignore를 확인한다.

언어별로 포맷터를 다르게 지정하는 경우에는 settings.json에서 언어별 설정이 충돌하는지도 본다.

{
  "editor.defaultFormatter": "biomejs.biome",
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

팀원 컴퓨터에서는 동작이 다르다

원인은 두 곳이다.

첫째, .vscode/settings.json이 Git에 없는 경우다.
.gitignore에 .vscode/가 통째로 들어가 있으면 프로젝트 설정이 공유되지 않는다.

cat .gitignore | grep vscode
# .vscode 또는 .vscode/ 가 있으면 settings.json도 무시된다

.vscode/settings.json과 .vscode/extensions.json은 팀 공유 대상이다.
개인 설정인 .vscode/launch.json, .vscode/tasks.json은 선택적으로 공유하면 된다.

둘째, 익스텐션 미설치다. .vscode/extensions.json을 커밋해두면 팀원이 프로젝트를 열 때 자동으로 설치 권유 팝업이 뜬다.

6. 결과: 레이어별로 역할 정리

[내 컴퓨터 전역, Git 공유 안 됨]
  VSCode Settings UI = 전역 settings.json
  → "기본적으로 이 포맷터, 이 설정을 써라"

      ↓ 프로젝트 설정이 덮어씀

[프로젝트, Git 공유됨]
  .vscode/settings.json
  → "이 프로젝트에서는 이 포맷터, 이 자동 수정을 써라"
  .vscode/extensions.json
  → "이 도구들을 설치해라"

      ↓ 도구를 실행

[린트 도구]
  biome.json / .eslintrc / .prettierrc
  → "이 코드는 오류다, 이렇게 포맷해라"

에러가 생기면 이 흐름을 위에서부터 따라가면 된다.
CLI에서는 동작한다면 린트 도구 레이어는 제외하고, VSCode 레이어만 확인하면 된다.

7. 지금 다시 한다면

새 프로젝트를 시작할 때 린트 설정 파일보다 .vscode/ 파일들을 먼저 만든다.

.vscode/
  settings.json     ← defaultFormatter, formatOnSave, codeActionsOnSave
  extensions.json   ← 필요한 익스텐션 ID 목록

그리고 .gitignore에서 이 파일들이 제외되지 않았는지 바로 확인한다.

린트 규칙 설정과 “VSCode가 그 규칙을 실행하는 설정”이 다른 파일이라는 걸 처음부터 알았다면,
같은 문제를 프로젝트마다 반복하지 않았을 것이다.

비고