ビルドシステム

統合ビルドシステム

Wails は、Go コードのコンパイル、フロントエンドアセットのバンドル、すべての要素の単一実行ファイルへの埋め込み、プラットフォーム固有のビルドを、1 つのコマンドで処理する統合ビルドシステムを提供します。

wails3 build

出力：すべてが埋め込まれたネイティブ実行ファイル。

ビルドプロセスの概要

［ビルドプロセス図のプレースホルダー］

ビルドフェーズ

1. 解析フェーズ

Wails は Go コードをスキャンしてサービスを把握します：

type GreetService struct {
    prefix string
}

func (g *GreetService) Greet(name string) string {
    return g.prefix + name + "!"
}

Wails が抽出する情報：

• サービス名：GreetService
• メソッド名：Greet
• パラメーターの型：string
• 戻り値の型：string

用途：TypeScript バインディングの生成

2. 生成フェーズ

TypeScript バインディング

Wails は型安全なバインディングを生成します：

// Auto-generated: frontend/bindings/<full-go-import-path>/greetservice.js
// (TypeScript is also generated when you pass `-ts`. The shape below is the real
// runtime call format — numeric IDs via $Call.ByID, imported from /wails/runtime.js.)
import { Call as $Call } from "/wails/runtime.js";

export function Greet($0) {
    return $Call.ByID(1234567890, $0);
}

利点：

• 完全な型安全性
• IDE の自動補完
• コンパイル時のエラー検出
• JSDoc コメント

フロントエンドのビルド

フロントエンドバンドラー（Vite、webpack など）が実行されます：

# Vite example
vite build --outDir dist

実行される処理：

• JavaScript／TypeScript のコンパイル
• CSS の処理と圧縮
• アセットの最適化
• ソースマップの生成（開発時のみ）
• frontend/dist/への出力

3. コンパイルフェーズ

Go のコンパイル

Go コードは最適化を有効にしてコンパイルされます：

go build -ldflags="-s -w" -o myapp.exe

フラグ：

• -s：シンボルテーブルを削除
• -w：DWARF デバッグ情報を削除
• 結果：バイナリを小型化（約30% 削減）

プラットフォーム固有の形式：

• Windows：アイコンが埋め込まれた .exe
• macOS：.appバンドル構造
• Linux：ELF バイナリ

アセットの埋め込み

フロントエンドアセットは Go バイナリに埋め込まれます：

//go:embed frontend/dist
var assets embed.FS

結果：すべてを内包した単一の実行ファイル。

4. 出力

単一のネイティブバイナリ：

• Windows：myapp.exe（約 15MB）
• macOS：myapp.app（約 15MB）
• Linux：myapp（約 15MB）

依存関係なし（システムの WebView を除く）。

開発環境と本番環境

wails3 dev

wails3 build

ビルドコマンド

基本的なビルド

wails3 build

出力：bin/<APP_NAME>（Windowsではbin/<APP_NAME>.exe）。bin/ディレクトリはプロジェクトルートにあります。

wails3 buildはwails3 task buildの薄いラッパーです。転送するビルド時フラグは--tagsのみで、これはTaskfile変数EXTRA_TAGSになります：

# Build with extra Go build tags
wails3 build --tags "myfeature,gtk4"

wails3 buildには、-platform、-o、-skipbindings、-clean、-debug、-devbuild、-icon、-ldflags、-packageの各フラグはありません。クロスコンパイル、出力パス、アイコン、パッケージ化は、プロジェクトのTaskfile（Taskfile.yml + build/config.yml）で制御します。

クロスプラットフォームおよびプラットフォーム固有のビルド

プラットフォーム向けビルドは、build/Taskfile.<platform>.ymlで定義されたdarwin: / windows: / linux:名前空間配下のTaskfileタスクとして公開されています。例：

# macOS — universal binary
wails3 task darwin:build:universal

# macOS — current arch
wails3 task darwin:build

# Windows
wails3 task windows:build

# Linux
wails3 task linux:build

現在のプロジェクトで利用可能なすべてのタスクを表示するには、次を実行します：

wails3 task --list

アイコンとパッケージ化

ソースPNGからプラットフォーム用アイコン（build/icons.icns、build/icon.icoなど）を生成します：

wails3 generate icons -input appicon.png

プラットフォーム固有のインストーラーまたはパッケージをビルドします：

wails3 package           # uses the current Go build env
wails3 task linux:create:deb
wails3 task windows:package
wails3 task darwin:package:universal

ビルド設定

Taskfile.yml

Wails 3プロジェクトでは、ビルドオーケストレーターとしてTaskfileを使用します。ルートのTaskfile.ymlは、build/にあるプラットフォーム別のタスクファイルをインクルードします：

# Taskfile.yml (excerpt — the real templates are richer)
version: '3'

includes:
  common: ./build/Taskfile.yml
  darwin: ./build/Taskfile.darwin.yml
  windows: ./build/Taskfile.windows.yml
  linux: ./build/Taskfile.linux.yml

tasks:
  build:
    desc: Build the application
    cmds:
      - task: "{{OS}}:build"

wails3 task <name>またはtask <name>でタスクを実行します：

wails3 task windows:build
wails3 task darwin:package:universal
wails3 task linux:create:appimage

プロジェクト設定：build/config.yml

プロジェクトのメタデータ（名前、識別子、バージョン、Info.plistの値、NSIS設定、.desktopフィールド、カスタムプロトコルなど）はbuild/config.ymlにあります。Taskfileは、アイコン、マニフェスト、インストーラーなどを生成するときにこのファイルを読み取ります。Wails 3にはbuild/build.jsonファイルは存在しません。

# build/config.yml (illustrative)
info:
  productName: "My App"
  productIdentifier: "com.example.myapp"
  productVersion: "1.0.0"
  companyName: "Example Ltd."
  productDescription: "An application built with Wails"

この設定からプラットフォーム固有のビルドアセットを更新するには、wails3 generate build-assets（またはwails3 update build-assets）を実行します。

アセットの埋め込み

仕組み

WailsはGoのembedパッケージを使用します：

package main

import (
    "embed"
    "github.com/wailsapp/wails/v3/pkg/application"
)

//go:embed frontend/dist
var assets embed.FS

func main() {
    app := application.New(application.Options{
        Name:   "My App",
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assets),
        },
    })
    
    app.Window.New()
    app.Run()
}

ビルド時：

1. フロントエンドをfrontend/dist/にビルド
2. //go:embedディレクティブでファイルを取り込み
3. ファイルをバイナリにコンパイル
4. バイナリにすべてを格納

実行時：

1. アプリを起動
2. メモリからアセットを提供
3. アセットのディスクI/Oなし
4. 高速な読み込み

カスタムアセット

追加ファイルを埋め込みます：

//go:embed frontend/dist
var frontendAssets embed.FS

//go:embed data/*.json
var dataAssets embed.FS

//go:embed templates/*.html
var templateAssets embed.FS

ビルドの最適化

フロントエンドの最適化

Vite（デフォルト）：

// vite.config.js
export default {
  build: {
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true,  // Remove console.log
        drop_debugger: true,
      },
    },
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],  // Separate vendor bundle
        },
      },
    },
  },
}

結果：

• JavaScriptを縮小（約70%削減）
• CSSを縮小（約60%削減）
• 画像を最適化
• ツリーシェイキングを適用

Goの最適化

コンパイラフラグ：

-ldflags="-s -w"

• -s：シンボルテーブルを削除（約10%削減）
• -w：DWARFデバッグ情報を削除（約20%削減）

その他の最適化：

-ldflags="-s -w -X main.version=1.0.0"

• -X：ビルド時に変数の値を設定
• バージョン番号やビルド日時に便利です

バイナリ圧縮

UPX（任意）：

# After building
upx --best bin/myapp.exe

結果：

• サイズを約50%削減
• 起動がわずかに遅くなります（約100ms）
• macOSでは推奨されません（コード署名の問題があるため）

プラットフォーム固有のビルド

Windows

出力： myapp.exe

含まれるもの：

• アプリケーションアイコン
• バージョン情報
• マニフェスト（UAC設定）

アイコン：

# Generate platform icons from a source PNG
wails3 generate icons -input appicon.png -windowsfilename build/icon.ico

その後、Windowsのtool packageステップで、生成された.icoを実行可能ファイルに埋め込みます。

マニフェスト：

<!-- build/windows/manifest.xml -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <assemblyIdentity version="1.0.0.0" name="MyApp"/>
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
      </requestedPrivileges>
    </security>
  </trustInfo>
</assembly>

macOS

出力： myapp.app（アプリケーションバンドル）

構造：

myapp.app/
├── Contents/
│   ├── Info.plist          # App metadata
│   ├── MacOS/
│   │   └── myapp           # Binary
│   ├── Resources/
│   │   └── icon.icns       # Icon
│   └── _CodeSignature/     # Code signature (if signed)

Info.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleName</key>
    <string>My App</string>
    <key>CFBundleIdentifier</key>
    <string>com.example.myapp</string>
    <key>CFBundleVersion</key>
    <string>1.0.0</string>
</dict>
</plist>

ユニバーサルバイナリ：

macOSのTaskfileには、両方のアーキテクチャをビルドしてwails3 tool lipoで結合するdarwin:build:universalタスク（およびdarwin:package:universalタスク）が用意されています：

wails3 task darwin:build:universal

Linux

出力： myapp（ELFバイナリ）

依存関係：

• GTK3
• WebKitGTK

デスクトップファイル：

# myapp.desktop
[Desktop Entry]
Name=My App
Exec=/usr/bin/myapp
Icon=myapp
Type=Application
Categories=Utility;

インストール：

# Copy binary
sudo cp myapp /usr/bin/

# Copy desktop file
sudo cp myapp.desktop /usr/share/applications/

# Copy icon
sudo cp icon.png /usr/share/icons/hicolor/256x256/apps/myapp.png

ビルドパフォーマンス

一般的なビルド時間

ビルドの高速化

1. ビルドキャッシュを使用する：

# Go build cache is automatic
# Frontend cache (Vite)
npm run build  # Uses cache by default

2. 必要な処理だけを実行する：

# Pick the specific Taskfile target you actually need
wails3 task common:build:frontend   # rebuild only the frontend
wails3 task windows:build           # rebuild only the Windows binary

3. 並列ビルド（複数マシン／CI）：

v3でのLinux、Windows、macOS間のクロスコンパイルは、通常、Dockerのwails-crossコンテナ内、またはプラットフォームごとの専用ランナー上で行います。wails3 build自体のターゲットはホストOSです。サポートされているワークフローについては、クロスプラットフォームビルドを参照してください。

4. 高速なツールを使用する：

# Use esbuild instead of webpack
# (Vite uses esbuild by default)

トラブルシューティング

ビルドが失敗する

症状： wails3 build がエラーで終了する

一般的な原因：

1. Go のコンパイルエラー

# Check Go code compiles
go build

2. フロントエンドのビルドエラー

# Check frontend builds
cd frontend
npm run build

3. 依存関係が不足している

# Install dependencies
npm install
go mod download

バイナリが大きすぎる

症状： バイナリが 50 MB を超えている

解決策：

1. デバッグシンボルを削除する（同梱の Taskfile では、すでに -ldflags="-s -w" が go build に渡されています）。

2. 埋め込まれたアセットを確認する

# Remove unnecessary files from frontend/dist/
# Check for large images, videos, etc.

3. UPX 圧縮を使用する

upx --best bin/myapp.exe

ビルドが遅い

症状： ビルドに 1 分を超える時間がかかる

解決策：

1. ビルドキャッシュを使用する

• Go のキャッシュは自動的に使用される
• フロントエンドのキャッシュ（Vite）は自動的に使用される

2. 必要なタスクだけを実行する

wails3 task common:build:frontend
wails3 task windows:build

3. フロントエンドのビルドを最適化する

// vite.config.js
export default {
  build: {
    minify: 'esbuild',  // Faster than terser
  },
}

ベストプラクティス

✅ 推奨事項

• 開発中は wails3 dev を使用する — 高速に反復できる
• リリースには wails3 build を使用する — 出力が最適化される
• ビルドにバージョンを付ける — バージョンの埋め込みには -ldflags を使用する
• 対象プラットフォームでビルドをテストする — クロスコンパイルは完全ではない
• フロントエンドのビルドを高速に保つ — バンドラーの設定を最適化する
• ビルドキャッシュを使用する — 2 回目以降のビルドが高速になる

❌ 禁止事項

• build/ ディレクトリをコミットしない — .gitignore に追加する
• ビルドのテストを省略しない — リリース前に必ずテストする
• 不要なアセットを埋め込まない — バイナリを小さく保つ
• 本番環境ではデバッグビルドを使用しない — 最適化されたビルドを使用する
• コード署名を忘れない — 配布には必須

次のステップ

アプリケーションのビルド — ビルドとパッケージ化の詳細ガイド 詳細を見る →

クロスプラットフォームビルド — 1 台のマシンですべてのプラットフォーム向けにビルドする 詳細を見る →

インストーラーの作成 — エンドユーザー向けのインストーラーを作成する 詳細を見る →

ビルドについて質問がありますか？ Discord で質問するか、ビルド例を確認してください。