Skip to main content

고급 설치 가이드

미리 빌드된 Electron 바이너리를 설치하려면 npm을 사용한다. 앱의 개발 의존성으로 Electron을 설치하는 것이 권장되는 방법이다:

npm install electron --save-dev

앱에서 Electron 버전을 관리하는 방법에 대한 자세한 내용은 Electron 버전 관리 문서를 참고한다.

Electron을 임시로 실행하기​

긴급한 상황에서 로컬 프로젝트에 npm install을 사용하지 않고 싶다면, npm에 포함된 npx 커맨드 러너를 사용해 Electron을 임시로 실행할 수 있다:

npx electron .

위 명령어는 현재 작업 디렉토리를 Electron으로 실행한다. 단, 앱에 필요한 의존성은 설치되지 않는다는 점에 유의한다.

커스텀 설정​

다운로드할 아키텍처를 변경하려면(예: x64 머신에서 ia32를 사용하는 경우) npm install 명령어에 --arch 플래그를 사용하거나 npm_config_arch 환경 변수를 설정한다:

npm install --arch=ia32 electron

아키텍처를 변경하는 것 외에도, --platform 플래그를 사용해 플랫폼(예: win32, linux 등)을 지정할 수 있다:

npm install --platform=win32 electron

프록시​

HTTP 프록시를 사용해야 한다면, ELECTRON_GET_USE_PROXY 변수에 아무 값이나 설정해야 한다. 또한 호스트 시스템의 Node 버전에 따라 추가 환경 변수를 설정해야 한다:

커스텀 미러와 캐시 설정​

electron 모듈을 설치할 때, 플랫폼에 맞는 Electron의 미리 빌드된 바이너리를 다운로드하기 위해 @electron/get을 호출한다. 이 과정에서 GitHub의 릴리스 다운로드 페이지(https://github.com/electron/electron/releases/tag/v$VERSION, 여기서 $VERSION은 Electron의 정확한 버전)에 접속한다.

GitHub에 접근할 수 없거나 커스텀 빌드를 제공해야 하는 경우, 미러 서버를 설정하거나 기존의 캐시 디렉터리를 사용할 수 있다.

미러 설정​

기본 URL, Electron 바이너리를 찾을 경로, 바이너리 파일명을 환경 변수로 재정의할 수 있다. @electron/get이 사용하는 URL은 다음과 같이 구성된다.

url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME

예를 들어, 중국 CDN 미러를 사용하려면 아래와 같이 설정한다.

ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

기본적으로 ELECTRON_CUSTOM_DIR은 v$VERSION으로 설정된다. 형식을 변경하려면 {{ version }} 플레이스홀더를 사용한다. 예를 들어, version-{{ version }}은 version-5.0.0으로, {{ version }}은 5.0.0으로, v{{ version }}은 기본값과 동일하게 해석된다. 더 구체적인 예로, 중국 비-CDN 미러를 사용하려면 아래와 같이 설정한다.

ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
ELECTRON_CUSTOM_DIR="{{ version }}"

위 설정은 https://npmmirror.com/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip과 같은 URL에서 파일을 다운로드한다.

미러가 공식 Electron 릴리스와 다른 체크섬을 제공하는 경우, electron_use_remote_checksums=1을 직접 설정하거나 .npmrc 파일에 구성하여 Electron이 내장된 체크섬 대신 원격 SHASUMS256.txt 파일을 사용하도록 강제할 수 있다.

캐시​

로컬 캐시를 재정의할 수도 있다. @electron/get은 네트워크 부하를 줄이기 위해 다운로드한 바이너리를 로컬 디렉토리에 캐시한다. 이 캐시 폴더를 통해 커스텀 빌드된 Electron을 제공하거나 네트워크 연결 없이 작업할 수 있다.

  • Linux: $XDG_CACHE_HOME 또는 ~/.cache/electron/
  • macOS: ~/Library/Caches/electron/
  • Windows: $LOCALAPPDATA/electron/Cache 또는 ~/AppData/Local/electron/Cache/

이전 버전의 Electron을 사용하던 환경에서는 ~/.electron에도 캐시가 있을 수 있다.

electron_config_cache 환경 변수를 제공해 로컬 캐시 위치를 재정의할 수도 있다.

캐시에는 해당 버전의 공식 zip 파일과 체크섬이 포함되며, [체크섬]/[파일명] 형태로 저장된다. 일반적인 캐시 구조는 다음과 같다:

├── a91b089b5dc5b1279966511344b805ec84869b6cd60af44f800b363bba25b915
│   └── electron-v15.3.1-darwin-x64.zip

바이너리 다운로드 건너뛰기​

Electron의 JavaScript API는 실제 구현이 포함된 바이너리에 바인딩된다. 이 바이너리는 모든 Electron 앱의 동작에 필수적이기 때문에, npm 레지스트리에서 electron을 설치할 때마다 기본적으로 postinstall 단계에서 다운로드된다.

하지만 프로젝트의 의존성을 설치하면서 Electron 기능을 사용할 필요가 없다면, ELECTRON_SKIP_BINARY_DOWNLOAD 환경 변수를 설정해 바이너리 다운로드를 방지할 수 있다. 예를 들어, electron 모듈을 모킹하는 단위 테스트를 실행하는 CI(지속적 통합) 환경에서 이 기능을 활용할 수 있다.

ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install

문제 해결​

npm install electron 명령어를 실행할 때 일부 사용자가 설치 오류를 겪는 경우가 있다.

대부분의 경우, 이러한 오류는 네트워크 문제로 인해 발생하며 electron npm 패키지 자체의 문제는 아니다. ELIFECYCLE, EAI_AGAIN, ECONNRESET, ETIMEDOUT과 같은 오류는 모두 네트워크 문제를 나타낸다. 가장 좋은 해결 방법은 네트워크를 변경하거나 잠시 기다린 후 다시 설치를 시도하는 것이다.

npm을 통해 설치가 실패한다면, electron/electron/releases에서 직접 Electron을 다운로드할 수도 있다.

EACCESS 오류가 발생한다면, npm 권한 설정을 수정해야 할 수 있다.

위 오류가 계속 발생한다면, --unsafe-perm 플래그를 true로 설정해야 할 수 있다:

sudo npm install electron --unsafe-perm=true

느린 네트워크에서는 다운로드 진행 상황을 확인하기 위해 --verbose 플래그를 사용하는 것이 좋다:

npm install --verbose electron

에셋과 SHASUM 파일을 강제로 다시 다운로드해야 한다면, force_no_cache 환경 변수를 true로 설정한다.