electron-builder

electron-builder

ドキュメント：https://www.electron.build（v26.8.x） リポジトリ：https://github.com/electron-userland/electron-builder

クイックスタート

インストール：

pnpm add electron-builder -D
pnpm add electron-updater  # If using auto-updates

最小構成の設定（electron-builder.yml）：

appId: com.example.myapp
productName: My App
files:
  - "out/**/*"
  - "package.json"
mac:
  target: dmg
  category: public.app-category.developer-tools
win:
  target: nsis
linux:
  target:
    - AppImage
    - deb
publish:
  provider: github

package.json のビルドスクリプト：

{
  "scripts": {
    "build:mac": "electron-builder --mac",
    "build:win": "electron-builder --win",
    "build:linux": "electron-builder --linux",
    "build:all": "electron-builder -mwl",
    "release": "electron-builder --publish always"
  }
}

CLI リファレンス

electron-builder                    # Build for current platform
electron-builder -mwl              # Build for all platforms
electron-builder --mac dmg         # macOS DMG only
electron-builder --win nsis:ia32   # Windows NSIS 32-bit
electron-builder --linux deb tar.xz
electron-builder --dir             # Unpacked dir (test builds)
electron-builder -p always         # Build and publish

# Architecture flags
--x64  --ia32  --armv7l  --arm64  --universal

# CLI config overrides
-c.extraMetadata.foo=bar
-c.mac.identity=null
-c.nsis.unicode=false

# Publish existing artifacts
electron-builder publish -f dist/*.exe -c electron-builder.yml

公開フラグの値：onTag | onTagOrDraft | always | never

設定

設定ファイルの場所（次の順に確認します）：

1. package.json の "build" キー
2. electron-builder.yml（デフォルト、推奨）
3. electron-builder.json / .json5 / .toml
4. electron-builder.config.js / .ts
5. CLI：--config <path>

JS 設定ファイルに electron-builder.js という名前を付けないでください — パッケージ名と競合します。

設定オプション、ファイルパターン、マクロ、アイコン、ディレクトリ設定の全容については、以下を参照してください。 references/configuration.md

重要な設定プロパティ

プロパティ	デフォルト	説明
appId	com.electron.${name}	デプロイ後は変更しないでください。 バンドル ID（macOS）および AUMID（Windows）として使用されます。
productName	package.json name	表示名（スペースを使用できます）
compression	"normal"	テストビルドを高速化するには "store"、リリースには "maximum" を指定します
asar	true	ソースを asar アーカイブにパッケージ化します
files	auto	アプリのソースファイルを指定する Glob パターン
extraFiles	—	asar の外部にコピーするファイル（例：ネイティブアドオン）
extraResources	—	resources ディレクトリにコピーするファイル
forceCodeSigning	false	署名されていない場合、ビルドを失敗させます

ファイルマクロ

artifactName、ファイルパターン、公開 URL で使用できます： ${arch}, ${os}, ${platform}, ${name}, ${productName}, ${version}, ${channel}, ${ext}, ${env.VAR_NAME}

デフォルトのターゲット

プラットフォーム	デフォルト
macOS	DMG + ZIP
Windows	NSIS
Linux（クロスビルド）	Snap + AppImage（x64）
Linux（ネイティブ）	Snap + AppImage（現在のアーキテクチャ）

コード署名

設定すると、署名は自動的に行われます。主な環境変数：

環境変数	説明
CSC_LINK	証明書のパス／URL／Base64（.p12/.pfx）
CSC_KEY_PASSWORD	証明書のパスワード
CSC_IDENTITY_AUTO_DISCOVERY	true/false（macOS キーチェーンの自動検出）
WIN_CSC_LINK	Windows 証明書（macOS からクロス署名する場合）
WIN_CSC_KEY_PASSWORD	Windows 証明書のパスワード

macOS：署名を無効にする

export CSC_IDENTITY_AUTO_DISCOVERY=false
# Or in config: mac.identity: null
# For ad-hoc (ARM): mac.identity: "-"

macOS：公証

mac:
  hardenedRuntime: true
  notarize: true    # or { teamId: "TEAM_ID" }

APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_TEAM_ID 環境変数が必要です。

Windows：Azure Trusted Signing

win:
  azureSignOptions:
    publisherName: "CN=Your Company"
    endpoint: "https://eus.codesigning.azure.net"
    certificateProfileName: "your-profile"
    codeSigningAccountName: "your-account"

AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET が必要です。

CI の設定、証明書、EV 証明書、クロスプラットフォーム対応を含むコード署名の全リファレンスについては、以下を参照してください。 references/code-signing.md

自動更新（electron-updater）

最小限の設定

// main process
import electronUpdater, { type AppUpdater } from "electron-updater";

export function getAutoUpdater(): AppUpdater {
  const { autoUpdater } = electronUpdater;
  return autoUpdater;
}

const autoUpdater = getAutoUpdater();
autoUpdater.checkForUpdatesAndNotify();

setFeedURL() を呼び出さないでください — app-update.yml はビルド時に自動生成されます。

ESM インポート（必須の回避策）

// CORRECT
import electronUpdater from "electron-updater";
const { autoUpdater } = electronUpdater;

// WRONG (may fail with ESM)
import { autoUpdater } from "electron-updater";

自動更新に対応するターゲット

• macOS：DMG
• Windows：NSIS
• Linux：AppImage、DEB、Pacman（ベータ版）、RPM

自動更新には macOS アプリの署名が必須です。 Squirrel.Windows はサポートされていません。

イベント

autoUpdater.on("error", (err) => {});
autoUpdater.on("checking-for-update", () => {});
autoUpdater.on("update-available", (info) => {});
autoUpdater.on("update-not-available", (info) => {});
autoUpdater.on("download-progress", (progress) => {
  // .bytesPerSecond, .percent, .total, .transferred
});
autoUpdater.on("update-downloaded", (info) => {
  autoUpdater.quitAndInstall();
});

デバッグ

import log from "electron-log";
autoUpdater.logger = log;
autoUpdater.logger.transports.file.level = "info";

段階的なロールアウト、カスタムアップデーターインスタンス、プライベートリポジトリ、開発時のテストについては、以下を参照してください。 references/auto-update.md

公開

GitHub Releases の簡単な設定

publish:
  provider: github
  releaseType: draft

GH_TOKEN 環境変数を設定します（repo スコープの個人用アクセストークン）。

S3 の簡単な設定

publish:
  provider: s3
  bucket: my-bucket-name

AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を設定します。

汎用サーバーの簡単な設定

publish:
  provider: generic
  url: https://example.com/releases

アーティファクトと latest.yml を手動でアップロードします。

公開 CLI の動作

条件	デフォルトの動作
CI を検出	onTagOrDraft
CI + タグをプッシュ	onTag
npm スクリプト release	always

リリースチャネル

バージョンによってチャネルが決まります：1.0.0 = latest、1.0.0-beta.1 = beta

すべてのパブリッシャー（Bitbucket、GitLab、Keygen、Snap Store、Spaces）、ワークフロー、高度な設定については、以下を参照してください。 references/publishing.md

プラットフォームターゲットの設定

macOS

mac:
  category: public.app-category.developer-tools
  hardenedRuntime: true
  darkModeSupport: true
  target: dmg
  entitlements: build/entitlements.mac.plist
  notarize: true

Windows（NSIS）

nsis:
  oneClick: true              # false for assisted installer
  perMachine: false
  allowToChangeInstallationDirectory: false
  createDesktopShortcut: true
  deleteAppDataOnUninstall: false
  include: build/installer.nsh  # Custom NSIS script
  differentialPackage: true

Linux

linux:
  category: Development
  desktop:
    MimeType: "x-scheme-handler/myapp"
  target:
    - AppImage
    - deb
    - snap

すべてのターゲットオプション（DMG、PKG、MAS、MSI、AppX、Snap、Flatpak、ポータブル、カスタム NSIS スクリプト）については、こちらをご覧ください： references/platform-targets.md

ビルドフック

実行順序：

beforeBuild → beforePack → afterExtract → afterPack → [signing] →
afterSign → artifactBuildStarted → [build] → artifactBuildCompleted →
afterAllArtifactBuild

インライン（JS/TS 設定）

module.exports = {
  afterSign: async (context) => {
    if (context.electronPlatformName === "darwin") {
      await notarize(context);
    }
  },
  afterAllArtifactBuild: (result) => {
    return ["/path/to/extra/file"];  // Additional files to publish
  },
};

ファイル参照（YAML 設定）

beforePack: "./scripts/before-pack.js"
afterSign: "./scripts/notarize.js"

// scripts/notarize.js
exports.default = async function(context) {
  // context: { outDir, appOutDir, packager, electronPlatformName, arch, targets }
};

すべてのフック、コンテキストインターフェース、プログラム API については、こちらをご覧ください： references/hooks-and-programmatic.md

一般的なパターン

マルチプラットフォームの CI ビルド

# GitHub Actions pattern
mac:
  target:
    - target: dmg
      arch: [x64, arm64]
win:
  target:
    - target: nsis
      arch: [x64, ia32]
linux:
  target:
    - target: AppImage
      arch: [x64, arm64]
    - target: deb
      arch: [x64, arm64]
publish:
  provider: github

自動更新と署名を含む完全な設定

appId: com.example.myapp
productName: My App
copyright: Copyright 2024 Example Inc.
asar: true
compression: normal
forceCodeSigning: true

directories:
  output: dist
  buildResources: build

files:
  - "out/**/*"
  - "package.json"

mac:
  target: [dmg, zip]
  hardenedRuntime: true
  notarize: true
  category: public.app-category.developer-tools

win:
  target: nsis

nsis:
  oneClick: false
  perMachine: false
  allowToChangeInstallationDirectory: true

linux:
  target: [AppImage, deb]
  category: Development

publish:
  provider: github

electronUpdaterCompatibility: ">= 2.16"

注意点

1. リリース後に appId を変更しないでください — NSIS はレジストリ GUID に使用します
2. 自動更新を機能させるには macOS の署名が必要です
3. TypeScript で electron-updater を使用するには ESM インポートの回避策が必要です
4. setFeedURL() を呼び出さないでください — app-update.yml は自動生成されます
5. Squirrel.Windows は electron-updater でサポートされていません — NSIS を使用してください
6. Windows の環境変数の上限は 8192 文字です — 長すぎる場合は、チェーンなしで証明書を再エクスポートしてください
7. electron-builder.js はパッケージ名と競合します — 別のファイル名を使用してください
8. Windows の通知を使うには、メインプロセスで app.setAppUserModelId(appId) を設定してください