04 · Packaging & Distribution — 배포 용어

이 챕터: 빌드 도구(electron-builder, electron-forge), 패키지 포맷(asar, MSI, dmg, AppImage, MSIX), 업데이트 인프라(Squirrel, autoUpdater, Hazel), 네이티브 모듈 빌드(N-API, electron-rebuild, prebuild)의 27개 용어. 참고 챕터: 06-packaging-distribution

AppImage

Linux의 단일 실행 파일 배포 포맷. 실행하면 임시 마운트되어 그 안의 앱이 돈다.

설치 불필요, 의존성 동봉, 어떤 distro에서도 동작 가능. Linux 시장의 dmg 같은 위치. electron-builder의 linux.target: 'AppImage'로 빌드. 단점: 데스크톱 통합(아이콘·.desktop 파일)은 사용자가 수동 또는 AppImageLauncher 별도 설치.

관련: [snap], [Flatpak], [electron-builder] 참고 챕터: 06-packaging-distribution

ASAR

Electron의 읽기 전용 tar-like 아카이브. 앱 소스를 한 파일에 묶어 파일 시스템 호출 횟수를 줄인다.

app.asar 한 파일이 수만 개의 작은 JS 파일을 대체 — 첫 require가 빨라진다. 읽기 전용이므로 사용자 데이터 저장에 못 쓴다 (app.getPath('userData') 사용). asar extract app.asar app/로 추출 가능 — 난독화·암호화가 아니다, 비밀을 그대로 넣으면 끝장.

관련: [electron-builder], [Fuses (OnlyLoadAppFromAsar)] 참고 챕터: 06-packaging-distribution

autoUpdater (Electron module)

Electron의 내장 자동 업데이트 모듈. macOS/Windows에서 동작 (Linux 없음).

macOS는 Squirrel.Mac(Sparkle 변형)을 호출, Windows는 Squirrel.Windows를 호출. autoUpdater.setFeedURL({ url }) + checkForUpdates() + on('update-downloaded', ...). Linux에서 안 됨 — Snap/Flatpak/AppImage는 각자의 업데이트 메커니즘. 대안으로 [electron-updater] (electron-builder의) 많이 씀.

관련: [Squirrel], [electron-updater], [Hazel] 참고 챕터: 06-packaging-distribution

Channel (update)

stable / beta / alpha 같은 업데이트 채널 분리. 같은 앱의 다른 트랙.

[electron-updater]는 channel 필드로 자동 분리. [Hazel]/[Nuts]/GitHub Releases도 채널별 디렉터리 또는 prerelease 플래그로. 사용자는 환경 변수/설정 UI로 선택. 카나리아 출시에 핵심.

관련: [autoUpdater], [electron-updater], [Hazel] 참고 챕터: 06-packaging-distribution

dmg

macOS의 디스크 이미지 배포 포맷. 더블 클릭하면 마운트, 안의 .app을 Applications에 드래그.

사실상 macOS 사용자 앱 배포의 표준. electron-builder의 mac.target: 'dmg'. 안에 Applications 폴더 alias를 두고 사용자가 드래그하게 만드는 *“DMG dance”*가 관례. 코드 서명은 dmg 자체에도, 그 안의 .app에도 둘 다 필요.

관련: [pkg], [Code Signing], [Notarization] 참고 챕터: 06-packaging-distribution

Delta Update

전체 패키지가 아니라 바뀐 부분만 다운로드받는 업데이트 방식.

Squirrel.Windows의 nupkg가 이미 delta — 200MB 앱이 10MB만 받기도. Squirrel.Mac은 full update. 사용자 대역폭·CDN 비용에 큰 차이. 직접 인프라를 짠다면 블록 단위 해시 비교가 일반적.

관련: [Squirrel], [autoUpdater] 참고 챕터: 06-packaging-distribution

electron-builder

Electron 배포 도구의 사실상 표준. macOS/Windows/Linux + asar + 서명 + dmg/MSI/NSIS/AppImage + autoUpdate 한 패키지.

package.json의 "build": { ... } 또는 electron-builder.yml로 설정. multi-target, multi-arch (x64/arm64) 지원. CI 친화적. 단점: 설정이 방대해서 처음엔 압도적, yaml 들여다보는 시간이 코드 짜는 시간만큼.

관련: [electron-forge], [electron-updater], [asar] 참고 챕터: 06-packaging-distribution

electron-forge

OpenJS Foundation 산하의 공식 배포 도구. Webpack/Vite 템플릿, 플러그인 구조.

electron-builder와 양대 산맥. create-electron-app으로 즉시 시작 가능. 빌드 + makers (.dmg/.exe/.deb 등) + publishers (GitHub/S3/Snap) 의 3-stage 파이프라인. 2022년 v6에서 대대적 리뉴얼, 플러그인 생태계가 강점.

관련: [electron-builder], [Squirrel] 참고 챕터: 06-packaging-distribution

electron-rebuild

현재 Electron 버전의 V8 ABI에 맞춰 네이티브 모듈을 재컴파일하는 CLI.

npm install은 Node ABI용 바이너리를 받기 때문에 Electron에서는 충돌. npx electron-rebuild가 같은 모듈을 Electron ABI로 다시 빌드. 모든 [Native Module] 사용자가 거치는 의례. postinstall에 묶는 게 관례.

관련: [Native Module], [N-API], [prebuild / prebuildify] 참고 챕터: 06-packaging-distribution, 04-native-integration

electron-updater

[electron-builder]의 자체 autoUpdater 대체. Electron 내장 autoUpdater의 한계를 메운다.

Linux 지원(AppImage), 채널, staged rollout, S3/GitHub/generic feed. import { autoUpdater } from 'electron-updater'. 디폴트 선택지로 굳어 있음 — Electron 내장 autoUpdater를 직접 쓰는 새 코드는 드물다.

관련: [autoUpdater], [electron-builder], [Squirrel], [Hazel] 참고 챕터: 06-packaging-distribution

Hazel

[Vercel]이 만든 GitHub Releases를 업데이트 서버처럼 쓰게 해주는 프록시.

GitHub Releases에 zip/dmg/exe를 올리면 Hazel이 그것을 [autoUpdater]가 기대하는 형식으로 재라우팅. Node 서버 한 개, Vercel/Heroku에 배포. 작은 팀의 가장 싼 업데이트 인프라. 대안: [Nuts], 자체 S3, GitHub Releases 직접 사용 (electron-updater의 provider: 'github').

관련: [autoUpdater], [electron-updater] 참고 챕터: 06-packaging-distribution

MSI

Windows Installer의 공식 패키지 포맷. .msi. 기업 환경(Group Policy 배포)에서 사실상 필수.

NSIS보다 기업 친화적 — Active Directory를 통한 자동 배포, MSI 트랜잭션 롤백. electron-builder의 win.target: 'msi'. 단점: 다중 사용자 설치/per-user 설치 옵션이 복잡.

관련: [NSIS], [MSIX], [Squirrel] 참고 챕터: 06-packaging-distribution

MSIX

Microsoft의 현대 Windows 패키지. Microsoft Store 배포 + sideload 둘 다 가능.

MSI/Appx의 후계자. 컨테이너화된 설치 — 시스템 변경을 격리, 깔끔히 제거. Windows 10/11. 코드 서명 필수(EV 권장). electron-builder의 win.target: 'msix' (실험적). 채택률은 아직 MSI/NSIS보다 낮음.

관련: [MSI], [Code Signing] 참고 챕터: 06-packaging-distribution

N-API (Node-API)

Node.js의 ABI-안정 네이티브 모듈 인터페이스. Node 버전이 바뀌어도 재컴파일 불필요.

이전의 NAN(Node-Addon-API의 전신)은 V8 API 직접 의존 → Node 업그레이드마다 깨졌다. N-API는 그 위에 얇은 C 추상화를 깔아 ABI 안정성을 보장. Electron에서도 동일 N-API 사용 → 같은 prebuilt 바이너리를 Electron + Node가 공유 가능 (이전엔 electron-rebuild 필수였음).

관련: [Native Module], [electron-rebuild], [node-gyp] 참고 챕터: 04-native-integration, 06-packaging-distribution

Native Module

Node.js의 C/C++ 또는 Rust 등으로 작성된 확장. .node 바이너리.

SQLite, sharp(이미지), keytar(시스템 키체인), serialport 등. Electron에서 쓰려면 Electron의 V8 ABI에 맞게 빌드되어야 함 → [electron-rebuild] 또는 [prebuild]된 바이너리. 네이티브 모듈 1개가 배포 복잡도를 10배로 올리는 경우가 많다.

관련: [N-API], [electron-rebuild], [prebuild / prebuildify], [node-gyp] 참고 챕터: 04-native-integration

node-gyp

Node 네이티브 모듈 빌드 시스템. Python + C/C++ 툴체인 호출.

binding.gyp를 읽고 플랫폼별 컴파일러를 호출 (Linux gcc, macOS clang, Windows MSVC). Python 2/3·MSVC 설치·windows-build-tools 등 환경 의존이 큰 약점. 그래서 [prebuild]된 바이너리를 받는 게 일반적.

관련: [Native Module], [prebuild / prebuildify], [N-API] 참고 챕터: 04-native-integration, 06-packaging-distribution

NSIS

Nullsoft Scriptable Install System. 오래된, 가볍고 유연한 Windows installer 빌더.

electron-builder의 디폴트 Windows installer. 스크립트 언어로 동작을 거의 다 커스터마이즈 가능. MSI보다 작고 친근하지만 기업 배포에는 약함. 한국·일본 SI 환경에서는 NSIS, 글로벌 엔터프라이즈는 MSI를 선호하는 경향.

관련: [MSI], [MSIX], [electron-builder] 참고 챀터: 06-packaging-distribution

pkg (macOS Installer)

macOS의 .pkg 설치 패키지. Apple Installer.app이 처리.

dmg가 드래그 설치라면 pkg는 설치 마법사. 시스템 영역 변경(LaunchDaemon, 권한 요청)에 필수. dmg + pkg를 같이 배포하는 앱도 흔하다. Developer ID Installer 인증서로 서명.

관련: [dmg], [Developer ID] 참고 챕터: 06-packaging-distribution

prebuild / prebuildify

Native Module의 플랫폼별 바이너리를 미리 만들어 npm에 함께 올리는 도구.

prebuild(레거시)와 prebuildify(현행). 사용자는 npm install만 하면 자기 OS+arch+Node/Electron ABI에 맞는 바이너리를 받는다 — node-gyp 빌드 불필요. sharp/sqlite3가 이 방식 사용. 도전 과제: arm64/x64, glibc/musl, Electron/Node의 조합 폭발.

관련: [Native Module], [N-API], [node-gyp], [electron-rebuild] 참고 챕터: 04-native-integration, 06-packaging-distribution

Snap

Ubuntu/Canonical의 컨테이너화 패키지. Snap Store로 자동 업데이트.

AppImage가 단일 파일·DIY라면 Snap은 Store 중심·자동 업데이트. 단점은 부팅 후 첫 실행이 느리다는 평판과 Ubuntu 외 distro에서 채택률이 낮다. electron-builder의 linux.target: 'snap'.

관련: [AppImage], [Flatpak] 참고 챕터: 06-packaging-distribution

Squirrel

Electron의 공식 자동 업데이트 프레임워크. macOS용 Squirrel.Mac, Windows용 Squirrel.Windows.

Slack이 만든 Squirrel.Windows + GitHub의 Squirrel.Mac. Sparkle (macOS의 사실상 표준)을 부분적으로 차용. autoUpdater 모듈이 내부에서 호출. 단점: Squirrel.Windows는 기업 환경 (UAC, AppLocker)에서 자주 깨진다 — 그래서 [MSI]/[MSIX] 별도 빌드를 같이 가지는 앱도 많다.

관련: [autoUpdater], [Sparkle], [electron-updater] 참고 챕터: 06-packaging-distribution

Sparkle

macOS의 사실상 표준 앱 자동 업데이트 프레임워크. Objective-C/Swift.

Squirrel.Mac이 Sparkle을 변형해 만든 fork. RSS appcast 기반 (appcast.xml에 새 버전 정보 + 서명). 비 Electron macOS 앱들의 디폴트. Electron 앱은 Squirrel.Mac을 통해 간접적으로 의존.

관련: [Squirrel], [autoUpdater] 참고 챕터: 06-packaging-distribution

zip (배포 측면)

가장 단순한 macOS/Windows 배포 — 그냥 압축.

macOS는 .app을 zip으로 → 풀어서 Applications로 이동. Windows는 .exe + 파일 묶음. [autoUpdater] (Squirrel.Mac)도 zip을 받아서 갱신 — dmg가 아니라 zip이 업데이트 페이로드. macOS 앱의 Notarization은 zip에도 staple 가능.

관련: [dmg], [autoUpdater] 참고 챕터: 06-packaging-distribution

부록: 플랫폼별 패키지 포맷 매트릭스

부록: 배포 파이프라인 한눈에

더 읽기

• 06-packaging-distribution — 배포 본문
• electron-builder docs
• electron-forge docs
• Squirrel.Windows · Squirrel.Mac
• N-API spec