Vue 디버거

다크 모드

빠른 시작 ​

이 페이지는 이미 돌아가는 Vue 3 프로젝트에 @platform/vue-debugger를 5분 안에 붙여 보는 최단 경로입니다. 패키지 하나를 설치하고, 부트스트랩에 조건부로 몇 줄을 추가하고, 개발 서버에서 동작을 확인하는 것이 전부입니다.

깊은 설명(옵션 전체·환경별 빌드·라우터 가드)은 각 전용 페이지로 미뤄 두었으니, 여기서는 일단 화면에 ⚙ 버튼을 띄우는 데 집중합니다. 사전 점검이 필요하면 사전 준비를, 더 상세한 설치 안내는 설치를 보세요.

설치 없이 30초 만에 먼저 만져보기

내 프로젝트에 붙이기 전에 디버거가 어떤 물건인지 보고 싶다면, **🕹 실습장**을 여세요 — 설치 0줄로 브라우저에서 바로 체험할 수 있고, **가이드 투어(/#/tour)**가 전 기능을 15분에 안내합니다. 마음에 들면 아래 3단계로 내 앱에 붙이면 됩니다.

실제 앱 전체 예시를 원하시면

이 페이지는 로컬에서 띄우는 최소 경로입니다. 배포(검증계) 빌드까지 포함해 건드리는 파일 전부(vite.config·라우터·.env.staging 등)를 한 앱에 순서대로 적용한 워크스루는 **전체 예시 — 실제 앱에 포팅하기**를 보세요.

1단계 — 설치 ​

호스트 앱의 vue를 그대로 쓰도록 peerDependency로만 의존하므로, 개발 의존성(-D)으로 한 번만 설치하면 됩니다.

bash
npm install -D @platform/vue-debugger

vue는 peerDependency라 호스트 앱의 vue를 중복 설치하지 않습니다. 사내 레지스트리나 타르볼에서 받는 방법은 빌드와 배포를 참고하세요.

2단계 — 부트스트랩에 연동 ​

main.ts(또는 main.js)에서 pinia·router 등록(app.use) 뒤, app.mount() 전에 디버거를 붙입니다. 디버거는 동적 import()로 지연 로드하므로, 부트스트랩 전체를 async 함수로 감싸야 합니다.

ts
import { createApp } from 'vue'
import App from './App.vue'

async function bootstrap() {
  const app = createApp(App)
  // app.use(createPinia()) / app.use(router) ... (있다면 먼저)

  if (import.meta.env.DEV || (import.meta.env.MODE === 'staging' && import.meta.env.VITE_DEBUGGER === 'on')) {
    const { attachDebugger } = await import('@platform/vue-debugger')
    attachDebugger(app)
  }

  app.mount('#app')
}
bootstrap()

import.meta.env.DEV는 vite dev(로컬)에서만 true라 로컬은 자동으로 켜지고, MODE === 'staging' && VITE_DEBUGGER === 'on'은 검증계(vite build --mode staging) 빌드에서만 켭니다. 모두 정적으로 false인 프로덕션 빌드에서는 이 블록과 그 안의 동적 import()가 dead-code로 통째 제거되어, 디버거 코드가 번들에 아예 들어가지 않습니다.

MODE === 'staging'을 AND로 묶는 이유: 셸·CI 환경변수에 VITE_DEBUGGER=on이 남아도 production 빌드(MODE 리터럴 'production')에선 정적 false가 되어 누출을 원천 차단합니다 — 빼지 마세요. 운영 누출 차단 전체 모델은 보안·누출 차단, 환경 매트릭스는 환경별 설정을 보세요.

top-level await는 금지입니다

await import()를 main.ts 최상단에 직접 쓰지 마세요. vite dev(esbuild)에선 되지만 vite build 기본 타깃(es2020)이 top-level await를 거부해 검증계 빌드가 깨집니다. 반드시 위처럼 async function으로 감싸세요 — 함수 안의 await는 일반 await라 모든 타깃에서 안전하고, 프로덕션 dead-code 제거도 그대로 유지됩니다.

webpack / Vue CLI를 쓴다면

webpack 등 import.meta.env가 없는 환경에서는 조건을 process.env.NODE_ENV !== 'production'으로 대체하세요. 자세한 분기 매트릭스는 환경별 설정에 있습니다.

이게 전부입니다. CSS import는 필요 없습니다 — 스타일은 Shadow DOM 안에 자동 주입되어 호스트 앱 CSS와 충돌하지 않습니다.

3단계 — 실행하고 열기 ​

개발 서버를 띄우면 디버거가 호스트 앱과 격리된 채 화면에 얹힙니다.

bash
npm run dev
  1. 화면 우측 하단에 ⚙ FAB(톱니 버튼)가 보입니다.
  2. ⚙를 누르거나 단축키 **Alt+Shift+D**로 패널을 엽니다.
  3. 하단/사이드 드로어로 패널이 열리고, 탭 11종(컴포넌트·네트워크·Pinia·스토리지·연쇄·에러·콘솔·Router·브리지·리포트·정보)이 나타납니다.

모바일 WebView에서

브라우저 devtools가 없는 WebView에서도 ⚙ FAB는 화면 안에 그대로 뜹니다. 단축키가 없는 환경이라면 FAB를 탭해서 여세요.

4단계 — 동작 확인 ​

붙었는지 확인하는 가장 빠른 방법은 두 가지입니다.

컴포넌트 인스펙션 — 컴포넌트 탭에서 ⌖(인스펙션) 버튼을 켠 뒤 화면 요소를 탭하면 해당 컴포넌트가 선택되고, 값마다 출처 칩이 보입니다.

네트워크 기록 — 화면을 조작해 API를 호출하면 네트워크 탭에 요청이 기록됩니다. axios든 fetch든 상관없이 잡힙니다.

배포 빌드에서 컴포넌트 State가 비어 있나요

vite build 기반 빌드에서 트리는 보이는데 값이 전부 비거나 undefined라면, __VUE_PROD_DEVTOOLS__: 'true'가 빠진 것입니다. 로컬(vite dev)에선 필요 없습니다. 이유와 설정은 환경별 설정에서 다룹니다.

attachDebugger는 { version, open(), close(), toggle(), destroy() } 핸들을 반환합니다(비브라우저 환경에선 null). window.__VUE_DEBUGGER__로도 접근할 수 있습니다.

다음 단계 ​

최단 경로는 끝났습니다. 필요에 따라 아래로 이어 가세요.

하고 싶은 것페이지
실제 앱에 전 과정 포팅 (건드리는 파일 전부, 순서대로)전체 예시
bridges·ignoreUrls·report 등 옵션 전체옵션 레퍼런스
검증계(staging) 빌드에 디버거 포함하기환경별 설정
전역 beforeEach/beforeResolve 가드 추적라우터 가드
11개 패널이 각각 무엇을 하는지패널 레퍼런스
안 보이거나 비어 있을 때문제 해결
프로덕션에 디버거가 안 들어갔는지 확인하려면

npm run build 후 산출물을 빠르게 점검할 수 있습니다.

bash
grep -rl "__VUE_DEBUGGER__" dist/assets 2>/dev/null && echo "⚠ 누출!" || echo "✓ 프로덕션 깨끗"

CI에 거는 정식 누출 검사는 검증을 보세요.

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

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