개발 취재 노트

모바일 브라우저(웨일)에서만 안 되는데 콘솔을 볼 수가 없을 때 — ?debug=1 화면 디버그 패널

무용 연습실에서 각자 준비한 영상을 리더의 조작에 맞춰 함께 보는 영상 동기화 웹앱을 만들고 있었다. 매번 노트북 서버를 켜는 번거로움을 줄이려고 클라우드로 옮겼는데, 안드로이드 웨일에서 영상을 골라도 방 만들기·참여 버튼이 켜지지 않았다.

결론

이 사건에서는 웨일에서 별도 스크립트 fingerprint.js가 로드되지 않아 페이지 초기화가 멈췄다. 파일명을 mediacheck.js로 바꾸고 두 페이지의 참조를 수정하자 정상 동작했다. 다만 어떤 기능이나 필터가 차단했는지는 확인되지 않았다.

모바일 브라우저에서만 나는 버그를 추측으로 고치고 있다면, 멈추고 ?debug=1일 때만 화면에 뜨는 로그 패널부터 넣는다. 핵심은 네 가지다.

  1. 맨 먼저 로드되는 스크립트로 넣는다. 그래야 페이지 로드 시점에 터진 에러까지 잡힌다
  2. 첫 줄에 UA(브라우저 식별 정보)와 쓰는 API(코드에서 호출하는 기능) 지원 여부를 찍는다
  3. window.onerror(와 unhandledrejection)를 화면으로 보낸다
  4. 복사 버튼을 단다. 사용자가 로그를 그대로 붙여 넣을 수 있게

첫 시도(8월 25일)와 재시도(8월 30일) 사이에는 5일의 간격이 있었다. 5일 내내 디버깅했다는 뜻은 아니다. 재시도에서 패널을 넣자 파일 선택 전의 초기화 오류가 드러났고, 파일명을 바꾼 뒤 성공 응답을 받았다.

아래는 같은 구성을 재현한 예시 구현이다(원본 debug.js 코드가 아니다. 원본의 구성 요소는 아래 ## 해결의 ‘패널 구성’에 나열돼 있다 ).

<!-- 페이지의 첫 번째 <script>. 다른 어떤 스크립트보다 먼저 -->
<script src="/debug.js"></script>
// debug.js — ?debug=1 일 때만 켜지는 화면 로그 패널 (예시)
(function () {
  const on = new URLSearchParams(location.search).get('debug') === '1';
  const lines = [];
  let box;

  function t() { return new Date().toISOString().slice(11, 23); }
  function render() { if (box) box.textContent = lines.join('\n'); }

  window.dbg = function (...args) {
    if (!on) return;
    const msg = args.map(a => typeof a === 'string' ? a : JSON.stringify(a)).join(' ');
    lines.push(t() + '  ' + msg);
    render();
  };
  if (!on) return;

  // 1) 페이지 로드 중 에러도 잡도록 가장 먼저 등록
  window.addEventListener('error', e =>
    dbg('❌ window.error:', e.message, '@', (e.filename || '') + ':' + e.lineno + ':' + e.colno));
  window.addEventListener('unhandledrejection', e =>
    dbg('❌ unhandledrejection:', String(e.reason)));

  // 2) 환경 한 줄: 가설을 한 번에 지우는 줄
  dbg('=== debug on ===');
  dbg('UA:', navigator.userAgent);
  dbg('secureContext:', window.isSecureContext,
      '| crypto.subtle:', !!(window.crypto && crypto.subtle),
      '| Blob.arrayBuffer:', typeof Blob !== 'undefined' && 'arrayBuffer' in Blob.prototype,
      '| File.text:', typeof File !== 'undefined' && 'text' in File.prototype);

  // 3) 패널 + 복사 버튼 (body가 생긴 뒤 붙이기)
  document.addEventListener('DOMContentLoaded', () => {
    const wrap = document.createElement('div');
    wrap.style.cssText = 'position:fixed;left:0;right:0;bottom:0;max-height:40vh;overflow:auto;' +
      'background:#000c;color:#0f0;font:11px/1.4 monospace;z-index:99999;padding:6px';
    const btn = document.createElement('button');
    btn.textContent = '복사';
    btn.onclick = () => navigator.clipboard.writeText(lines.join('\n'))
      .then(() => btn.textContent = '복사됨', () => btn.textContent = '복사 실패');
    box = document.createElement('pre');
    box.style.cssText = 'margin:0;white-space:pre-wrap';
    wrap.append(btn, box);
    document.body.append(wrap);
    render();
  });
})();

그다음 의심 가는 파이프라인에 dbg()를 한 줄씩 끼운다. 이 사건에서는 파일 정보 → 길이 읽기 시작/완료 → 지문 계산 시작/완료 → 버튼 disabled 최종값 순서였다 .

chrome://inspect 원격 디버깅화면 디버그 패널 (?debug=1)
준비물PC, USB 케이블, 폰의 개발자 옵션 → USB 디버깅 없음. URL에 ?debug=1만 붙이면 됨
보이는 것콘솔·네트워크 등 진짜 DevTools 전부직접 심은 로그 + 전역 에러만
버그가 난 사람의 폰에서그 폰을 PC에 꽂아야 함링크만 보내면 됨. 로그는 복사해서 받음
이 사건에서시도하지 않음첫 로그로 원인 확정

네트워크 요청까지 봐야 하면 chrome://inspect가 낫다. "어디서 죽었는지"만 알면 되는 경우라면 패널이 훨씬 빠르다.

상황

리더가 연습방을 열고 영상을 선택하면, 참가자는 방 목록에서 같은 방에 들어가 각자 미리 받은 영상 파일을 고른다. 서버는 영상 대신 동기화 신호를 전달하고, 참가자의 재생은 리더 조작을 따른다.

같은 영상인지 확인하는 지문 계산 헬퍼는 별도 스크립트였다. 파일 선택 뒤 길이 읽기와 지문 계산을 거쳐 버튼 상태를 정하고, 뷰어는 서버에서 방 정보를 받아 영상 대조에 쓴다. 따라서 버튼이 꺼져 있다는 관찰만으로 어느 단계가 고장 났는지는 알 수 없었다.

증상

이 사건에서는 문제 기기의 콘솔 로그 없이 수정을 반복했고, 이후 모바일 디버깅 방법을 찾으면서 화면 패널을 넣었다.

원인

두 층위로 봐야 한다.

FormationFingerprint는 같은 영상인지 대조하는 지문 계산 함수를 담은 전역 객체이고, fingerprintVideo는 그 안에서 꺼내 쓰는 함수다.

버그 자체의 원인. 패널이 찍은 첫 로그는 이랬다(배포 주소는 제거했다) .

UA: Mozilla/5.0 (Linux; Android 10; K) ... Chrome/138.0.0.0 Whale/3.9.14.9 Mobile Safari/537.36
secureContext: true | crypto.subtle: true | Blob.arrayBuffer: true | File.text: true
❌ window.error: Uncaught TypeError: Cannot destructure property 'fingerprintVideo' of 'window.FormationFingerprint' as it is undefined. @ /leader?debug=1:172:13

파일을 고르기도 전, 페이지를 열자마자 에러가 났다. 별도 파일로 둔 영상 지문 헬퍼 fingerprint.js가 웨일에서만 로드되지 않았다. 그래서 인라인 스크립트가 맨 위 구조분해에서 죽었고, 그 아래의 파일 핸들러·WebSocket 연결·버튼 활성화 코드가 전부 등록되지 않았다 . 버튼이 안 켜진 것도, "방 정보를 불러오는 중"에서 멈춘 것도 이 에러 하나로 설명된다 .

파일 이름을 mediacheck.js로 바꾸자 웨일에서도 됐다 . 바꾼 것은 파일명과 참조뿐이고, 전역 이름 FormationFingerprint와 함수 이름은 그대로 뒀다 . 그래서 막힌 기준은 파일명(URL)이었다고 보는 게 자연스럽다. 다만 웨일의 어떤 기능이나 필터 목록이 막았는지는 확인하지 않았다. "추적 방지 기능이 fingerprint를 지문 추적 스크립트로 오인했다"는 설명은 에이전트의 추론이다 .

첫날 원인을 못 잡은 이유. 에러를 볼 수단이 없어서 증상만 보고 고쳤다. 5일은 계속 매달린 시간이 아니라 첫날(8월 25일) 시도와 다음 시도(8월 30일) 사이의 간격이다. 이 간격과 재시도는 기록의 날짜로 확인된다.

해결

1. 두 길 중 패널을 고른 이유

에이전트는 chrome://inspect 원격 디버깅과 앱 안 디버그 패널을 함께 제시했다. 원격 디버깅은 케이블과 설정이 필요했다. 패널은 웨일에서 설정 없이 바로 된다는 이유로 패널을 먼저 택했다 . 에이전트는 웨일도 원격 디버깅이 "대개 된다"고 했지만, 이 사건에서는 시도하지 않았으므로 여기서는 확인하지 않은 주장으로 둔다 .

2. 패널 구성

사용법 안내에 적힌 구성은 이렇다 .

debug.js는 두 페이지 모두에 첫 번째 스크립트로 넣었다 . 이 사건에서 가장 중요했던 결정이 이것이다. 실제 에러는 파일 선택 파이프라인이 아니라 페이지 로드 시점에 났다. 패널이 앱 스크립트보다 먼저 떠 있고 window.error를 듣고 있었기 때문에 잡을 수 있었다 .

3. 첫 줄이 한 일

패널 설계 단계에서 에이전트는 로그를 읽는 기준을 미리 정해 뒀다. crypto.subtle: false면 웨일이 보안 API를 막는 것, size: 0이면 파일 바이트가 넘어오지 않는 것, 이런 식이다 . 실제 첫 줄은 네 항목이 모두 true였다 . 이 값은 해당 환경·API의 존재 여부를 보여줄 뿐, 실제 호출 성공까지 보장하지는 않는다. 이 사건에서 실행 중단 지점을 알려준 결정적 증거는 바로 아래의 window.error 한 줄이었다.

4. 로그를 받은 뒤

5. 자기 프로젝트에서 점검할 순서

다음은 이 사건의 비교 방식에서 도출한 점검 제안이다. 전역 객체가 없다는 오류와 파일명 변경 후 성공을 구분해 확인한다.

  1. 패널을 먼저 로드하고 페이지를 다시 연다. 파일을 고르기 전부터 에러가 뜨는지 확인한다.
  2. 헬퍼 스크립트가 실행돼야 하는 시점 뒤, 그 객체를 사용하는 코드 바로 앞에 dbg('helper:', typeof window.FormationFingerprint)를 넣는다. 자기 앱에서는 실제 전역 이름으로 바꾼다. undefined라면 헬퍼가 준비되지 않은 상태이며, 이것만으로 네트워크 차단이라고 단정하지 않는다.
  3. 같은 페이지 경로를 정상 브라우저에서도 열어 비교한다. 스크립트 참조 경로와 실행 순서도 함께 점검한다.
  4. 파일명 영향을 의심할 근거가 남으면 내용과 전역·함수 이름을 유지한 채 파일명과 참조만 바꿔 비교한다. 새 파일이 반영됐는지, 오류와 버튼 동작이 달라졌는지 확인한다.
  5. 이름 변경으로 동작해도 특정 차단 기능의 탓으로 확정하지 않는다. 이 사건에서도 차단 주체는 미확인으로 남았다.

덤 — 같은 사건의 곁가지 교훈

취재 후기 — 버튼을 고치기 전에 첫 에러부터

박도은
연습실에서 각자 폰으로 같은 영상을 맞춰 보는 웹앱을 만들고 있잖아. 내 안드로이드에선 파일명은 뜨는데 방 만들기와 참여 버튼이 안 켜져.
정하늘
영상을 골랐다는 표시만으로 준비가 끝났다고 볼 수는 없어. 길이 읽기, 같은 영상인지 확인하는 지문 계산, 버튼 활성화 중 어디서 멈췄는지 나눠 보자.
정바다
그 길이 읽기라면 loadedmetadata, 영상 길이 같은 기본 정보가 준비됐다는 신호가 안 오는 것 아닐까? 길이 읽기를 계속 기다리면 버튼도 켜지지 않을 거야.
정하늘
그 가설대로라면 기다림을 끊었을 때 진행돼야겠네. 길이를 못 읽어도 6초 뒤 넘어가게 하고, 서버도 길이를 모르는 파일을 받도록 바꿔 확인하자.
박도은
바꾼 뒤 다시 해봤는데 여전히 참여 버튼이 꺼져 있어. 아이폰과 데스크톱은 되고, 이 폰은 ‘방 정보를 불러오는 중’에서 멈춰.
정하늘
그러면 길이 읽기 대기를 풀었다고 해결됐다는 판정은 취소야. 방 정보를 못 받는다는 관찰도 생겼으니, 파일 처리만 볼 수는 없겠어.
박도현
기다림을 제한하는 코드는 대비책이 될 수 있어도 원인의 증거는 아니야. 문제 기기에서 그대로라면 ‘고쳤다’는 말부터 거둬야 해.
정바다
그 방 정보 대기라면 WebSocket, 서버와 메시지를 주고받는 연결 통로가 문제 아닐까? 데스크톱 뷰어에서도 같은지 확인해 보자.
박도은
열어 보니 데스크톱은 연결되고 방 정보도 받아. 폰에서도 비교했는데 일반 크롬은 되고 웨일만 안 돼. 서버 전체가 멈춘 건 아니겠네.
정바다
그럼 웨일의 통신 차단 아닐까? 연결 상태를 보고 차단 설정을 바꿔 비교하면 알 수 있을 것 같은데, 아직 그 결과는 없네.
정하늘
결과가 없으니 통신 차단은 미확인으로 두자. ‘방 정보 대기’는 결과 화면일 뿐이야. 연결 코드가 시작됐는지부터 봐야 해.
박도은
그 로그는 아직 없지만, 파일 선택 창에 클라우드 미디어 안내가 떠. 동선용 JSON 파일은 골라지는데 영상은 안 되는 것도 단서 아닐까?
정바다
그 차이라면 사진·영상 전용 선택 창을 의심할 만하네. 고를 형식을 지정하는 accept 속성을 확장자만 남기거나 아예 빼서 비교해 보자.
박도은
바꿔도 안 됐어. 필터를 뺀 뒤 다음에 다시 시도했을 때도 재생 가능한 상태로 넘어가지 않아. 화면에서 실행 로그를 볼 방법은 없을까?
박도현
그 로그부터 얻자. 선택 창이 수상해도 조건을 바꿔 해결되지 않았잖아. 다음 추측보다 실제로 멈춘 지점을 보는 데 시간을 써야 해.
정하늘
로그를 얻으려면 케이블로 PC에 연결하는 원격 디버깅도 있지만, 이번엔 ?debug=1 화면 패널을 먼저 넣자. 앱보다 먼저 읽히게 해서 시작할 때 나는 에러도 잡자.
정바다
그 패널에 UA라는 브라우저 식별 정보와 API, 즉 코드가 쓰는 기능의 지원 여부도 찍자. 파일 처리 단계별 로그와 복사 버튼을 함께 두면 어디서 멈췄는지 읽을 수 있겠어.
박도은
패널을 보니 페이지를 열자마자 에러가 떠. 파일은 아직 안 골랐는데 window.FormationFingerprint가 없대. 그게 뭔데?
정바다
같은 영상인지 확인하는 지문 함수를 담는 객체야. 그게 없네. 주소가 .html 없는 /leader라서 별도 파일인 fingerprint.js를 찾는 상대경로가 어긋난 것 아닐까?
정하늘
그 경로 그대로 데스크톱에서도 열어 보자. 파일이 준비됐는지와 그 객체가 있는지 확인하면, 경로만으로 같은 문제가 나는지 비교할 수 있어.
박도은
데스크톱은 /leader로 열어도 객체가 있어. 웨일에서 본 건 파일 선택 뒤의 실패가 아니라 페이지를 열자마자 그 객체가 없다는 에러야.
정하늘
경로만의 문제라는 가설은 접자. 앞부분에서 실행이 멈춰 파일 선택 처리와 서버 연결도 시작하지 못한 거야. 두 증상이 같은 시작 오류로 설명돼.
박도현
파일을 고른 다음 멈춘 것처럼 보여도 실제 실패는 그보다 앞이었네. 진단 코드를 앱보다 먼저 읽혀야 한다는 이유가 바로 이거야.
정하늘
그 시작 오류를 풀려고 파일명을 mediacheck.js로 바꾸고 두 페이지의 참조도 바꿨어. 함수와 전역 객체 이름은 유지했고 데스크톱에서도 확인했어. 이제 웨일 결과를 보자.
박도은
이제 돼! 이름을 바꾼 뒤에는 진행할 수 있어. 다만 지금 확인한 성공만으로 웨일의 어느 차단 설정이 원인이었는지까지 알 수는 없어.
박도현
첫 에러가 있어야 고장 난 단계를 좁힐 수 있어. 콘솔을 바로 볼 수 없는 기기에서는 추측을 더하기 전에, 앱보다 먼저 실행되는 로그 패널부터 준비하자.