⚠️ Electron + Vite 빌드 트러블슈팅 기록 (Feat. app.asar, GitHub Push 실패)

내가 직접 삽질하며 겪은 ⚠️ 빌드 이슈들 정리

electron + vite + electron-builder 환경에서 발생했던 문제와 해결 팁들 모음입니다.

---

✅ 환경

• Electron 25.x
• Vite 4.x
• electron-builder 24.x
• 윈도우 11
• 배포 타겟: win-unpacked, NSIS

---

🧨 문제 1. 빌드 중 app.asar 삭제 실패

⨯ remove app.asar: The process cannot access the file because it is being used by another process.

💡 원인

Electron 앱이 실행된 상태에서 다시 electron:build 를 시도하면

app.asar 파일이 사용 중이라 삭제할 수 없음

✅ 해결 방법

taskkill /F /IM electron.exe

• 실행 중인 electron 프로세스 강제 종료
• 터미널, VSCode 등에서 electron이 점유된 경우도 있으니 껐다 켜기

---

🧨 문제 2. GitHub push 실패 (100MB 초과)

error: File app.asar is 113.77 MB; this exceeds GitHub's file size limit of 100.00 MB

💡 원인

release/, dist/, dist-electron/ 등의 빌드 결과물이 Git에 포함됨

GitHub의 최대 파일 용량 제한(100MB) 초과

✅ 해결 방법 (BFG로 Git 히스토리 정리)

1. BFG 다운로드: https://rtyley.github.io/bfg-repo-cleaner/
2. app.asar 삭제 실행

java -jar bfg-1.14.0.jar --delete-files app.asar --no-blob-protection

1. Git 히스토리 정리

git reflog expire --expire=now --all && git gc --prune=now --aggressive

1. 강제 푸시

git push --force --all origin

💬 BFG는 커밋 히스토리를 직접 수정하므로 주의!

팀원이 있다면 꼭 공유하고 진행해야 함

---

🧨 문제 3. Cannot find module 'dist-electron/main/main.js'

Cannot find module 'dist-electron/main/main.js'

💡 원인

• 빌드된 파일을 실수로 Git에서 삭제했거나
• 아직 빌드하지 않은 상태에서 앱을 실행했을 때

✅ 해결 방법

npm run build

또는 package.json에서 아래 항목 확인

"main": "dist-electron/main/main.js"

Electron이 시작할 엔트리 파일을 못 찾는 거니까, 해당 경로에 파일이 있는지 꼭 확인!

---

📦 Gitignore 꼭 이렇게 쓰자

bash
복사편집
/release/
/dist/
/dist-electron/

빌드 산출물은 Git에 넣지 말자!

특히 release/win-unpacked/resources/app.asar 이거 GitHub에서 안 올라감

---

🧼 빌드 클린업 스크립트 추천

"scripts": {
  "clean:release": "rimraf release dist dist-electron"
}

• 실행: npm run clean:release
• 설치: npm install -D rimraf

---

✅ 체크리스트 요약

• Electron 앱 실행 중일 때 빌드하지 않았는지?
• .gitignore에 빌드 폴더들 빠짐 없이 추가했는지?
• 커밋 전에 빌드 산출물 제외했는지?
• main 엔트리 파일 경로가 맞는지?

---

🎁 덤: GitHub 릴리즈 배포 고려 중이라면?

• .exe 파일만 GitHub Releases에 업로드 가능
• electron-updater + publish 설정하면 자동 업데이트도 가능
• 다만 용량이 너무 클 경우엔 S3나 자체 서버로 호스팅 고려

---

✍️ 마치며

처음엔 왜 오류가 나는지도 모르고 한참 헤맸는데,

이제는 구조를 조금씩 이해하게 되는 것 같아서 기록해둡니다 😌

나중에 나처럼 삽질할 누군가에게 도움이 되길 🙏