--- title: "electron-builderの使い方：Windows・Linux配布とelectron-updaterの自動更新【v26】" url: "https://www.issoh.co.jp/tech/details/19120/" published: 2026-10-31 updated: 2026-10-31 categories: ["Electron"] publisher: "株式会社一創" --- # 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の仕組みと始め方を解説した入門記事](https://www.issoh.co.jp/tech/details/3322/)で扱っているので、ここでは配布の段階だけを見ます。 ### パッケージ化・インストーラ生成・公開・自動更新を1本で担う範囲 [公式のGitHubリポジトリ](https://github.com/electron-userland/electron-builder)では、macOSのdmg・pkg、Linuxのdeb・rpm・AppImage・snapなど多数の形式に対応すると説明されています。担う作業は、asarアーカイブへの固め、インストーラ作成、署名、公開、更新情報ファイルの生成です。 自動更新の実行部分は別パッケージのelectron-updaterが受け持ちます。electron-builderが作った`app-update.yml`と`latest.yml`を、配布後のアプリが読む分担です。 ### npm registryのlatest・nextタグで確認する安定版と先行版 [npm registryの記録](https://registry.npmjs.org/electron-builder)では、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](https://registry.npmjs.org/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の設定リファレンス](https://www.electron.build/v26/docs/configuration/)によると、ほかに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のリファレンス](https://www.electron.build/v26/docs/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のリファレンス](https://www.electron.build/v26/docs/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イメージの使いどころ [マルチプラットフォームビルドの説明](https://www.electron.build/v26/docs/features/multi-platform-build/)では、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のリファレンス](https://www.electron.build/v26/docs/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互換の範囲](https://www.issoh.co.jp/tech/details/7455/)も比較材料になります。 v26では、`--publish`を指定しないと公開の可否が自動で決まります。CIを検出すると`onTagOrDraft`、タグのpushなら`onTag`、`release`という名前のnpmスクリプトがあると`always`です。この暗黙の挙動は非推奨で、v27で無効になると明記されています。 ### メインプロセスに書く自動更新チェックと利用者への再起動確認の実装例 [自動更新のリファレンス](https://www.electron.build/v26/docs/features/auto-update/)の要点は、`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の手引き](https://www.electron.build/v26/docs/features/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でビルドと自動テストを設定する手順](https://www.issoh.co.jp/tech/details/2497/)にまとめています。 ## Windowsのコード署名をelectron-builderに渡す環境変数と証明書の選び方 macOSの署名と公証は手順が長いので、[Electron製Macアプリのコード署名とApple公証の手順](https://www.issoh.co.jp/tech/details/6874/)に分けています。ここではWindowsだけを扱います。 ### WIN\_CSC\_LINKとWIN\_CSC\_KEY\_PASSWORDで.pfxを渡す設定 [コード署名のリファレンス](https://www.electron.build/v26/docs/features/code-signing/)では、証明書のファイルパスかbase64の文字列を`WIN_CSC_LINK`に、パスワードを`WIN_CSC_KEY_PASSWORD`に入れます。未設定なら`CSC_LINK`と`CSC_KEY_PASSWORD`が使われるので、MacとWindowsで証明書が違うときは`WIN_`付きの方に分けます。 見落としやすいのは、証明書が見つからなくてもビルドが署名なしで進む点です。`forceCodeSigning: true`を設定すると、署名できないときにビルドが失敗します。リリース用のジョブでは必ず有効にしてください。 electron-updaterがWindowsでも確かめる対象は、更新ファイルの署名です。[Windowsのリファレンス](https://www.electron.build/v26/docs/win/)によると`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の公式説明](https://www.electronforge.io/core-concepts/why-electron-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公式の更新ガイド](https://www.electronjs.org/docs/latest/tutorial/updates)が中心に置くのは、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の違いを最小アプリで比べた記事](https://www.issoh.co.jp/tech/details/4114/)で判断してください。社内の業務端末へ配るデスクトップアプリを設計から任せたい場合は、[業務用・Webアプリ開発の相談窓口](https://www.issoh.co.jp/service/apps/business/)で配布と更新の運用まで含めて見積もれます。 ### v27で変わる暗黙の公開・Node.js 22.12要件・設定移行コマンド [v27の変更点の説明](https://www.electron.build/docs/migration/whats-new-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連携の説明](https://www.electron.build/v26/docs/features/electron-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のランナーで作ります。 ## 関連記事 - [Electronとは？Web技術でデスクトップアプリを作る仕組みと始め方](https://www.issoh.co.jp/tech/details/3322/)：配布の前段となる仕組み - [Electron製Macアプリのビルド・コード署名・Apple公証](https://www.issoh.co.jp/tech/details/6874/)：macOSの署名と公証 - [Electronはオワコンか？採用状況・将来性とUIの作り方](https://www.issoh.co.jp/tech/details/11692/)：UIの組み立て方 - [Tauriとは？Electronとの違い・将来性](https://www.issoh.co.jp/tech/details/4114/)：サイズが問題になるときの代替 - [GitHub Actionsでビルド・自動テストを設定する方法](https://www.issoh.co.jp/tech/details/2497/)：CIの書き方 --- 出典: [electron-builderの使い方：Windows・Linux配布とelectron-updaterの自動更新【v26】]()（株式会社一創）