2026.10.31 Electron

electron-builderの使い方：Windows・Linux配布とelectron-updaterの自動更新【v26】

Q: electron-builderでWindowsのexeを作るにはどうすればよいですか？

package.jsonの build.win.target に nsis を書き、Windows上で npx electron-builder --win を実行します。インストーラを通さず単体で起動する.exeが欲しい場合は、ターゲットを portable にします。portableは自動更新の対象外なので、更新を配るアプリではNSISを選んでください。

Q: electron-updaterの更新が開発中に動かないのはなぜですか？

接続先を書いた app-update.yml は、パッケージ化したときに resources へ作られるファイルです。 electron . で起動した開発中のアプリには存在しません。開発中に試すなら、プロジェクト直下に dev-app-update.yml を置き、 autoUpdater.forceDevUpdateConfig = true を設定します。公式は、実際にインストールした版で確かめる方法を勧めています。

Q: GitHubの非公開リポジトリから自動更新を配れますか？

非公開リポジトリからの自動更新の配布は可能です。publishリファレンスのGitHubの設定に private の項目があり、トークンを使って取得します。ただしトークンを設定ファイルに書かないよう警告があり、アプリに埋め込めば利用者に取り出されます。社外へ配るアプリは、S3互換のストレージなど別の公開場所に置く方が安全です。

electron-builderの使い方：Windows・Linux配布とelectron-updaterの自動更新【v26】

electron-builderは、Electronで作ったアプリをWindowsのインストーラ（.exe）やLinuxのAppImage、macOSのdmgにまとめ、GitHub Releasesなどへの公開と自動更新までを1つの設定ファイルで扱えるMITライセンスのツールです。この記事では、2026年10月31日にnpm registryで確認した安定版26.18系を前提に、build設定、NSISの既定値、electron-updaterのコード、GitHub Actionsでの公開、Windowsの署名を順に扱います。後半はElectron Forgeとの使い分けと、v27で変わる点です。

まとめ：electron-builderで配布物と自動更新を組む範囲と選ぶ条件

Windowsの業務アプリを社内や顧客へ配り、配布後も自動で更新させたいなら、electron-builderとelectron-updaterの組み合わせが第一候補です。WindowsはNSIS、LinuxはAppImageを作り、GitHub Releasesか自社のS3互換ストレージへlatest.ymlと一緒に置けば、アプリ側はautoUpdater.checkForUpdatesAndNotify()の1行で更新を確認できます。

注意したい点は2つあります。v26では公開の方針を書かないとCIの状況から自動で決まり、この挙動はv27で無効になります。最初から--publishを明示してください。もう1つはWindowsの署名で、証明書が無くてもビルドは黙って成功し、利用者の画面に「不明な発行元」の警告が出ます。

Macだけに配る案件や、Electron公式のツールでそろえたい新規案件はElectron Forgeで足ります。

electron-builderの役割とv26.18系・v27 alphaの位置づけ

electron-builderの仕事は、Electron本体とアプリのコードを各OSの配布形式へ詰めることです。Electronアプリ全体の仕組みはElectronの仕組みと始め方を解説した入門記事で扱っているので、ここでは配布の段階だけを見ます。

パッケージ化・インストーラ生成・公開・自動更新を1本で担う範囲

公式のGitHubリポジトリでは、macOSのdmg・pkg、Linuxのdeb・rpm・AppImage・snapなど多数の形式に対応すると説明されています。担う作業は、asarアーカイブへの固め、インストーラ作成、署名、公開、更新情報ファイルの生成です。

自動更新の実行部分は別パッケージのelectron-updaterが受け持ちます。electron-builderが作ったapp-update.ymlとlatest.ymlを、配布後のアプリが読む分担です。

npm registryのlatest・nextタグで確認する安定版と先行版

npm registryの記録では、2026年10月31日時点でlatestタグが26.18.0（10月20日公開）、v26タグが26.18.1（10月26日公開）、nextタグが27.0.0-alpha.14（10月29日公開）を指していました。26.0.0の公開は2025年1月26日です。v26系はNode.js 14.0.0以上で動く指定になっています。

electron-updaterはlatestが6.8.11です。latestよりv26タグの方が新しい修正版を指す時期があるので、npm view electron-builder dist-tagsで確かめてから入れます。

electron-builderを入れてpackage.jsonのbuild設定を書く手順

設定はpackage.jsonのbuildキーか、別ファイルのelectron-builder.ymlに書きます。v26の設定リファレンスによると、ほかにjson・json5・toml・js・tsの形式も読めます。

devDependenciesへの追加とdistスクリプトの最小構成

electron-builderとElectron本体は開発依存として入れ、electron-updaterだけは実行時に使うので通常の依存に入れます。package.jsonの最小構成は次の形です。

npm install --save-dev electron electron-builder
npm install electron-updater

{
  "name": "sample-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dist": "electron-builder --publish never",
    "release": "electron-builder --publish always"
  },
  "build": {
    "appId": "jp.co.example.sampleapp",
    "productName": "SampleApp",
    "directories": { "output": "release" },
    "win": { "target": ["nsis"] },
    "linux": { "target": ["AppImage", "deb"], "category": "Office" }
  }
}

npm run distを実行すると、実行したOS向けの成果物がreleaseフォルダに出ます。appIdを省くとcom.electron.${name}になるので、Windowsのスタートメニューやインストール先の識別に使われる前提で、自社のドメインを逆にした値を最初に決めておきます。

asar・filesの既定値と開発依存のパッケージが同梱されない仕組み

設定リファレンスでは、asarの既定値はtrueで、ソースは1つのアーカイブにまとめられます。ネイティブモジュールなど展開が要るファイルは、自動判定の対象です。filesの既定は**/*に除外パターンを足したもので、devDependenciesは「どの場合もコピーされない」と書かれています。

配布サイズが膨らむ原因の多くは、実行時に使わないパッケージをdependenciesに入れていることです。ビルドツールやテスト用のパッケージを開発依存へ移すだけで、インストーラは小さくなります。帳票テンプレートなどアプリ外のファイルはextraResourcesで同梱し、process.resourcesPathから読みます。設定をJavaScriptで書くときは、パッケージ名と衝突するためelectron-builder.jsというファイル名を避けてください。

Windows用NSISインストーラとLinux用AppImageを作るビルド設定

各OSの形式はwin・linux・macキーのtargetで選びます。何も書かなければWindowsはNSIS、LinuxはAppImageとSnapが作られます。

NSISのoneClick・perMachine既定値と業務アプリ向けの組み合わせ

NSISのリファレンスに載っている主な既定値は次のとおりです。

オプション	既定値	意味
oneClick	true	画面を出さずにすぐインストールする
perMachine	false	全ユーザー向けに固定するか
allowElevation	true	管理者権限への昇格を求めるか
インストール先の変更許可	false	インストール先を選ばせるか
createDesktopShortcut	true	デスクトップにショートカットを作るか
deleteAppDataOnUninstall	false	削除時にアプリのデータも消すか
differentialPackage	true	差分更新に対応した形で作るか

表の「インストール先の変更許可」は、allowToChangeInstallationDirectoryに対応する項目です。既定のままだと、ユーザー単位にワンクリックで入るインストーラになります。情報システム部門が配布ツールで全端末へ入れる業務アプリなら、全ユーザー向けのインストール先に固定します。

# electron-builder.yml（package.jsonのbuildキーの代わりに使う場合）
appId: jp.co.example.sampleapp
win:
  target: nsis
nsis:
  oneClick: false
  perMachine: true
  allowToChangeInstallationDirectory: true

成果物の名前は既定で${productName} Setup ${version}.${ext}です。ファイル名に空白が入るので、社内のファイルサーバーやURLで扱いにくい場合はartifactNameで付け替えます。

Linux既定のAppImage・Snapとdeb・rpmを足すときの設定

Linuxのリファレンスでは、既定のターゲットはAppImageとSnapです。Ubuntuの社内端末へ配るならdeb、Red Hat系ならrpmをtargetへ足します。debのメンテナ欄はmaintainerを書かなければpackage.jsonのauthorが入ります。

自動更新に対応するLinuxの形式はAppImage・DEB・Pacman・RPMです。Snapはストア側で更新されるため、electron-updaterの対象には入りません。

1台で全OSを作れない制約とDockerのwineイメージの使いどころ

マルチプラットフォームビルドの説明では、1つのOSで全OS分を作ることはできないと前置きしています。macOSのコード署名はmacOS上でしか動きません。ネイティブ依存を含むアプリは、prebuildを使わない限りそのOS上でしかコンパイルできません。

LinuxからWindows向けを作るにはWine 2.0以上が要ります。Dockerならelectronuserland/builder:wineを日付のタグで固定して使います。実務ではOSごとに分けたCIのジョブで作るのが確実です。

electron-updaterの自動更新実装とGitHub Releases公開

自動更新は、成果物と一緒に公開した更新情報ファイルを、配布済みのアプリが読みに行く仕組みです。

publish設定とlatest.ymlが自動更新の土台になる仕組み

publishのリファレンスに載っている公開先は、GitHub、S3、DigitalOceanのSpaces、Bitbucket、GitLab、Keygen、Snap Store、自前のWebサーバー（generic）です。GitHubを使う場合はrepo権限を持つトークンをGH_TOKENに入れます。作られるリリースは既定でdraft（下書き）です。

公開のたびに、Windowsはlatest.yml、macOSはlatest-mac.yml、Linuxはlatest-linux.ymlが作られます。genericを選んだ場合は、成果物とこれらのファイルを自分でサーバーへ上げる作業が必要です。S3互換で転送料のかからない保存先を探しているなら、Cloudflare R2の料金とS3互換の範囲も比較材料になります。

v26では、--publishを指定しないと公開の可否が自動で決まります。CIを検出するとonTagOrDraft、タグのpushならonTag、releaseという名前のnpmスクリプトがあるとalwaysです。この暗黙の挙動は非推奨で、v27で無効になると明記されています。

メインプロセスに書く自動更新チェックと利用者への再起動確認の実装例

自動更新のリファレンスの要点は、setFeedURLを呼ばないことです。接続先はビルド時にresourcesへ作られるapp-update.ymlに入っています。ダウンロード後に利用者の確認を取ってから再起動する例は次のとおりです。

// main.js（メインプロセス）
const { app, dialog } = require("electron")
const { autoUpdater } = require("electron-updater")

autoUpdater.autoDownload = true

autoUpdater.on("update-downloaded", async (info) => {
  const { response } = await dialog.showMessageBox({
    type: "info",
    buttons: ["再起動して更新", "後で"],
    message: `バージョン${info.version}をダウンロードしました`
  })
  if (response === 0) autoUpdater.quitAndInstall()
})

autoUpdater.on("error", (err) => {
  console.error("更新の確認に失敗しました", err)
})

app.whenReady().then(() => {
  // パッケージ化されていない開発中は更新を確認しない
  if (app.isPackaged) autoUpdater.checkForUpdates()
})

進み具合の表示に使うのは、download-progressイベントです。開発中に試すときは、プロジェクト直下にdev-app-update.ymlを置き、autoUpdater.forceDevUpdateConfig = trueを設定します。ただしリファレンスは、実際にインストールした版で試すよう勧めています。

Windowsで更新に対応する形式はNSISだけで、Squirrel.Windowsは対象外です。macOSはdmgに加えてzipが必要で、コード署名が無いと更新は動きません。

stagingPercentageで段階的に配り不具合版を取り下げる手順

全員へ一度に配るのが不安なときは、公開したlatest.ymlを手で編集し、stagingPercentage: 10のように割合を書き足します。この例では利用者の10%だけが更新を受け取ります。

配った版に不具合が見つかったら、同じ版番号で上書きしてはいけません。リファレンスは、壊れた版より大きい版番号で出し直すよう求めています。1.4.0に問題があれば、1.3.xの中身を1.4.1として公開します。

GitHub Actionsでタグのpush時にビルドと公開を回すワークフロー

GitHub Actionsの手引きは、3つのOSの行列でジョブを回し、タグのpushで公開する構成を示しています。これを最小限にしたのが次の例です。

# .github/workflows/release.yml
name: release
on:
  push:
    tags: ["v*.*.*"]
permissions:
  contents: write
jobs:
  build:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx electron-builder --publish always
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
          WIN_CSC_KEY_PASSWORD: ${{ secrets.WIN_CSC_KEY_PASSWORD }}

permissionsにcontents: writeが無いと「Resource not accessible by integration」で公開に失敗します。リリースは下書きで作られるので、正式な公開の前に確かめる対象は、3つのOSの成果物とlatest*.ymlがすべて揃っていることです。CIの基本的な書き方はGitHub Actionsでビルドと自動テストを設定する手順にまとめています。

Windowsのコード署名をelectron-builderに渡す環境変数と証明書の選び方

macOSの署名と公証は手順が長いので、Electron製Macアプリのコード署名とApple公証の手順に分けています。ここではWindowsだけを扱います。

WIN_CSC_LINKとWIN_CSC_KEY_PASSWORDで.pfxを渡す設定

コード署名のリファレンスでは、証明書のファイルパスかbase64の文字列をWIN_CSC_LINKに、パスワードをWIN_CSC_KEY_PASSWORDに入れます。未設定ならCSC_LINKとCSC_KEY_PASSWORDが使われるので、MacとWindowsで証明書が違うときはWIN_付きの方に分けます。

見落としやすいのは、証明書が見つからなくてもビルドが署名なしで進む点です。forceCodeSigning: trueを設定すると、署名できないときにビルドが失敗します。リリース用のジョブでは必ず有効にしてください。

electron-updaterがWindowsでも確かめる対象は、更新ファイルの署名です。WindowsのリファレンスによるとverifyUpdateCodeSignatureの既定はtrueで、証明書の発行先名（publisherName）がapp-update.ymlに書き込まれます。配布中のアプリはこの名前で新版の署名を照合するため、証明書の更新で名義の表記が変わるときは、更新が通るかを旧版から試してから公開してください。

未署名・OV・EVのSmartScreen警告とCI向け署名の選択肢

署名なしの.exeを初回起動したときに表示されるのは、SmartScreenによる「不明な発行元」としての警告です。OV証明書で署名しても、SmartScreenの信頼はダウンロード数に応じて積み上がるため、配り始めは警告が残ることがあります。EV証明書はこの期間を飛ばせる代わりにハードウェアのドングルが要り、多くのCIでは使えないとリファレンスは説明しています。

CIで署名を完結させたいなら、MicrosoftのAzure Trusted Signing（azureSignOptions）が候補で、AZURE_TENANT_IDなど3つの環境変数で渡します。社内だけで配る業務アプリでも、警告を見た利用者からの問い合わせを考えると署名は省きません。

electron-builderとElectron Forgeの選定とv27移行判断

Electronの配布ツールは、electron-builderとElectron公式のElectron Forgeの2つが主流です。同じプロジェクトでは片方に寄せます。

公式ツールを束ねるForgeと独自実装のbuilderという設計の差

Forgeの公式説明は、Forgeを「Electron Builderの代わりになるもの」と位置づけています。Forgeは既存のElectron公式ツールを1つのパイプラインにまとめ、builderは多くの処理を独自に実装している、という違いです。そのため、Electron側の新機能はForgeに先に入ります。npm registryではForgeの最新は8.0.1（2026年9月29日）で、Node.js 22.13.0以上が必要です。

自動更新の考え方も違います。Electron公式の更新ガイドが中心に置くのは、Electron組み込みのautoUpdaterと、Electronチームが無料で運営するupdate.electronjs.orgです。このサービスは公開のGitHubリポジトリが前提で、Windowsの更新はSquirrel.Windowsの形式です。非公開のリポジトリや自社サーバーから配るなら、electron-updaterの方が設定は短く済みます。

electron-builderを選ぶ条件と選ばない条件の線引き

electron-builderを選ぶのは、次のどれかに当てはまる案件です。Windowsに全ユーザー向けのNSISインストーラで配る、非公開リポジトリやS3・自社サーバーから自動更新を配る、段階配信で更新の影響を絞りたい、LinuxのAppImageやdebも同じ設定で作りたい、という場合です。

選ばないのは、Macだけに配る案件と、Electronの新しいビルド機能をすぐ使いたい新規案件です。前者はForgeと公証の手順で足ります。インストーラの大きさやメモリ使用量そのものが問題なら、配布ツールではなく土台の選び直しになるので、TauriとElectronの違いを最小アプリで比べた記事で判断してください。社内の業務端末へ配るデスクトップアプリを設計から任せたい場合は、業務用・Webアプリ開発の相談窓口で配布と更新の運用まで含めて見積もれます。

v27で変わる暗黙の公開・Node.js 22.12要件・設定移行コマンド

v27の変更点の説明によると、v27は未リリースで、全パッケージがネイティブのESMになり、Node.js 22.12.0以上が必須になります。v26の設定をv27の形に書き換えるelectron-builder migrate-schemaコマンドが加わりました。更新情報ファイル（latest*.yml）をEd25519で署名する機能も入り、既定で必須とされています。

Windowsの署名設定も、v27ではwin.signに統合されます。本番の案件は正式版が出るまでv26系に留めてください。今のうちに--publishを明示し、CIのNode.jsを22.12以上に上げておけば、移行はmigrate-schemaでの書き換えと動作確認で済みます。

よくある質問

electron-builderの導入や配布で、実装の担当者からよく出る質問をまとめました。

electron-builderでWindowsのexeを作るにはどうすればよいですか？

package.jsonのbuild.win.targetにnsisを書き、Windows上でnpx electron-builder --winを実行します。インストーラを通さず単体で起動する.exeが欲しい場合は、ターゲットをportableにします。portableは自動更新の対象外なので、更新を配るアプリではNSISを選んでください。

Electron Forgeで作ったプロジェクトをelectron-builderに移せますか？

移せます。electron-builderはForgeのmakerとしてNSISやAppImageを作るパッケージも配っているので、まずはForgeのまま配布形式だけを足す段階を挟めます。ただしForge連携の説明によると、公開・自動更新・コード署名はelectron-builderを主ツールにしないと使えません。自動更新が必要になった時点で、forge.config.jsの設定をpackage.jsonのbuildキーへ書き移してください。

electron-updaterの更新が開発中に動かないのはなぜですか？

接続先を書いたapp-update.ymlは、パッケージ化したときにresourcesへ作られるファイルです。electron .で起動した開発中のアプリには存在しません。開発中に試すなら、プロジェクト直下にdev-app-update.ymlを置き、autoUpdater.forceDevUpdateConfig = trueを設定します。公式は、実際にインストールした版で確かめる方法を勧めています。

GitHubの非公開リポジトリから自動更新を配れますか？

非公開リポジトリからの自動更新の配布は可能です。publishリファレンスのGitHubの設定にprivateの項目があり、トークンを使って取得します。ただしトークンを設定ファイルに書かないよう警告があり、アプリに埋め込めば利用者に取り出されます。社外へ配るアプリは、S3互換のストレージなど別の公開場所に置く方が安全です。

WindowsのPCだけでMac用のdmgも作れますか？

作れません。マルチプラットフォームビルドの説明でDockerが対応するのはLinuxとWindows向けだけで、macOSのコード署名もmacOS上でしか動きません。署名と公証を通さないdmgは、macOSの既定の設定では開く前に警告で止められるので、Mac向けはGitHub Actionsのmacos-latestなどmacOSのランナーで作ります。