책에 포함된 노트초보자도 쉽게 하는 WebXR 개발: A-Frame부터 Three.js·Babylon.js·React-XR까지 차근차근 배우는 실전 입문

13. 배포와 다음 단계: 테스트, 공개, 확장 로드맵

2026-04-29Views 44약 11분생성형 AI 활용

배포와 다음 단계: 테스트, 공개, 확장 로드맵

튜토리얼을 끝냈다고 해서 프로젝트가 끝난 것은 아닙니다. 오히려 진짜 WebXR 개발은 여기서부터 시작됩니다. 내 컴퓨터에서만 돌아가는 장면은 아직 연습작에 가깝고, 다른 사람이 링크를 열어 보고 실제 기기에서 경험할 수 있어야 비로소 하나의 작품이 됩니다.

이번 장에서는 지금까지 만든 WebXR 프로젝트를 배포 가능한 형태로 정리하고, 기기별로 점검하고, VR에서 AR과 MR로 확장해 가는 다음 공부 순서까지 한 번에 잡아보겠습니다. 마지막 장답게, "만들었다"에서 "공개하고 성장한다"로 넘어가는 다리를 놓아 보겠습니다.

배포는 기능이 아니라 완성의 순간이다

WebXR은 링크 하나로 공유할 수 있다는 점이 큰 장점입니다. 앱 스토어 심사를 기다리지 않아도 되고, QR 코드 하나만 있어도 헤드셋이나 모바일에서 바로 열 수 있습니다. 하지만 그 편리함은 아무 준비 없이 얻어지지 않습니다. 정적 파일이 올바르게 빌드되어야 하고, HTTPS 환경이어야 하며, 배포 경로에 맞게 에셋 주소도 맞아야 합니다.¹⁴

초보자가 가장 많이 하는 실수는 아주 단순합니다. npm run dev로는 잘 되는데, 막상 공개 URL에서는 모델이 안 뜨고 버튼이 먹지 않는 경우입니다. 대개 원인은 두 가지입니다. 하나는 배포 경로 설정이 틀린 것, 다른 하나는 공개 환경에서 필요한 HTTPS와 자산 경로를 제대로 챙기지 않은 것입니다.¹³⁴

좋은 소식도 있습니다. WebXR 프로젝트는 대체로 정적 사이트 형태로 배포할 수 있어서, 일반적인 프런트엔드 프로젝트처럼 GitHub Pages, Vercel, Netlify, 또는 직접 운영하는 정적 호스팅에 올릴 수 있습니다.¹²³

가장 쉬운 공개 방법: GitHub Pages로 배포하기

초보자에게 가장 추천하기 쉬운 방법은 Vite로 빌드하고 GitHub Pages로 배포하는 방식입니다. 무료로 시작하기 좋고, Git 저장소와 배포 이력이 함께 남아서 포트폴리오 관리에도 편합니다. GitHub Actions를 붙여 두면 main 브랜치에 푸시할 때마다 자동으로 다시 배포할 수도 있습니다.¹²³

1단계: 저장소를 만들고 Vite의 base 경로를 맞춘다

GitHub Pages에서 저장소 이름 기반 주소를 쓸 때는 Vite의 base 값을 저장소 이름과 맞춰야 합니다. 이 설정이 틀리면 자바스크립트, 텍스처, 모델 파일 경로가 어긋나서 404가 나기 쉽습니다.¹³

import { defineConfig } from 'vite';

export default defineConfig({
  base: '/my-webxr-app/',
  build: {
    outDir: 'dist'
  }
});

예를 들어 저장소 이름이 my-webxr-app이라면 최종 주소는 보통 https://사용자이름.github.io/my-webxr-app/ 형태가 됩니다.¹

2단계: 배포 전에 로컬에서 프로덕션 빌드를 확인한다

개발 서버가 아니라 실제 배포물 기준으로 먼저 확인해야 합니다. 가장 기본적인 흐름은 아래와 같습니다.¹³

npm install
npm run build
npm run preview

이 단계에서 꼭 확인할 것은 "XR 버튼이 보이느냐"보다 먼저 모델, 텍스처, 사운드, CSS, 라우팅이 모두 정상적으로 로드되느냐입니다. WebXR 문제처럼 보였는데 사실은 에셋 경로 문제인 경우가 생각보다 많습니다.

3단계: GitHub Actions로 자동 배포를 연결한다

GitHub Pages는 정적 파일 배포와 궁합이 좋습니다. 아래처럼 워크플로를 두면, 푸시할 때마다 의존성을 설치하고 빌드한 뒤 dist 폴더를 Pages에 올릴 수 있습니다.¹³

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

이 방식의 좋은 점은 배포 과정을 손으로 반복하지 않아도 된다는 것입니다. 버그를 고쳐 푸시하면 다시 배포되고, 언제 어떤 버전이 올라갔는지도 기록으로 남습니다.¹²⁵

4단계: GitHub Pages 설정을 켠다

저장소의 Settings → Pages로 가서 배포 소스를 GitHub Actions로 설정합니다. 그다음 main에 푸시하면 자동 배포가 시작됩니다.¹⁵

5단계: 실제 공개 URL에서 확인한다

GitHub Pages는 HTTPS를 기본으로 제공하므로 WebXR의 보안 컨텍스트 요구사항을 만족하기 좋습니다. WebXR은 보통 HTTPS 또는 localhost 같은 안전한 환경에서만 동작하므로, 단순한 HTTP 정적 서버에 올려 두고 "왜 XR이 안 켜지지?" 하고 놀라는 일이 없어집니다.¹⁴

GitHub Pages 말고도 가능한 배포 방법

GitHub Pages가 가장 쉬운 출발점이지만, 유일한 답은 아닙니다. 핵심은 dist 같은 빌드 결과물을 HTTPS 정적 호스팅에 올릴 수 있느냐입니다.²³⁵

Vercel / Netlify 같은 정적 호스팅: 연결이 빠르고 재배포가 쉽습니다. 다만 경로 설정과 정적 자산 처리 방식을 한 번은 직접 확인해야 합니다.
직접 운영하는 서버나 CDN: 자유도는 높지만 HTTPS, 캐시, 압축, 경로 설정까지 직접 챙겨야 합니다.
교육·전시용 배포 링크: 공개 URL을 QR 코드로 만들어 헤드셋이나 모바일에서 바로 열게 하면 공유가 훨씬 쉬워집니다. 특히 교실, 행사장, 체험 부스에서는 이 방식이 아주 강력합니다.¹

한 줄로 정리하면 이렇습니다. 어디에 올리든, 브라우저가 안전하게 접속하고 자산 경로를 정확히 찾을 수 있어야 한다는 점은 같습니다.

공개 전에 꼭 해볼 로컬 네트워크 테스트

바로 공개 서버에 올리기 전에, 같은 Wi-Fi 안에서 헤드셋이나 휴대폰으로 로컬 개발 서버를 열어 보는 습관을 들이면 디버깅이 훨씬 쉬워집니다. Meta의 WebXR 튜토리얼은 헤드셋에서 PC의 IP 주소와 포트를 직접 입력해 개발 서버에 접속하거나, 네트워크 제약이 있으면 ADB 포트 포워딩을 사용할 수 있다고 설명합니다.⁵

만약 로컬 HTTPS가 필요하다면 mkcert 같은 도구로 개발용 인증서를 만들어 Vite 서버에 연결하는 방법도 쓸 수 있습니다. 이렇게 하면 같은 네트워크의 헤드셋이 https://내-PC-IP:포트 주소로 접속해 실제 기기 테스트를 할 수 있습니다.⁶

이 과정이 중요한 이유는 단순합니다. 배포 버그인지, 기기 호환성 문제인지, 네트워크 문제인지를 빨리 나눌 수 있기 때문입니다. 로컬 네트워크에서는 잘 되는데 공개 URL에서만 깨지면 경로나 배포 설정을 보면 되고, 로컬에서도 헤드셋에서 안 되면 권한, 인증서, 브라우저 지원 여부를 먼저 봐야 합니다.

디바이스별 테스트 체크리스트

11장에서 "무엇을 조심해야 하는가"를 살펴봤다면, 여기서는 "공개 직전에 무엇을 확인해야 하는가"에 집중해 보겠습니다. 배포 테스트의 핵심은 하나입니다. 내 코드가 아니라 실제 사용자의 환경 기준으로 확인하는 것입니다.

데스크톱 브라우저와 에뮬레이터에서 확인할 것

데스크톱 테스트는 빠른 1차 점검용입니다. 장면 구조, 버튼 흐름, 세션 진입 조건, 기본 입력 흐름을 빠르게 볼 수 있습니다. 다만 이 단계는 어디까지나 예행연습입니다.⁵

XR 진입 버튼이 사용자 클릭 뒤에만 활성화되는가
WebXR 미지원 환경에서 안내 문구나 대체 화면이 보이는가
모델과 텍스처가 404 없이 모두 로드되는가
세션 종료 후 다시 들어가도 상태가 이상하지 않은가
콘솔에 보안, 권한, 경로 관련 에러가 남지 않는가

VR 헤드셋에서 확인할 것

실제 VR 헤드셋 테스트는 필수입니다. 브라우저 에뮬레이터는 컨트롤러 감각, 시야, 추적, 실제 몰입 상태를 대신해 주지 못합니다.⁵¹¹

헤드셋 브라우저에서 공개 URL이 바로 열리는가
Enter VR 또는 시작 버튼을 눌렀을 때 세션이 정상 진입하는가
컨트롤러 입력이 왼손과 오른손 모두에서 예상대로 작동하는가
세션을 종료한 뒤 브라우저 화면으로 자연스럽게 돌아오는가
다시 입장했을 때 이전 세션의 선택 상태나 배치 상태가 남지 않는가
텍스트 크기와 버튼 거리가 실제 헤드셋에서 읽고 누르기 편한가
같은 장면을 3분 이상 유지했을 때 갑작스러운 끊김이나 크래시가 없는가

모바일 AR 기기에서 확인할 것

AR은 VR보다 체크 포인트가 조금 더 현실적입니다. 공간 추적, 카메라 권한, 표면 인식, 조명 변화 같은 요소가 함께 들어오기 때문입니다.⁹¹⁰

카메라 권한을 거부했을 때 안내가 이해하기 쉬운가
AR 세션이 시작된 뒤 화면에 아무것도 없는 것처럼 보이지 않는가
히트 테스트가 잡히기 전까지 사용자에게 움직임 안내가 필요한가
표면을 찾은 뒤 오브젝트 배치가 지나치게 흔들리지는 않는가
탭으로 배치하는 동작이 자연스럽고 반복 배치도 잘 되는가
세로 모드와 가로 모드가 섞일 때 UI가 깨지지 않는가
실내 조명이 바뀌거나 바닥 무늬가 단순한 공간에서도 최소 동작은 유지되는가

공개 URL에서 마지막으로 확인할 것

배포가 끝났다고 바로 공유하지 말고, 공개 주소에서 마지막 검수를 한 번 더 해 보세요.

주소창이 https://로 시작하는가⁴
저장소 이름 변경 뒤 base 경로를 놓치지 않았는가¹³
서브 경로 배포에서 이미지, GLB, 오디오가 전부 정상 로드되는가¹
iframe 안에 넣었다면 필요한 권한 설정이 되어 있는가⁸
QR 코드로 접속했을 때 모바일과 헤드셋에서 주소 입력 없이 바로 열리는가¹

브라우저나 기기 자체의 문제를 분리해서 보고 싶다면, Immersive Web의 샘플 페이지와 테스트 페이지를 먼저 열어 보면서 현재 장치가 WebXR 기능을 제대로 제공하는지 확인하는 것도 좋은 방법입니다.⁷

공개는 한 번에 크게 하지 말고, 작게 시작하자

처음 배포한 WebXR 프로젝트는 완성품이라기보다 첫 공개 버전에 가깝습니다. 그래서 배포 전략도 거창할 필요가 없습니다. 오히려 작은 범위에서 시작하는 편이 좋습니다.¹¹

예를 들어 이렇게 가면 부담이 적습니다.

0.1 내부 공유: 내 PC, 내 헤드셋, 가까운 동료 기기에서 먼저 본다.
0.2 제한 공개: GitHub Pages 링크를 소수 사용자에게 보내고, 어떤 기기에서 잘 되거나 안 되는지 기록한다.
1.0 공개 배포: README, 사용 방법, 지원 기기, 알려진 제한 사항까지 적어 두고 널리 공유한다.

이 과정을 거치면 "왜 어떤 사람은 되고 어떤 사람은 안 되지?"를 막연히 고민하지 않게 됩니다. 사용자 피드백이 모이면 기기별 호환성 표도 만들 수 있고, 다음 버전 목표도 분명해집니다.

배포된 프로젝트를 포트폴리오로 바꾸는 법

좋은 WebXR 프로젝트는 링크만 있는 것이 아니라, 설명 가능한 프로젝트입니다. 채용 담당자나 협업자는 완성된 장면보다도 "이 사람이 어떤 문제를 어떻게 풀었는가"를 보고 싶어 합니다.

그래서 공개 저장소에는 최소한 다음 정도를 함께 남겨 두면 좋습니다.

프로젝트 소개 한 줄
실행 주소와 QR 코드
지원한 기기와 테스트한 브라우저 목록
주요 기능 스크린샷 또는 짧은 GIF
로컬 실행 방법과 배포 방법
아직 미지원인 기능 또는 알려진 제한 사항

이렇게 정리해 두면 프로젝트가 단순한 실습 결과물이 아니라, 공개 가능한 작업물로 보이기 시작합니다.

VR에서 AR로, AR에서 MR로 가는 학습 로드맵

이제 다음 질문이 자연스럽게 생깁니다. "그래서 다음엔 뭘 공부해야 할까?"

좋은 확장 순서는 VR 기본기 → AR 입문 → MR 감각입니다. 한 번에 모든 기능을 붙이는 것보다, 좌표계와 입력에 익숙해진 다음 현실 공간과의 결합으로 넘어가는 편이 훨씬 안정적입니다.

1단계: VR 기본기를 단단하게 만든다

먼저 VR에서 아래 세 가지가 자연스럽게 손에 익어야 합니다.

세션 시작과 종료
컨트롤러 입력과 선택
이동, UI, 장면 전환 같은 기본 흐름

이 단계가 단단해야 이후 AR과 MR에서도 중심을 잃지 않습니다. 왜냐하면 결국 WebXR의 핵심은 "기기에 맞는 세션과 입력을 다룬다"는 점이기 때문입니다.¹⁰

2단계: 한 장면을 여러 환경에서 견디게 만든다

다음에는 하나의 기능을 데스크톱 미리보기, VR 헤드셋, 모바일 브라우저에서 각각 어떻게 보이게 할지 고민해 보세요. 예를 들어 VR에서는 컨트롤러 광선으로 선택하고, 데스크톱에서는 마우스로 대체하고, 미지원 브라우저에서는 3D 미리보기 모드만 제공하는 식입니다.

이 단계에서부터 당신의 프로젝트는 "데모"보다 "제품"에 가까워집니다.

3단계: AR의 기본기부터 익힌다

AR로 넘어갈 때는 처음부터 거창하게 하지 말고, 아래 흐름 하나만 완성해도 충분합니다.

immersive-ar 세션을 시작한다.
hit-test로 표면을 찾는다.
레티클로 배치 위치를 보여 준다.
select 또는 화면 탭으로 오브젝트를 놓는다.

Google의 WebXR AR 예제도 바로 이 흐름을 중심으로 설명합니다. 즉, AR 입문은 "현실 위에 뭔가를 보여 주는 것"이 아니라 안정적으로 놓고 다시 볼 수 있게 만드는 것에서 시작합니다.⁹

4단계: AR을 더 현실답게 만든다

AR 기본 배치가 되면 그다음은 몰입감을 조금씩 높이는 단계입니다. 이때 관심을 가질 만한 기능이 앵커, 히트 테스트, 깊이 정보, 조명 추정, DOM 오버레이 같은 모듈들입니다.¹⁰

여기서 중요한 감각은 "기능이 많을수록 좋은 AR"이 아니라는 점입니다. 예를 들어 깊이 정보나 조명 추정은 분명 강력하지만, 기기 지원 차이가 있고 디버깅 비용도 큽니다. 그래서 가장 좋은 순서는 배치 안정성 → 스케일 감각 → 가림과 조명 표현입니다.

5단계: MR은 기능보다 공간적 사고방식으로 접근한다

MR은 단순히 AR보다 더 화려한 모드가 아닙니다. 사용자의 손, 시선, 실제 공간, 가상 오브젝트가 같은 장면 안에서 자연스럽게 어울려야 합니다. 그래서 MR에 가까워질수록 이런 질문을 하게 됩니다.

"이 버튼은 벽에 붙어 있어야 할까, 눈앞에 떠 있어야 할까?"

"이 오브젝트는 손으로 집는 편이 자연스러울까, 시선으로 선택하는 편이 자연스러울까?"

"현실 공간에 고정된 UI와 따라다니는 UI를 어떻게 나눌까?"

이 단계에서는 손 입력, 공간 이해, 실제 환경과의 가림 표현 같은 요소가 중요해집니다. WebXR 생태계도 손 입력, 깊이 센싱, 조명 추정, 앵커 같은 확장 모듈을 통해 이런 방향으로 발전하고 있습니다.¹⁰

6단계: 같은 기능을 다른 프레임워크로 다시 만들어 본다

실력이 빨리 느는 방법 중 하나는 "새 기능을 무한히 추가하는 것"이 아니라, 같은 기능을 다른 방식으로 다시 만들어 보는 것입니다. WebXR Showcase처럼 여러 엔진과 프레임워크로 비슷한 장면을 비교해 볼 수 있는 자료는 이런 공부에 큰 도움이 됩니다.¹²

예를 들어 작은 목표를 하나 정해 보세요. "큐브를 놓고, 선택하고, 색을 바꾼다." 이 기능을 A-Frame, Three.js, Babylon.js, React-XR 중 두 가지 이상으로 다시 만들어 보면, 당신은 단순히 API를 외운 사람이 아니라 구조를 이해한 개발자가 됩니다.

앞으로의 학습 목표는 이렇게 잡으면 좋다

마지막으로, 앞으로 1~2개월의 목표를 아주 현실적으로 잡아 보겠습니다.

첫째 주에는 지금 만든 프로젝트를 GitHub Pages에 올리고, README와 실행 링크를 정리하세요. 둘째 주에는 헤드셋 1종과 모바일 1종에서 체크리스트를 기준으로 다시 테스트해 보세요. 셋째 주에는 같은 프로젝트에 간단한 AR 배치 기능을 따로 실험해 보세요. 넷째 주에는 "지원 환경이 아닐 때 어떤 화면을 보여 줄 것인가"까지 포함해 사용자 흐름을 다듬어 보세요.

이렇게 하면 공부가 "새 기술을 계속 주워 담는 과정"이 아니라, 하나의 프로젝트를 점점 더 공개 가능한 형태로 키우는 과정이 됩니다.