はじめに
クロスプラットフォーム対応ということで、初めてElectron-viteを使ってWindowsで動作するデスクトップアプリを作成しました。しかし、Windows用のアプリをMacでビルドしようとすると失敗してしまう問題に遭遇。その解決までの手順をまとめました。
同じ問題に直面している方の参考になれば幸いです。
重要：ローカル環境でのクロスビルドについて
Apple Silicon Mac（ARM64）のローカル環境では、Windows用（x64）のビルドが失敗します。
ただし、GitHub Actionsなどのクラウド環境では正常にビルドできることを確認済みです。
何が起きているのか？
問題の正体：node-gyp
私のケースではnode-gypが原因でした。
同様の問題に遭遇している方も、多くの場合node-gypが関係していると思われます。
node-gypとは？
Node-gypは、Node.jsのネイティブアドオンモジュールをクロスプラットフォームでコンパイルするためのコマンドラインツールです。ネイティブアドオンは、CやC++で記述されたライブラリで、Node.jsから直接呼び出すことができます。これにより、JavaScriptでは実行が困難な低レベルな処理を高速化できます。
つまり、デスクトップアプリとして必要な低レベルな処理を実行するための重要なツールです。
ほとんどのElectronアプリでは必須ではありませんが、sqlite3、keytar、sharp、シリアルポート関連などのネイティブモジュール（CやC++で書かれたコンパイルが必要なnpmパッケージ）に依存している場合には、このnode-gypが必要になります。
なぜnode-gypが問題になるのか？
アーキテクチャの違いが原因
MacとWindowsで使用されているプロセッサのアーキテクチャの違いが主な原因です。
| アーキテクチャ | ARM64 | x64 |
|---|---|---|
| プロセッサ | Apple Silicon (M1, M2, M3など) | Intel/AMD（Core i7など） |
| 主な搭載機器 | 最新のMac | Windows PC、Intel Mac |
具体的な問題
ARM64環境（Apple Silicon Mac）でx64用のビルドを実行すると、ネイティブモジュールのコンパイルが失敗します。これは、異なるCPUアーキテクチャ向けのバイナリを生成しようとするためです。
Intel Macについて
Apple Silicon登場前のIntel Coreを使用したIntel Mac（x64アーキテクチャ）では、理論上この問題は発生しないはずです。ただし、手元にIntel Macがないため、動作確認は行えていません🙇
解決手順１：Windows PCでビルドする
必要な環境構築
- Windows PCを用意
- x64アーキテクチャ搭載のWindows PC
- 開発環境のセットアップ
- Visual Studio Codeをインストール
- Visual Studio（C++開発環境）をインストール
- node-gypがC++コンパイラを必要とするため
- Python環境の準備
- Python 3.9.13をインストール
- node-gypの依存関係でPython 3.9系が必要
- 3.9系の中では比較的新しいバージョンを選択
プロジェクトの移行とビルド
-
ソースコードの準備
- 方法A：Git Clone
bash git clone [あなたのリポジトリURL]
- 方法B：ファイル転送
- MacでプロジェクトをZIP化
- Windows PCに転送してVSCodeで開く -
依存関係のインストール
bash npm install -
Windows用ビルドの実行
bash npm run build:win
（package.jsonで設定したWindows用のビルドスクリプトを実行）
ビルドが成功したら
上記の手順で、Windows用の.exeファイルが生成されるはずです。
もし手順に不足があったり、エラーが発生した場合は、コメントでご指摘いただけますと幸いです🙇
解決方法2：GitHub Actions（推奨）
Windows PCが不要で、クラウド環境で自動ビルドする方法です。実際に動作確認済みで、最も手軽な解決策といえます。
GitHub Actionsのメリット
🔹 Windows PCが不要：クラウド環境で自動ビルド（ありがたい）
🔹 自動化：プッシュするだけで全プラットフォーム用のビルドが完了（今回はLinux用のビルドは意図的に入れています）
設定手順
1. ワークフローファイルの作成
プロジェクトのルートに .github/workflows/build.yml を作成
私はdevにPR出すタイミングで確認したいのでbranchesに追加していますが、自分の開発フローで必要なブランチに調整してください。
mainに直接pushすることないので不要かとも思いますが一応入れてます
name: Build Electron-vite App
on:
push:
branches: [ main, dev ]
pull_request:
branches: [ main, dev ]
workflow_dispatch:
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
include:
- os: windows-latest
platform: win
output: '**/*.exe'
- os: macos-latest
platform: mac
output: '**/*.dmg'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Setup Python (macOS only)
if: matrix.os == 'macos-latest'
uses: actions/setup-python@v4
with:
python-version: '3.9.13'
- name: Install dependencies (with rebuild skip)
run: npm ci --ignore-scripts
- name: Rebuild native modules
run: npm run postinstall
env:
npm_config_cache: /tmp/.npm
ELECTRON_CACHE: /tmp/.cache/electron
ELECTRON_BUILDER_CACHE: /tmp/.cache/electron-builder
- name: Build for ${{ matrix.platform }}
run: npm run build:${{ matrix.platform }}
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: app-name-${{ matrix.platform }}
path: |
dist/${{ matrix.output }}
retention-days: 30
2. package.jsonのbuild設定
Vite + Vueなのでdistですが、outputなどの場合もあると思いますので、調整してください。
"build": {
"appId": "com.yourcompany.yourapp",
"productName": "Your App Name",
"directories": {
"output": "dist"
},
"files": [
"out/**/*"
],
"win": {
"target": [
{
"target": "nsis",
"arch": ["x64"]
}
]
},
"mac": {
"target": [
{
"target": "dmg",
"arch": ["x64", "arm64"]
}
]
}
}
3. 実行方法
- 上記ファイルをリポジトリに追加
- GitHubにプッシュ
- Actionsタブで実行状況を確認
- 完了後、Artifactsからビルドファイルをダウンロード
(ArtifactsはActionタブの成功したActionをクリックすると遷移できるページにあります)
GitHub Actionsでの重要ポイント
- Python 3.9.13：記事で紹介したのと同じバージョンを使用
- Node.js 20：依存関係に対応（流石にもう18ではダメっぽかった）
- npm ci --ignore-scripts：postinstallを別途実行してnode-gyp問題を回避
macOS配布時の注意点
GitHub ActionsでビルドしたmacOS用アプリにはセキュリティーの制限があります。
GitHub Actionsに限った話ではなく、Macが外部で作られているし署名もないと判断した場合は全て警告が出ます。
問題：コード署名なしの警告
「Macに損害を与えたり、プライバシーを侵害する可能性のある
マルウェアが含まれていないことを検証できませんでした。」
解決方法
- 個人利用の場合
- ローカル環境（Mac）でビルドすることを推奨
- または、システム環境設定で「セキュリティとプライバシー」→「一般」で許可
- システム環境設定から「セキュリティとプライバシー」→ 「このまま使用」などで開く
- 配布・商用利用の場合
- Apple Developer Program(年間99ドル）への登録が必要
- コード署名とNotarization（公証）の設定が必要
- GitHub Actionsでの自動署名も可能（要設定）
Windows用アプリにはこの制限はないため、GitHub Actionsで問題なく配布可能です。
推奨アプローチ
開発段階や配布目的に応じて使い分けることをお勧めします
開発・テスト段階
- GitHub Actionsを活用してWindows/Mac両方のビルドを自動化（テストも兼ねる）
- Macで開発している人はローカルでビルドして動作確認した方が良さそう
配布段階
- Windows用：GitHub Actionsでビルドしたファイルをそのまま配布可能
- macOS用：
- 個人利用→ローカル（Mac）でビルド
- 商用配布→Apple Developer Programでコード署名後、GitHub Actionsも活用可能
| 方法 | 向いているケース | Windows PC | macOS配布 |
|---|---|---|---|
| GitHub Actions | 継続的ビルド、Windows配布、開発用 | 不要 ✅ | 署名必要 ⚠️ |
| ローカルビルド(Mac) | macOS配布、個人利用 | --- | 署名不要 ✅ |
| ローカルビルド(Win) | 確実性重視、一回限り | 必要 ❌ | 対象外 - |
その他の代替案
AIに聞いたら下の方法も返ってきましたが、個人的にはGithub Actionsが一番簡単で手軽だと感じたので何かしらの必要性に駆られない限り以下の方法を使用することはなさそうかなと思います。
- Dockerを使用したクロスプラットフォームビルド
- クラウドサービス（AWS、Azure等）での仮想Windows環境
まとめ
今回は、electron-viteを使ったクロスプラットフォーム開発で、ローカル環境でのアーキテクチャの違いという壁にぶつかりました。GitHub Actionsという解決策に気づくまでWindowsの実機でビルドしたりと、時間を要してしまいましたが最終的に便利な方法に辿り着けてよかったです。
特に、Windows PCを持っていなくてもWindows用アプリが作れるのは大きなメリットだと感じました。（動作検証ができないので、このままユーザーに提供するわけにはいきませんが）一方、macOS用の配布には署名の課題がありますが、開発段階では十分だと思いました。
Web開発とは異なるデスクトップアプリ開発の醍醐味を味わえて、とても楽しい経験でした。（Webの言語を使えるので、書く内容は一緒なのですが、設定周りとできることが異なりました。）
Web開発しかやったことがないけど、デスクトップアプリを作ってみたいという方は、ぜひチャレンジしてみてください！思っているより簡単にできました。
この記事が同じ問題で困っている方の助けになれば幸いです🙇