🧹빌드 전에 꼭 필요한 대청소 - 캐시(Cache)를 치우자~

송연지·2025년 8월 13일

electron 트러블슈팅

트러블슈팅

목록 보기

31/32

Electron + Vite로 개발하면서 VM 환경에서 패키징을 하다 보면,

“같은 코드, 같은 설정인데 엔진이 안 열린다”는 이상한 상황을 겪는 경우가 있습니다.

처음에는 단순한 VM(가상머신) 속도 문제겠거니 하고 넘어갔지만,

문제는 하루이틀이 아니라 빌드할 때마다 가끔 꼭 나타난다는 점이었죠.

더 이상한 건, 아무것도 바꾸지 않고 다시 빌드하면 또 잘 된다는 것이었습니다.

이쯤 되면 운이 좋은 건지, 빌드가 장난을 치는 건지 알 수 없었습니다.

💡 빌드 산출물과 캐시의 숨겨진 함정

빌드를 하면 dist/, release/, build/ 같은 폴더에 실행 파일과 번들된 JS가 생성됩니다.

이게 바로 빌드 산출물입니다.

문제는 이 폴더에 남아 있는 예전 파일이 다음 빌드에 그대로 섞여 들어갈 수 있다는 점입니다.

여기에 캐시(Cache)까지 더해집니다.

Vite, Webpack, Next.js 등 빌드 도구들은 빌드를 빠르게 하기 위해 캐시를 사용합니다.

변경이 없는 파일은 다시 처리하지 않고 재활용하죠.

하지만 가끔 변경 감지를 놓치면, 오래된 결과물이 그대로 살아남아 버립니다.

캐시는 빌드 속도를 높이는 ‘부스터’이지만, 잘못 쓰이면 발목을 잡는 ‘지뢰’가 되기도 합니다.

🗂 빌드 도구별로 지워야 할 폴더

프로젝트마다 지워야 할 폴더가 다릅니다.

아래 표는 대표적인 빌드 환경에서 청소해야 할 캐시와 빌드 산출물 폴더입니다.

빌드/프레임워크	캐시 폴더	빌드 산출물 폴더
Vite	`.vite`	`dist/`
Webpack	`.webpack-cache`	`dist/`
Next.js	`.next`	`.next`
CRA	`node_modules/.cache`	`build/`
Electron	없음(기본)	`dist/`, `release/`
Node.js	`node_modules/.cache`	없음

🧹 클린 빌드의 발견

이때부터 “클린 빌드(Clean Build)”라는 개념을 깊이 들여다봤습니다.

클린 빌드는 이전 빌드 산출물과 캐시를 완전히 지우고, 깨끗한 상태에서 새로 빌드하는 과정입니다.

문제의 근본 원인은 단순했습니다.

이전 빌드의 잔여 파일과 캐시가 새 빌드에 섞여 들어가면서

파일 누락, 변경 미반영 같은 기이한 현상을 만든 것이었습니다.

🛠 클린 빌드 실행 방법

수동 삭제

# macOS / Linux
rm -rf dist release out build .vite .webpack-cache node_modules/.cache

# Windows PowerShell
rd /s /q dist release out build .vite .webpack-cache node_modules\.cache

npm 스크립트 자동화

"scripts": {
  "clean": "rimraf dist release out build .vite .webpack-cache node_modules/.cache",
  "build": "npm run clean && electron-builder"
}

rimraf 설치:
npm i rimraf --save-dev

📦 Electron + 엔진 exe 포함 시 주의할 점

Electron 앱에서 엔진 실행 파일을 같이 배포하려면,

electron-builder의 extraResources에 정확한 경로를 지정해야 합니다.


"build": {
  "asar": true,
  "asarUnpack": [],
  "extraResources": [
    { "from": "electron/engine/bin/seph_engine.exe", "to": "public/seph_engine.exe" }
  ],
  "files": [
    "dist/**",
    "electron/**",
    "!**/*.map"
  ]
}

경로를 명확히 해주면 패키징 시 엔진 파일 누락을 방지할 수 있습니다.

🔄 CI/CD 환경에서의 클린 빌드

GitHub Actions, Jenkins, GitLab CI 같은 CI/CD 서버는 매번 깨끗한 환경에서 빌드하지만,

빌드 속도를 높이려고 캐시를 켜면 이 문제가 다시 생길 수 있습니다.

GitHub Actions 예시


steps:
  - name: Clean build
    run: rm -rf dist release .vite .webpack-cache node_modules/.cache
  - name: Install dependencies
    run: npm ci
  - name: Build
    run: npm run build

⚠️ VM 환경에서 자주 발생하는 변수

I/O 속도 지연 → 파일 복사나 압축이 중간에 누락될 수 있음
스냅샷 복원 → 예전 빌드 결과물이 그대로 복귀
시간 동기화 문제 → 설치기가 파일 변경을 인식 못 함
백신 간섭 → 실행 파일을 격리 또는 삭제

🛡 엔진 실행 전 점검 코드


import fs from 'fs';
import path from 'path';
import { spawn } from 'child_process';

const enginePath = path.join(process.resourcesPath, 'app.asar.unpacked', 'public', 'seph_engine.exe');

function fileExists(p: string) {
  try { return fs.existsSync(p); } catch { return false; }
}

export function startEngine() {
  if (!fileExists(enginePath)) {
    throw new Error(`[Engine Missing] ${enginePath}`);
  }

  const proc = spawn(enginePath, [], { detached: true });
  proc.on('error', (err) => {
    console.error('[Engine Spawn Error]', err);
  });
}