[Trouble Shooting] - BibleSlide 자동 업데이트 구현

BibleSlide 트러블슈팅

프로젝트 개요

사용 기술: `electron-updater`, `electron-builder`, `GitHub Releases`

 

 BibleSlide 데스크톱 애플리케이션을 배포하면서, 사용자가 매번 웹사이트를 방문하여 수동으로 다운로드하는 번거로움을 없애고자 했습니다. 앱 실행 시 자동으로 최신 버전을 감지하고 설치를 유도하는 자동 업데이트 기능을 `electron-updater`를 이용해 구현하는 것이 이번 목표였습니다.

자동 업데이트 기본 구현 과정

1. 환경 설정 및 패키지 설치

먼저, 자동 업데이트의 핵심 패키지인 `electron-updater`를 설치했습니다. 주의할 점은 이 패키지는 런타임에 실행되어야 하므로 `package.json`의 dependencies에 포함되어야 하며 devDependencies에 있으면 안 됩니다.

2. Main Process 설정 및 업데이트 로직

`electron-updater`를 초기화하고 업데이트 확인 및 설치 이벤트를 처리하는 로직을 구성했습니다. 이때, 개인 프로젝트에서는 유료 인증서(코드서명 X)를 사용하지 않기 때문에, Windows 환경에서 자동 업데이트가 정상 작동하도록 설정했습니다.

// main/index.ts (일부)
if (process.platform === 'win32') {
  (autoUpdater as WindowsUpdater).verifyUpdateCodeSignature = false;
}

그 이후, 앱이 준비되면 업데이트 확인을 시작하되, 개발 환경에서 불필요한 네트워크 요청을 피하도록 조건을 추가했습니다.

// main/index.ts (일부)
app.whenReady().then(() => {
  createWindow();
  if (app.isPackaged) { // 빌드된 프로덕션 환경에서만 실행
    autoUpdater.checkForUpdatesAndNotify();
  }
  // ...
});

업데이트 파일 다운로드가 완료되면, 사용자에게 다이얼로그를 띄워 재시작 및 설치를 요청합니다.

autoUpdater.on('update-downloaded', (info) => {
  const dialogOpts = {
    type: 'info' as const,
    buttons: ['재시작 및 설치', '나중에'],
    title: '업데이트 알림',
    message: `새로운 버전(${info.version})이 준비되었습니다.`,
    detail: '앱을 재시작하여 업데이트를 적용하시겠습니까?',
  };

  dialog.showMessageBox(dialogOpts).then((returnValue) => {
    if (returnValue.response === 0) {
      // '재시작 및 설치' 클릭 시
      autoUpdater.quitAndInstall(false, true);
    }
  });
});

3. 수동 배포 방식 채택

저작권 및 보안상 `.gitignore`에 등록된 필수 파일(`data/bible.json`) 문제 때문에 CI/CD 통한 배포 자동화는 포기하고 로컬 빌드 후 `.exe` 및 `latest.yml` 파일만 GitHub Releases에 수동으로 배포를 진행하는 방식을 유지했습니다.

트러블슈팅: 404 Not Found (파일명 불일치)

문제 발생

새 버전(v1.2.3) 배포 후 구버전(v1.2.2) 앱 실행 시, 업데이트 확인 로그는 찍혔으나 다운로드 단계에서 멈추고 팝업이 뜨지 않았습니다.

 

PowerShell을 실행하고 `& "$env:LOCALAPPDATA\Programs\bibleslide\BibleSlide.exe"` 명령어를 강제 실행하여 확인한 에러 로그를 확인했습니다.

Error: Cannot download "https://.../bibleslide-Setup-1.2.3.exe", status 404

원인 분석

`electron-updater`는 서버(GitHub Releases)에 직접 접근하는 것이 아니라, `electron-builder`가 생성한 `latest.yml` 파일을 먼저 읽고 그 안에 명시된 경로를 따라 파일을 요청합니다. 현재 발생한 문제 원인은 다음과 같습니다.

• latest.yml에 명시된 파일명: bibleslide-Setup-1.2.3.exe (하이픈 -)
• GitHub Releases에 수동 업로드한 파일명: bibleslide.Setup.1.2.3.exe (점 .)

결국, latest.yml에 명시된 파일명과 Github Release에 수동으로 업로드한 파일명이 달라 발생한 문제였습니다.

문제 해결

먼저 GitHub Releases에서 잘못된 이름의 파일 삭제하고 로컬 빌드 결과물의 파일명을 `latest.yml`에 맞춰 정확히 bibleslide-Setup-1.2.3.exe로 수정하여 재업로드했습니다. 

Found version 1.2.3
Downloading update...
Update installer has already been triggered. Quitting application.

그 이후, 정상적인 업데이트 다운로드 및 설치 유도를 확인하고, 앱 재시작 후 v1.2.3 버전으로 성공적으로 업데이트되었습니다.