증상: 검사 스크립트에서 잘 돌던 mp3 부품이 일렉트론 앱에서만
Mp3Encoder is not a constructor 로 터졌고, require(...) 결과는 빈 객체였습니다.원인: 앱은 electron-vite 의
externalizeDepsPlugin 이 부품을 밖에 두고 require 로 불렀고, 그 꾸러미의 exports 는 require 에 브라우저 전용 파일을 내줬습니다.해결: 그 부품만 번들 안에 넣도록
exclude 에 적었습니다. 새 부품은 검사 스크립트가 아니라 앱을 띄워 확인합니다.데스크톱 앱 하나와 작은 로그인 서버를 만들면서, 바깥 npm 부품 때문에 두 번 걸렸습니다. 하나는 "검사에서는 되는데 앱에서는 안 되는" 문제였고, 다른 하나는 "개발 PC 에서는 되는데 다른 곳에서는 설치조차 안 되는" 문제였습니다. 둘 다 부품을 어떻게 불러오고 어떻게 까느냐에서 생겼습니다.
두 사건을 한 표로
| 본 증상 | 뿌리 | 고친 방법 | |
|---|---|---|---|
| mp3 부품 | 앱에서만 is not a constructor |
묶는 도구가 달라 다른 진입 파일이 잡힘 | 그 부품만 번들 안에 넣음 |
| better-sqlite3 | 윈도우에서 컴파일 실패 | 네이티브 애드온은 환경마다 다시 빌드 | 바깥 부품 0개로 다시 만듦 |
mp3 부품이 앱에서만 터진 이야기
검사 스크립트와 앱은 같은 코드를 다르게 묶었다
wav 를 mp3 로 바꾸는 데 @breezystack/lamejs 를 썼습니다. 따로 만든 검사 스크립트로 돌려 보니 문제없이 mp3 가 나왔습니다. 그런데 같은 함수를 앱에 넣고 켜자 이 오류로 멈췄습니다.
Mp3Encoder is not a constructor
부품을 불러온 결과를 찍어 보니 빈 객체였습니다. 함수가 없으니 new 를 할 수 없었던 것입니다. 코드는 같았으므로 차이는 묶는 방식에 있었습니다.
| 묶는 도구 | 부품을 부르는 방식 | 결과 | |
|---|---|---|---|
| 검사 스크립트 | esbuild | 번들 안에 넣고 ESM 진입점 사용 | 정상 |
| 일렉트론 앱 | electron-vite (externalizeDepsPlugin) |
번들 밖에 두고 require |
빈 객체 |
까닭은 꾸러미의 exports 에 있었다
그 꾸러미의 package.json 을 열어 보니 불러오는 방식에 따라 다른 파일을 내주게 되어 있었습니다.
"exports": { "default": { "import": "./dist/lamejs.js", "require": "./dist/lamejs.iife.js" } }
import 로 부르면 모듈 파일이, require 로 부르면 iife 파일이 잡힙니다. iife 는 브라우저에서 스크립트 태그로 읽어 전역 변수에 붙는 모양이라, 노드의 require 로 읽으면 내보낸 것이 없는 빈 객체가 됩니다. 노드 공식 문서의 조건부 exports 설명과 같은 동작입니다.
의심이 들 때는 앱과 같은 방식으로 한 줄만 불러 보면 바로 보입니다.
node -e "console.log(Object.keys(require('@breezystack/lamejs')))"
그 부품만 번들 안에 넣는다
electron.vite.config.ts 에서 본체 쪽 설정에 이 한 줄을 넣었습니다. 다른 부품은 그대로 밖에 두고, 문제의 부품만 번들 안으로 들어와 ESM 진입점으로 묶입니다.
plugins: [externalizeDepsPlugin({ exclude: ['@breezystack/lamejs'] })]
네이티브 부품이 설치를 깨뜨린 이야기
로그인 서버에는 처음에 better-sqlite3 를 넣으려 했습니다. 윈도우에서 설치하자 컴파일이 실패했습니다. 노드 24 용으로 미리 만든 파일이 없어서 소스를 빌드하려 했고, 그 PC 에는 빌드 도구가 없었습니다.
이런 네이티브 애드온은 기계, 운영체제, 노드 판이 바뀔 때마다 다시 빌드해야 합니다. 개발 PC 에서 된다고 서버나 다른 PC 에서 된다는 보장이 없습니다. 같은 SQLite 라도 파이썬 쪽에서 겪은 잠금 문제는 SQLite database is locked 로 배치가 죽을 때에 따로 적었습니다.
그래서 작은 서버는 바깥 부품을 하나도 쓰지 않고 다시 만들었습니다. 노드에 이미 든 것으로 충분했습니다. SQLite 가 꼭 필요하다면 노드 24 에는 실험 단계의 내장 node:sqlite 모듈도 있습니다(노드 공식 문서 SQLite 항목). 이 글을 쓰며 노드 24.13.1 에서 DatabaseSync 로 한 줄 질의가 도는 것까지 봤고, 실행하면 실험 기능이라는 경고가 한 번 찍혔습니다. 앱을 이 모듈로 옮겨 보지는 않았습니다.
- 비밀번호 해시:
crypto.scryptSync - 서명:
createHmac - 웹서버:
node:http - 원자적 파일 쓰기:
writeFileSync로 임시 파일에 쓴 뒤renameSync
그 덕에 npm install 자체가 필요 없어졌고, 백업은 파일 복사 한 줄, 서버 이사는 파일 하나 옮기기가 됐습니다.
그 뒤로 지키는 규칙 두 개
첫째, 새 부품을 넣으면 검사 스크립트가 아니라 앱을 띄워 확인합니다. 묶는 도구가 다르면 같은 코드도 다른 파일을 부릅니다. 이번처럼 오류가 앱 안에서만 나면 검사 쪽은 끝까지 아무 말이 없으니, 실패가 숨는 길을 미리 알아 두는 것도 도움이 됩니다. 파이썬 쪽 사례는 파이썬에서 실패가 조용히 숨는 경우에 모았습니다. 검사는 통과했는데 실제로 돌리는 곳에서 깨진 다른 경우는 py_compile 검사를 통과했는데 라이브 서버가 죽었을 때에 있습니다.
둘째, 부품 하나가 죽어도 일은 굴러가게 만듭니다. 이 앱의 미리듣기는 mp3 변환이 실패하면 wav 로 두고 소리는 냅니다. mp3 는 담는 자리를 아끼려는 것일 뿐이라, 그 때문에 소리를 못 내면 앞뒤가 바뀐 것입니다. 같은 앱에서 변환이 창을 얼린 일은 일렉트론 창이 긴 작업 중 응답 없음으로 얼 때에, 스토어용 설치 파일로 포장하다 겪은 문제는 MSIX 일렉트론 앱에서 AppData 가 갈라질 때에 적었습니다.
확인한 환경
| 항목 | 내용 |
|---|---|
| 운영체제 | 윈도우 |
| 노드 | 24 (better-sqlite3 설치 실패 때) |
| 묶는 도구 | 앱 = electron-vite, 검사 스크립트 = esbuild |
| 확인한 시기 | 2026년 8월 |
이 글의 내용은 2026년 10월 24일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.