build: bundle sharp's win32-x64 prebuilt for Windows packaging

The packaged installer-rp crashed on launch with
"Could not load the 'sharp' module using the win32-x64 runtime" because
electron-builder ran on Linux and only the Linux sharp variants were
present in node_modules.

- Add `preinstall:sharp-win32` script that force-installs
  `@img/sharp-win32-x64@0.34.5` into the local node_modules (npm refuses
  it on Linux without --force due to its os/cpu restrictions).
- Chain that script before both `dist:win` and `dist:win:rp` so future
  Windows builds always have the native prebuilt available.
- Exclude `@img/sharp-{,libvips-}linux*` from the packaged files list in
  both electron-builder configs so the unused Linux variants don't bloat
  the portable exe.

Verified `release/win-unpacked/resources/app.asar.unpacked/node_modules/
@img/sharp-win32-x64/lib/sharp-win32-x64.node` is present and that no
linux sharp variants ship inside the asar.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.env.build

@@ -0,0 +1,4 @@
+# 빌드용 환경변수 — `npm run dist:win` / `npm run dist:win:rp` 로 패키징될 때
+# 설치기 exe 의 `resources/.env.build` 로 함께 배포되어 런타임에 로드됨.
+# 서버 운영용(PORT/HOST/SESSION_SECRET) 값은 여기 두지 말고 `.env` 에.
+SITE_BASE_URL=https://mc.tkrmagid.kr

.env.build.example

@@ -0,0 +1,37 @@
+# =============================================================================
+# 음악퀴즈 통합 패키지 — 빌드용 환경변수 템플릿
+#
+# 이 파일은 `npm run dist:win` / `npm run dist:win:rp` 로 exe 를 패키징할 때
+# 설치기(installer / installer-rp) 안에 함께 묶이는 값들입니다.
+# 개발 실행에서 쓰는 `.env` 와는 분리되어 있어, 운영 도메인 같은 값을 빌드용
+# 으로만 관리할 수 있습니다.
+#
+# 사용법:
+#   1) 이 파일을 복사해 `.env.build` 로 만든다.
+#   2) 운영 도메인 등 배포에 들어갈 값으로 채운다.
+#   3) `npm run dist:win` 또는 `npm run dist:win:rp` 로 빌드한다.
+#      → electron-builder 가 `.env.build` 를 패키지된 exe 의
+#        `resources/.env.build` 로 함께 배포.
+#      → 런타임에서 `env.ts` 가 우선 로드.
+#
+# `.env.build` 는 .gitignore 로 제외되어 있습니다.
+# 서버(express) 운영용 PORT / HOST / SESSION_SECRET 같은 변수는 여기 두지 말고
+# 서버 측 `.env` 에 두세요. 이 파일은 설치기 exe 에 묶이는 값 전용입니다.
+# =============================================================================
+
+# ----- 사이트 도메인(설치기가 manifest 를 받아갈 주소) -----
+
+# 설치기 두 종(installer / installer-rp) 이 첫 화면에서 자동으로 채워 넣는
+# manifest 의 호스트. 프로토콜 + 호스트(+포트) 까지만 적고 슬래시는 끝에 붙이지 않음.
+# 예) 운영 도메인     : https://mq.example.com
+#     로컬 개발       : http://127.0.0.1:3000
+SITE_BASE_URL=https://mq.example.com
+
+# 위 SITE_BASE_URL 로부터 자동으로 `${SITE_BASE_URL}/manifest.json` 이 생성됩니다.
+# 특별히 다른 경로를 쓰고 싶을 때만 아래를 풀어서 우선 적용시키세요.
+# MANIFEST_URL=https://mq.example.com/manifest.json
+
+# ----- 리소스팩 설치기 -----
+
+# yt-dlp 동시 다운로드 수(1~8). 비워두면 CPU 코어 수로 자동 결정.
+# MUSIC_CONCURRENCY=

electron-builder-rp.yml

@@ -13,12 +13,18 @@ files:
   - installer-rp/**
   - build/icon.*
   - package.json
-# 메인 설치기와 동일하게 .env, locales 를 함께 배포.
+  # sharp 는 플랫폼별 prebuilt 가 분리 패키지로 배포됨. Windows 빌드에서는
+  # win32-x64 만 포함하고 linux/* 변종은 묶지 않아 exe 크기를 줄임.
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+# 메인 설치기와 동일하게 빌드 전용 `.env.build` 와 locales 를 함께 배포.
 extraResources:
   - from: .
     to: .
     filter:
-      - .env
+      - .env.build
   - from: locales
     to: locales
     filter:

electron-builder.yml

@@ -9,15 +9,23 @@ files:
   - installer/**
   - build/icon.*
   - package.json
-# 빌드 시점의 .env 를 설치기 옆에 함께 배포(없으면 조용히 패스).
-# 패키징 후 운영자가 resources/.env 만 교체해서 도메인을 바꿀 수도 있음.
+  # sharp 는 플랫폼별 prebuilt 가 분리 패키지로 배포됨. Windows 빌드에서는
+  # win32-x64 만 포함하고 linux/* 변종은 묶지 않아 exe 크기를 줄임.
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+# 빌드 전용 `.env.build` 를 설치기 옆에 함께 배포(없으면 조용히 패스).
+# `.env` 는 서버/개발 실행용이라 빌드 산출물에는 포함되지 않으며, 패키지된 exe
+# 는 `resources/.env.build` 를 우선 로드함(없으면 `resources/.env` 로 폴백).
+# 패키징 후 운영자가 `resources/.env.build` 만 교체해서 도메인을 바꿀 수 있음.
 # locales/ 폴더는 i18n.ts 가 process.resourcesPath/locales/<component>/ko-kr.json
 # 을 찾아 로드하므로, 빌드된 .exe 에서도 한국어 사전이 적용되도록 함께 배포.
 extraResources:
   - from: .
     to: .
     filter:
-      - .env
+      - .env.build
   - from: locales
     to: locales
     filter:

locales/installer/ko-kr.json

@@ -47,7 +47,7 @@
     "hostTitle": "호스트",
     "hostHint": "내가 서버를 직접 열고 친구들을 초대할 때",
     "participantTitle": "참가자",
-    "participantHint": "친구가 연 서버에 접속만 할 때 (맵은 받지 않음)"
+    "participantHint": "친구가 연 서버에 접속만 할 때"
   },
   "step3": {
     "heading": "서버 관련 설정",

package.json

@@ -9,8 +9,9 @@
     "dev:server": "tsc -p tsconfig.server.json && node dist/server/app.js",
     "installer": "tsc -p tsconfig.installer.json && electron .",
     "installer:rp": "tsc -p tsconfig.installer-rp.json && electron dist/installer-rp/main.js",
-    "dist:win": "tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder.yml",
-    "dist:win:rp": "tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp.yml"
+    "preinstall:sharp-win32": "npm install --no-save --force @img/sharp-win32-x64@0.34.5",
+    "dist:win": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder.yml",
+    "dist:win:rp": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp.yml"
   },
   "dependencies": {
     "@types/archiver": "^7.0.0",

src/shared/env.ts

@@ -4,30 +4,42 @@ import dotenv from 'dotenv'
 import { projectRoot } from './paths.js'
 
 /**
- * `.env` 를 읽어 `process.env` 에 주입.
+ * `.env` / `.env.build` 를 읽어 `process.env` 에 주입.
  *
- * 탐색 순서(처음 발견된 것만 사용):
- *   1. 패키징된 Electron 앱이면 `process.resourcesPath/.env`
- *      — electron-builder 의 extraResources 로 빌드 시점 `.env` 가 함께 배포됨.
- *   2. `<프로젝트 루트>/.env`
- *      — 개발 실행(npm start / npm run installer*) 및 서버 운영용.
+ * 여러 파일을 순서대로 읽되 `override:false` 로 병합하므로 **먼저 로드된 값이
+ * 우선**. 두 도메인(패키지 빌드용 vs 개발/서버용) 이 한 함수에서 자연스럽게
+ * 분리됨:
  *
- * - 이미 설정된 환경변수는 덮어쓰지 않음(쉘/systemd 에서 넘긴 값이 우선).
- * - 파일이 없으면 조용히 통과.
+ *   1. 패키징된 Electron 앱: `process.resourcesPath/.env.build`
+ *      — electron-builder 가 빌드 시점 `.env.build` 를 함께 배포. 패키지된 exe
+ *        에서 가장 먼저 적용되는 값.
+ *   2. 패키징된 Electron 앱: `process.resourcesPath/.env`
+ *      — 운영자가 패키징 후 직접 `.env` 를 옆에 두고 덮어쓰는 경우 폴백.
+ *   3. `<프로젝트 루트>/.env`
+ *      — 개발 실행(npm start / npm run installer*) 및 서버 운영용. 서버의
+ *        `PORT/HOST/SESSION_SECRET` 처럼 dev 에서 반드시 살아 있어야 하는 값들이
+ *        있어, `.env.build` 보다 먼저 로드해 우선권을 줌.
+ *   4. `<프로젝트 루트>/.env.build`
+ *      — dev 환경에서 빌드용 값(예: 운영 도메인 SITE_BASE_URL)을 테스트하고
+ *        싶을 때 사용. `.env` 에 없는 키만 채움.
+ *
+ * - 이미 설정된 환경변수는 덮어쓰지 않음(쉘/systemd 에서 넘긴 값이 최우선).
+ * - 존재하지 않는 후보는 조용히 건너뜀.
  * - 서버/설치기/리소스팩설치기 진입점에서 한 번씩 호출.
  */
 export function loadEnv(): void {
   const candidates: string[] = []
   const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath
   if (typeof resourcesPath === 'string' && resourcesPath.length > 0) {
+    candidates.push(path.join(resourcesPath, '.env.build'))
     candidates.push(path.join(resourcesPath, '.env'))
   }
   candidates.push(path.join(projectRoot, '.env'))
+  candidates.push(path.join(projectRoot, '.env.build'))
 
   for (const envPath of candidates) {
     if (fs.existsSync(envPath)) {
       dotenv.config({ path: envPath, override: false, quiet: true })
-      return
     }
   }
 }