Vue 디버거

다크 모드

설치 검증 ​

연동을 마쳤다면, 디버거가 개발/검증 빌드에서는 동작하고 프로덕션 빌드에는 전혀 들어가지 않는지 두 방향 모두 확인해야 합니다. 이 페이지는 사람이 따라 해도 되고 AI 에이전트가 그대로 실행해도 되도록, 각 단계를 번호로 명시한 체크리스트입니다.

검증은 두 부분으로 나뉩니다. 앞 4단계는 "디버거가 켜져서 잘 보이는지"(dev), 마지막 1단계는 "프로덕션에는 새지 않았는지"(build)를 확인합니다. 디버거는 dev/검증 전용 도구이므로, 이 마지막 단계가 가장 중요합니다.

동작 체크리스트 (dev) ​

먼저 개발 서버를 띄운 상태에서 다음을 순서대로 확인하세요.

1. ⚙ FAB가 보입니다 ​

bash
npm run dev

화면 우측 하단에 **⚙ FAB(톱니 버튼)**가 떠야 합니다. 단축키 Alt+Shift+D로도 열립니다.

왜 이게 첫 단계인가

FAB가 보인다는 건 attachDebugger가 실제로 호출됐고 분기 조건이 dev에서 true라는 뜻입니다. 가장 빠른 연동 확인 신호입니다.

2. 패널이 열리고 11개 탭이 있습니다 ​

⚙ 버튼(또는 Alt+Shift+D)을 누르면 하단/사이드 패널이 열립니다. 탭 11종이 모두 보여야 합니다.

#탭#탭
1컴포넌트7콘솔
2네트워크8Router
3Pinia9브리지
4스토리지10리포트
5연쇄11정보
6에러

각 탭의 용도는 패널 레퍼런스를 참고하세요.

3. 컴포넌트 인스펙션 → 출처 칩이 보입니다 ​

컴포넌트 탭으로 가서 ⌖ 인스펙션을 켠 뒤, 화면의 요소를 탭하세요. 선택된 컴포넌트의 State 값마다 출처 칩이 보여야 합니다.

값이 비거나 출처 칩이 안 보일 때

이는 거의 항상 배포 빌드에서 __VUE_PROD_DEVTOOLS__가 꺼진 경우입니다. vite dev(로컬)에서는 기본으로 바인딩이 노출되므로 정상이어야 합니다. 트리는 보이는데 값이 다 비어 있다면 환경별 설정의 __VUE_PROD_DEVTOOLS__ 항목을 확인하세요.

4. 화면 조작 → 네트워크 탭에 기록됩니다 ​

API를 호출하는 동작을 화면에서 수행한 뒤 네트워크 탭을 보세요. 요청이 기록돼야 합니다(axios/fetch 무관).

APM 비콘이 네트워크 탭을 채운다면

사내 APM(Datadog·New Relic·Sentry·자체 텔레메트리)이 주기적으로 폴링하면 네트워크 탭이 그 요청으로 가득 찰 수 있습니다. attachDebugger의 ignoreUrls 옵션으로 해당 패턴을 제외하세요. 자세한 내용은 옵션 레퍼런스에 있습니다.

프로덕션 안전 검증 (build) ​

dev 동작만큼 중요한 것이 프로덕션 빌드에 디버거가 한 줄도 남지 않았는지 확인하는 일입니다. 디버거는 쿠키·스토리지·API 응답·브리지 호출을 그대로 노출하므로, 진짜 프로덕션 번들에 새어 들어가면 보안 사고가 됩니다.

5. 산출물에 디버거 흔적이 없습니다 ​

프로덕션 빌드를 만든 뒤, 패키지에 동봉된 누출 게이트로 산출물을 검사하세요. 디버거 마커 3종(__VUE_DEBUGGER__·vue-debugger-host·__vdbgWrapped, minify 보존)을 스캔하고 잡히면 exit 1을 냅니다(런타임 의존성 0).

bash
npm run build
npx vue-debugger-leak-check dist    # 누출 발견 시 exit 1 → 배포 차단
# → ✓ vue-debugger 누출 없음 — dist 깨끗함

bin을 못 쓰는 임시 상황의 약식은 grep -rl "__VUE_DEBUGGER__" dist 입니다. 분기 조건(import.meta.env.DEV || (import.meta.env.MODE === 'staging' && import.meta.env.VITE_DEBUGGER === 'on'))이 production에서 정적으로 false가 되면 Vite/Rollup이 동적 import() 블록을 dead-code로 통째 제거하므로, 디버거 코드가 번들에 아예 안 들어갑니다.

이 검사가 실패하면 프로덕션에 디버거가 새고 있습니다

⚠ 누출!이 나오면 디버거가 프로덕션 번들에 포함된 것입니다. 가장 흔한 원인은 분기 조건을 동적 키로 접근한 경우입니다.

ts
// ❌ 정적 치환이 안 돼 dead-code 제거에서 살아남습니다 → 프로덕션 누출
const flag = 'VITE_DEBUGGER'
if (import.meta.env[flag] === 'on') { /* ... */ }

// ✅ 정적 치환 대상 → production에서 false로 굳어 블록째 제거됩니다
if (import.meta.env.DEV || (import.meta.env.MODE === 'staging' && import.meta.env.VITE_DEBUGGER === 'on')) { /* ... */ }

반드시 import.meta.env.VITE_DEBUGGER를 직접 참조하세요.

이 검사를 CI 게이트로 고정하세요

사람의 검사는 잊혀집니다. 누출을 구조적으로 막으려면 npx vue-debugger-leak-check dist를 CI 파이프라인의 blocking(required) 스텝으로 강제하는 것이 정답입니다 — 이것이 "운영 누출 0"의 실질 보장입니다. 3층 방어(코드 패턴·CI 게이트·트립와이어)와 데이터 거버넌스 전체는 보안·누출 차단 을 보세요.

손으로 기능 확인 — 8443 라이브 데모

  • 콜스택 복원: /#/lab/callstack — 동기·await(복원 가능) vs .then·타이머·이벤트(복원 불가, 맥락 breadcrumb로 보완)를 코드+버튼으로 비교.
  • 트리 검색/접기: /#/lab/tree — 수백·깊은 컴포넌트 트리에서 검색·접기 효용 체감.
  • 그 외 디버깅 사례는 /#/case/*(경쟁 상태·유령 갱신·연쇄 등)에서 직접 재현해 보세요.

문제가 있으면 ​

증상별 흔한 원인입니다. 표에서 원인을 먼저 짚고, 해결이 깊은 경우 트러블슈팅으로 이동하세요.

증상흔한 원인확인할 것
⚙ FAB가 안 보임attachDebugger를 app.mount() 뒤에 호출, 또는 dev에서 분기가 false호출 위치와 분기 조건
Pinia/Router 패널이 비어 있음attachDebugger를 app.use(pinia/router) 앞에 호출app.use(...) 뒤에 호출하도록 순서 변경
배포 환경에서 컴포넌트 트리/값이 비어 있음배포 빌드에 __VUE_PROD_DEVTOOLS__가 꺼짐staging 빌드에 __VUE_PROD_DEVTOOLS__: 'true' 지정 (환경별 설정)
vite build가 깨짐(top-level await 오류)동적 import()를 main.ts 최상단에 직접 작성async function bootstrap()으로 감싸기 (연동)

top-level await 함정

await import('@platform/vue-debugger')를 모듈 최상단에 직접 쓰면 vite dev(esbuild)에서는 통과하지만, vite build 기본 타깃(es2020)이 top-level await를 거부해 검증계 빌드가 깨집니다. 반드시 async 함수 안에서 await 하세요. 이유와 정확한 코드는 연동에 있습니다.

더 많은 증상과 깊은 해결은 트러블슈팅을, 환경별로 무엇을 켜고 끄는지는 환경별 설정을 참고하세요.

개발/검증 환경 전용 인페이지 Vue 디버거 · 진짜 프로덕션엔 코드가 들어가지 않습니다

@platform/vue-debugger · UNLICENSED (사내 전용)