수성컴전자방입니다. Electron으로 개발한 앱을 배포하려면 어떻게 해야 할까요? Windows PC에서 설치하기 위해 .exe 파일로 빌드해 보겠습니다. 이를 위하여 electron-builder를 사용할 것이며, NSIS 타깃으로 하겠습니다.
목차
1. electron-builder 설치
2. package.json
2.1. version(Line 3)
2.2. scripts ▶ build 추가(Line 7)
2.3. build(Line 9~39)
2.4. build ▶ appId(Line 10)
2.5. build ▶ productName(Line 11)
2.6. build ▶ win(Line 12~19)
2.7. build ▶ win ▶ target ▶ target(Line 14)
2.8. build ▶ win ▶ target ▶ arch(Line 15~18)
2.9. build ▶ win ▶ icon(Line 20)
2.10. build ▶ nsis(Line 22~35)
2.11. build ▶ nsis ▶ oneClick(Line 23)
2.12. build ▶ nsis ▶ perMachine(Line 24)
2.13. build ▶ nsis ▶ allowToChangeInstallationDirectory(Line 25)
2.14. build ▶ nsis ▶ installerLanguages(Line 26)
2.15. build ▶ nsis ▶ createDesktopShortcut(Line 27)
2.16. build ▶ nsis ▶ shortcutName(Line 28)
2.17. build ▶ nsis ▶ createStartMenuShortcut(Line 29)
2.18. build ▶ nsis ▶ menuCategory(Line 30)
2.19. build ▶ nsis ▶ installerHeader(Line 31, 헤더 이미지)
2.20. build ▶ nsis ▶ installerSidebar(Line 32, 환영 이미지)
2.21. build ▶ nsis ▶ license(Line 33)
2.22. build ▶ nsis ▶ include(Line 34, 커스텀 NSIS 스크립트)
2.23. build ▶ directories ▶ output(Line 37)
3. VS Code 관리자 권한으로 실행, Electron 빌드, 설치
4. 글 마무리
5. 참고 자료
1. electron-builder 설치
Electron 프로젝트 폴더에서 npm install --save-dev electron-builder 명령을 실행합니다.
2. package.json
아래 코드는 package.json 예제입니다.
{
"name": "electron_practice",
"version": "1.0.0",
"main": "main.js",
"scripts": {
"start": "electron .",
"build": "electron-builder"
},
"build": {
"appId": "com.sooseongcom.practice",
"productName": "Electron 연습",
"win": {
"target": [{
"target": "nsis",
"arch": [
"x64",
"ia32"
]
}],
"icon": "image/icon.ico"
},
"nsis": {
"oneClick": false,
"perMachine": true,
"allowToChangeInstallationDirectory": true,
"installerLanguages": ["en_US", "ko-KR"],
"createDesktopShortcut": true,
"shortcutName": "Electron 연습",
"createStartMenuShortcut": true,
"menuCategory": "Electron Practice",
"installerHeader": "buildResources/header.bmp",
"installerSidebar": "buildResources/welcome.bmp",
"license": "buildResources/license.txt",
"include": "buildResources/installer.nsh"
},
"directories": {
"output": "dist"
}
},
//...
}
2.1. version(Line 3)
“version”: “1.0.0”
앱의 버전을 기입합니다.
2.2. scripts ▶ build 추가(Line 7)
“build”: “electron-builder”
scripts 안에 이 코드를 작성합니다.
npm run build 명령을 실행하면 electron-builder 명령이 실행되게 합니다.
2.3. build(Line 9~39)
electron-builder로 빌드할 때의 옵션을 작성합니다.
2.4. build ▶ appId(Line 10)
“appId”: “com.sooseongcom.practice”
Java로 프로그래밍할 때 패키지 이름 짓듯이 appId를 짓습니다.
2.5. build ▶ productName(Line 11)
“productName”: “앱 이름”
2.6. build ▶ win(Line 12~19)
Windows용 앱 배포와 관련된 설정입니다.
2.7. build ▶ win ▶ target ▶ target(Line 14)
“target”: “nsis”
NSIS로 배포합니다.
2.8. build ▶ win ▶ target ▶ arch(Line 15~18)
"arch": [
"x64",
"ia32"
]
지원하는 아키텍처를 배열 형태로 작성합니다. 저처럼 x64, ia32 모두 적으면 사용자의 PC에 따라 알맞은 아키텍처로 설치됩니다.
2.9. build ▶ win ▶ icon(Line 20)
“icon”: “아이콘 파일 경로”
main.js의 createWindow 함수에서 설정하는 아이콘과는 별개의 아이콘이 필요합니다(규격도 다름). electron-builder에서 적용하는 아이콘 파일은 256x256 이상 크기의 ico 파일이어야 합니다.
2.10. build ▶ nsis(Line 22~35)
win의 target인(2.7절, 14행 참고) nsis의 설정입니다.
2.11. build ▶ nsis ▶ oneClick(Line 23)
- “oneClick”: true이면 설치 파일을 실행했을 때 설정 체크 같은 것 없이 바로 설치됩니다.(기본값)
- “oneClick”: false이면 경로 설정이 가능합니다.(예제)
2.12. build ▶ nsis ▶ perMachine(Line 24)
- “perMachine”: true이면 PC 단위로 설치됩니다.(예제)
- “perMachine”: false이면 사용자 계정 단위로 설치됩니다. 단, oneClick이 false이면 PC 단위로 설치할지 사용자 계정 단위로 설치할지 묻습니다.(기본값)
2.13. build ▶ nsis ▶ allowToChangeInstallationDirectory(Line 25)
- “allowToChangeInstallationDirectory”: true이면 설치 경로를 변경할 수 있습니다.(예제)
빌드 후 설치해 보면 이 화면이 뜹니다. - “allowToChangeInstallationDirectory”: false이면 설치 경로를 변경할 수 없습니다.(기본값)
2.14. build ▶ nsis ▶ installerLanguages(Line 26)
“installerLanguages”: [“en_US”, “ko-KR”]
설치 시 지원할 언어를 작성합니다.
https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c에서 원하는 언어의 Language tag를 찾아 작성합니다.
2.15. build ▶ nsis ▶ createDesktopShortcut(Line 27)
- “createDesktopShortcut”: true이면 바탕화면에 바로가기를 추가합니다. 단, 재설치 시 바탕화면에 바로가기를 추가하지 않습니다.(기본값, 예제)
- “createDesktopShortcut”: false이면 바탕화면에 바로가기를 추가하지 않습니다.
- “createDesktopShortcut”: “always”이면 바탕화면에 바로가기를 추가하며, 재설치 시에도 바탕화면에 바로가기를 추가합니다.
2.16. build ▶ nsis ▶ shortcutName(Line 28)
“shortcutName”: “바로가기 이름”
모든 바로가기의 이름을 설정합니다.
2.17. build ▶ nsis ▶ createStartMenuShortcut(Line 29)
- “createStartMenuShortcut”: true이면 시작 메뉴(모든 앱)에 바로가기를 추가합니다.(기본값, 예제)
- “createDesktopShortcut”: false이면 시작 메뉴(모든 앱)에 바로가기를 추가하지 않습니다.
2.18. build ▶ nsis ▶ menuCategory(Line 30)
- “menuCategory”: true이면 시작 메뉴에 프로그램 폴더를 만듭니다. 폴더 이름은 제작자 이름으로 합니다.
- “menuCategory”: false이면 시작 메뉴에 프로그램 폴더를 만들지 않습니다.(기본값)
- “menuCategory”: “폴더 이름”이면 “폴더 이름”으로 시작 메뉴에 프로그램 폴더를 만듭니다.(예제)
2.19. build ▶ nsis ▶ installerHeader(Line 31, 헤더 이미지)
“installerHeader”: “헤더 이미지 경로”
헤더 이미지는 설치 프로그램 오른쪽 상단에 떠 있는 이미지를 말합니다. 헤더 이미지의 권장 해상도는 150x57입니다. 확장명은 bmp로 해야 합니다.
저는 이렇게 만들어서 buildResources 폴더 안에 header.bmp로 저장했습니다.(물론 파일명까지 저와 똑같이 하실 필요는 없습니다.)
그러면 코드는 “installerHeader”: “buildResources/header.bmp”가 됩니다.
2.20. build ▶ nsis ▶ installerSidebar(Line 32, 환영 이미지)
“installerSidebar”: “환영 이미지 경로”
환영 이미지의 권장 해상도는 164x314입니다. 확장명은 bmp로 해야 합니다.
저는 이렇게 만들어서 buildResources 폴더 안에 welcome.bmp로 저장했습니다.
그러면 코드는 “installerSidebar”: “buildResources/welcome.bmp”가 됩니다.
적용 시 설치 완료 화면에서 환영 이미지를 보실 수 있습니다.
2.21. build ▶ nsis ▶ license(Line 33)
“license”: “라이선스 파일 경로”
사용권 계약(License Agreement) 창에 띄울 라이선스 내용의 파일 경로를 입력합니다. .txt, .rtf, .html을 지원합니다. HTML로 작성할 때 하이퍼링크를 달 경우 target=”_blank” 속성 넣는 것을 잊지 말라고 하네요.
저는 그냥 buildResources/license.txt로 했습니다.
실제 설치 시 이런 식으로 나타납니다.
2.22. build ▶ nsis ▶ include(Line 34, 커스텀 NSIS 스크립트)
“include”: “buildResources/installer.nsh”
electron-builder로 설정할 수 없는 부분을 설정하고 싶을 때 NSIS 스크립트를 직접 작성하여 include할 수 있습니다. 이때 NSIS 스크립트의 확장명은 .nsh로 합니다.
customHeader, preInit, customInit, customUnInit, customInstall, customUnInstall, customRemoveFiles, customInstallMode, customWelcomePage, customUnWelcomePage 매크로가 정의되어 있습니다.
가령, electron-builder는 기본적으로 설치 프로그램에 Welcome Page가 존재하지 않는데, 이것을 띄우려면 아래와 같이 buildResources/installer.nsh를 작성합니다.
!macro customWelcomePage
!insertMacro MUI_PAGE_WELCOME
!macroend
2.23. build ▶ directories ▶ output(Line 37)
“output”: “빌드 결과물(.exe)이 저장될 경로”
3. VS Code 관리자 권한으로 실행, Electron 빌드, 설치
3.1. electron-builder를 사용하기 위해서는 관리자 권한이 필요하므로 Visual Studio Code를 관리자 권한으로 실행합니다.
3.2. Electron 프로젝트 폴더에서 npm run build 명령을 실행합니다.
3.3. 빌드가 성공적으로 완료되면 2.23절(예제 37행)에서 설정한 output 경로(예제는 dist 폴더)에 설치 파일이 생성됩니다.
설치 과정 스크린샷은 2번 문단 중간 중간 보여드렸으므로 이번 문단에서는 건너뛰겠습니다.
설치하고 나면 바탕화면에 바로가기가 잘 생성되었고,
시작 메뉴에도 프로그램이 추가된 것을 보실 수 있습니다.
물론 프로그램 실행도 잘 됩니다.
4. 글 마무리
제 글을 읽어 주셔서 감사합니다. 다음에 만나요!
5. 참고 자료
1) Cyp. 2021. “일렉트론(Electron) 쉬운 사용법”, Cyp Software Blog. (2025. 01. 11. 방문). https://cypsw.tistory.com/entry/일렉트론Electron-쉬운-사용법
2) 콩소프트. 2023. “Electron으로 개발한 애플리케이션 배포 빌드 하기”, 콩소프트 공작소. (2025. 01. 11. 방문). https://kongsoft.tistory.com/6
3) jETA. 2022. “Electron 시작하기 - 03 - 멋지게 포장해 배포하기”, jetalog.net. (2025. 01. 11. 방문). https://jetalog.net/106
4) Hyunchul Kwak. 2018. “electron의 윈도우용 인스톨러 NSIS 설정”, 낭중일기. (2025. 01. 11. 방문). https://wanderer.work/articles/electron의-윈도우용-인스톨러-nsis-설정/
5) electron-builder. n. d. “NSIS”, electron-builder. (2025. 01. 11. 방문). https://www.electron.build/nsis
6) damabe 외 1명. 2023. “5 Appendix A: Product Behavior”, Microsoft Learn. (2025. 01. 11. 방문). https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c
7) 신·기록. 2024. “[Window] Electron Builder 실행시 cannot create symbolic link 이슈”, 문제해결집. (2025. 01. 11. 방문). https://god-logger.tistory.com/104