[Electron 데스크톱 앱 개발] #7: 앱 이름 / 아이콘 / 기본 정보 설정

 

이번에는 실제로 다른 사람에게 앱을 전달했을 때 보이는 앱의 이름과 아이콘, 기본 정보​를 정리해 보겠습니다.

 

✔️ 1. 현재 앱 이름 확인하기

먼저 현재 프로젝트의 package.json을 확인해 보겠습니다.

{
  "name": "electron-app",
  "version": "1.0.0"
}

여기서 현재 앱의 기본적인 정보가 설정되어 있습니다.

현재 프로젝트에서는 name이 electron-app으로 되어 있기 때문에 npm run make를 실행하면 설치 파일도 다음과 같이 생성됩니다.

electron-app-1.0.0 Setup.exe

여기서 각각의 의미는 다음과 같습니다.

항목	의미
electron-app	앱의 패키지 이름
1.0.0	앱 버전
Setup.exe	Windows 설치 프로그램

즉, 현재는 프로젝트를 처음 만들었을 때 사용했던 electron-app이라는 이름이 그대로 사용되고 있는 상태입니다.

---

✔️ 2. name과 productName의 차이

Electron 앱의 이름을 변경할 때 한 가지 알아두어야 할 것이 있습니다.

package.json의 name과 productName은 같은 역할을 하지 않습니다.

`name`

name은 앱의 패키지 및 프로젝트 식별에 사용되는 이름입니다.

예를 들어 다음과 같이 작성할 수 있습니다.

"name": "huni-roulette"

공백이나 일부 특수문자를 사용하는 사용자 표시용 이름보다는 패키지 이름에 적합한 형태로 작성하는 것이 좋습니다.

`productName`

반면 productName은 사용자에게 보여주는 실제 프로그램 이름을 지정할 때 사용할 수 있습니다.

예를 들어:

"productName": "Huni Roulette"

라고 설정하면 사용자가 보는 프로그램 이름을 Huni Roulette로 지정할 수 있습니다.

따라서 두 값을 다음과 같이 구분해서 사용할 수 있습니다.

{
  "name": "huni-roulette",
  "productName": "Huni Roulette",
  "version": "1.0.0"
}

정리하면,

name은 프로그램을 구분하기 위한 패키지 이름이고,
productName은 사용자가 보는 프로그램 이름이라고 생각하면 이해하기 쉽습니다.

---

✔️ 3. 앱 이름 변경하기

그렇다면 현재 electron-app이라는 이름을 실제 앱 이름으로 변경해 보겠습니다.

저는 이번에 만들고 있는 룰렛 앱의 이름을 Huni Roulette로 정했습니다.

`package.json`을 다음과 같이 수정합니다.

{
  "name": "huni-roulette",
  "productName": "Huni Roulette",
  "version": "1.0.0"
}

여기서 주의할 점은 두 이름을 똑같이 작성할 필요는 없다는 것입니다.

name
→ huni-roulette

productName
→ Huni Roulette

이렇게 사용할 수 있습니다.

---

✔️ 4. 설치 파일 이름도 변경되는지 확인

이제 변경된 내용을 적용한 뒤 다시 설치 파일을 만들어 보겠습니다.

Electron Forge를 사용하고 있기 때문에 다음 명령어를 실행합니다.

npm run make

빌드가 완료되면 out/make 폴더에 설치 파일이 생성됩니다.

기존에는:

electron-app-1.0.0 Setup.exe

였다면, 이제 다음과 같이 변경되는 것을 확인할 수 있습니다.

Huni Roulette-1.0.0 Setup.exe

즉, productName을 설정하면 사용자가 확인하는 설치 프로그램 이름도 앱의 이름에 맞게 변경할 수 있습니다.

---

✔️ 5. 설치 후 바탕화면에 표시되는 이름

설치 파일의 이름만 바뀌는 것은 아닙니다.

Squirrel.Windows를 통해 앱을 설치하면 Windows에 프로그램과 바로가기가 생성됩니다.

기존에는 프로젝트 이름을 기반으로 다음과 같이 표시되었다면,

electron-app

앱 이름을 변경한 후에는 사용자에게 표시되는 프로그램 이름도

Huni Roulette

로 맞춰줄 수 있습니다.

따라서 이번에 변경하는 productName은 단순히 Setup.exe의 파일명만 바꾸기 위한 설정이 아니라, 사용자가 실제로 접하게 되는 앱의 이름을 지정하는 설정이라고 이해하면 됩니다.

---

✔️ 6. 앱 아이콘 준비하기

이제 앱 이름을 변경했으니, 기본 Electron 아이콘 대신 준비한 아이콘을 적용해 보겠습니다.

Windows 프로그램에서는 일반적인 이미지 파일인 `.png`나 `.jpg`이미지보다 `.ico`형식의 아이콘 파일을 사용하는 경우가 많습니다.

먼저 사용할 이미지를 준비하고, `.ico`파일로 변환해야 합니다.

예를 들어 제가 사용할 이미지를 다음과 같이 준비했습니다.

Huni.png

이 이미지를 Windows 아이콘으로 사용할 수 있도록 `.ico`형식으로 변환합니다.

Huni.png
↓
Huni.ico

변환한 아이콘 파일은 프로젝트 안에 별도의 `assets`폴더를 만들어 관리하면 편리합니다.

예를 들어 다음과 같이 구성할 수 있습니다.

electron-app
├─ assets
│  └─ icon.ico
├─ index.html
├─ main.js
├─ package.json
└─ ...

 

---

✔️ 7. Electron Forge에서 아이콘 적용하기

이제 준비한 `icon.ico`를 Electron Forge에 적용해 보겠습니다.

Electron Forge에서는 아이콘을 설정하는 위치가 두 곳으로 나뉘고, 각각 적용되는 대상이 다릅니다.

먼저 표로 정리하면 이렇습니다.

설정	아이콘이 적용되는 곳
`packagerConfig.icon`	설치 후 실행 중인 프로그램 창 , 작업 표시줄 아이콘
`makers` → `setupIcon`	Setup.exe(설치 프로그램) 아이콘, 설치된 앱의 실행 파일(.exe), 바탕화면/시작 메뉴 바로가기 아이콘

즉, `setupIcon` 은 설치 프로그램인 Setup.exe에 사용할 아이콘을 설정하고, `packagerConfig.icon`은 패키징된 앱의 아이콘을 설정합니다. 

실제 설치 후에는 두 설정의 영향을 받아 설치 프로그램, 실행 파일, 바로가기 등에서 아이콘이 어떻게 표시되는지 확인할 수 있습니다.

🔹 앱 실행 중 아이콘 설정 (packagerConfig.icon)

먼저 `forge.config.js`의 `packagerConfig`에 `icon`을 추가합니다.

packagerConfig: {
  asar: true,
  icon: './assets/icon'   // 확장자(.ico)는 생략합니다
},

이 설정은 앱을 실행했을 때 뜨는 창 아이콘과 작업 표시줄 아이콘에 적용됩니다.

🔹 Setup.exe / 실행 파일 / 바로가기 아이콘 설정 (setupIcon)

`makers`의 Squirrel 설정에서 다음과 같이 `setupIcon`을 추가합니다.

makers: [
  {
    name: '@electron-forge/maker-squirrel',
    config: {
      setupIcon: './assets/icon.ico'   // 이번엔 확장자를 포함해서 작성합니다
    }
  }
]

`packagerConfig.icon`과 달리 `setupIcon`은 확장자(`.ico`)까지 정확히 작성해야 합니다. 이 설정 하나로 다음 세 가지가 한 번에 바뀝니다.

• Setup.exe(설치 프로그램) 파일 아이콘
• 설치된 프로그램의 실행 파일(.exe) 아이콘
• 바탕화면 / 시작 메뉴 바로가기 아이콘

🔹 setupIcon 적용 중 만난 오류

`setupIcon`을 추가하고 `npm run make`를 돌리면 이런 오류가 날 수 있습니다.

✖ Making a squirrel distributable for win32/x64
Fatal error: Unable to load file

제 환경에서는 `setupIcon`을 추가한 후 `Unable to load file` 오류가 발생했습니다.

원인을 찾아보니, Windows 사용자 계정명에 한글이 포함되어 있어 `%TEMP%` 경로에도 한글이 들어가는 환경이었고, 이 경로에서 아이콘 처리 과정에 문제가 발생하는 것으로 보였습니다.

프로젝트 폴더(`C:\electron-app`)는 영문이라 문제없어 보이지만, Windows가 내부적으로 쓰는 임시 폴더(`%TEMP%`)는 보통

C:\Users\사용자이름\AppData\Local\Temp

형태인데, 이 계정명이 한글이면 이 경로 자체가 걸림돌이 됩니다. `packagerConfig.icon`은 이 임시 폴더를 거치지 않는 다른 방식이라 문제없이 통과된 것이었습니다.

🔹 해결 방법: 빌드할 때만 임시 폴더 경로 바꾸기

먼저 영문 경로의 임시 폴더를 하나 만들고,  (한 번만 있으면 되고, 이미 있으면 다시 안 만들어도 됩니다.)

mkdir C:\temp

빌드 직전에 `TEMP/TMP` 경로를 그 폴더로 잠깐 바꿔준 뒤 `make`를 실행합니다.

set TEMP=C:\temp
set TMP=C:\temp
npm run make

한 번에 실행하면 다음과 같습니다.

mkdir C:\temp
set TEMP=C:\temp
set TMP=C:\temp
npm run make

이렇게 하니 오류 없이 정상적으로 설치 파일이 생성되었습니다.

`set TEMP=...` / `set TMP=...`: 는 지금 열려 있는 명령 프롬프트 창 안에서만 적용되는 임시 설정입니다.
컴퓨터 계정 이름이나 시스템 설정을 건드리는 게 아니라서, 창을 닫으면 자동으로 원래 값(C:\Users\사용자이름\AppData\Local\Temp)으로 돌아갑니다. 따로 되돌리는 작업은 필요 없어요.

다만 set은 세션이 끝나면 초기화되기 때문에, 새 명령 프롬프트를 열 때마다 다시 입력해줘야 하는 번거로움이 있습니다.

🔹 매번 입력하지 않으려면: npm 스크립트에 자동화하기

`cross-env`라는 패키지를 쓰면, `npm run make`를 실행할 때 저 임시 경로 설정이 자동으로 적용되게 만들 수 있습니다.

npm install --save-dev cross-env

`package.json`의 `scripts`를 다음과 같이 수정합니다.

"scripts": {
  "make": "cross-env TEMP=C:\\temp TMP=C:\\temp electron-forge make"
}

이제 `npm run make`만 실행해도 `TEMP/TMP` 경로가 자동으로 `C:\temp`로 설정된 상태에서 빌드가 진행됩니다. 이 설정은 `make` 스크립트를 실행할 때만 적용되고, 다른 프로그램이나 시스템 전체에는 영향을 주지 않습니다.

---

✔️ 8. 최종 확인하기

이름과 아이콘을 모두 적용한 뒤 설치 파일을 다시 만들고, 실제로 설치해서 확인해봤습니다.

항목	이전	이후
설치 파일 이름
설치된 프로그램 이름
설치 파일 아이콘
실행 파일 아이콘
바탕화면 바로가기 아이콘