建置系統 · Wails

統一建置系統

Wails 提供統一建置系統，只需一道命令即可編譯 Go 程式碼、封裝前端資產、將所有內容嵌入單一執行檔，並處理平台專屬建置。

bash

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 會產生型別安全的繫結：

javascript

// 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 等）：

bash

# Vite example
vite build --outDir dist

執行內容：

編譯 JavaScript/TypeScript
處理並壓縮 CSS
最佳化資產
產生來源對應表（僅限開發環境）
輸出至frontend/dist/

3. 編譯階段

Go 編譯

以最佳化選項編譯 Go 程式碼：

bash

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 除外）。

開發環境與正式環境

針對速度最佳化：

bash

wails3 dev

執行內容：

啟動前端開發伺服器（Vite 預設使用連接埠9245）
不進行最佳化即編譯 Go
啟動應用程式並將其指向開發伺服器
啟用熱重載
包含來源對應表

特性：

快速重新建置（前端變更耗時<1 秒）
不嵌入資產（由開發伺服器提供）
包含偵錯符號
啟用來源對應表
詳細記錄

檔案大小：較大（包含偵錯符號時約 50MB）

針對大小和效能最佳化：

bash

wails3 build

執行內容：

為正式環境建置前端（最小化）
啟用最佳化來編譯 Go
移除偵錯符號
嵌入資產
建立單一二進位檔

特性：

最佳化的程式碼（已最小化並移除未使用的程式碼）
已嵌入資產（無外部檔案）
已移除偵錯符號
無原始碼對應檔
最少量的記錄

檔案大小：較小（約 15MB）

建置命令

基本建置

bash

wails3 build

輸出：bin/<APP_NAME>（在 Windows 上則為bin/<APP_NAME>.exe）。bin/目錄位於專案根目錄。

wails3 build是wails3 task build的薄包裝。它唯一會轉送的建置階段旗標是--tags，該旗標會成為EXTRA_TAGS Taskfile 變數：

bash

# 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）控制。

跨平台與平台專屬建置

平台建置會以 Taskfile 任務的形式公開於darwin: / windows: / linux:命名空間下（定義於build/Taskfile.<platform>.yml）。例如：

bash

# 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

若要查看目前專案中的所有可用任務：

bash

wails3 task --list

圖示與封裝

從來源 PNG 產生平台圖示（build/icons.icns、build/icon.ico等）：

bash

wails3 generate icons -input appicon.png

建置平台專屬的安裝程式／套件：

bash

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/的各平台任務檔案：

yaml

# 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>執行任務：

bash

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檔案。

yaml

# 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()
}

建置時：

將前端建置至frontend/dist/
//go:embed指令會納入檔案
將檔案編譯進二進位檔
二進位檔包含所有內容

執行階段：

應用程式啟動
從記憶體提供資產
資產不需要磁碟 I/O
快速載入

自訂資產

嵌入其他檔案：

//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（預設）：

javascript

// 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 最佳化

編譯器旗標：

bash

-ldflags="-s -w"

-s：移除符號表（大小減少約10%）
-w：移除 DWARF 偵錯資訊（大小減少約20%）

其他最佳化：

bash

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

-X：在建置時設定變數值
適用於版本號、建置日期

二進位檔壓縮

UPX（選用）：

bash

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

結果：

大小減少約50%
啟動速度稍慢（約 100ms）
不建議用於 macOS（程式碼簽署問題）

平台特定建置

Windows

輸出：myapp.exe

包含：

應用程式圖示
版本資訊
資訊清單（UAC 設定）

圖示：

bash

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

接著，Windows 的tool package步驟會將產生的.ico嵌入可執行檔。

資訊清單：

xml

<!-- 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（應用程式套件）

結構：

text

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

Info.plist：

xml

<?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 提供darwin:build:universal（以及darwin:package:universal）任務，可建置這兩種架構，並透過wails3 tool lipo將其合併：

bash

wails3 task darwin:build:universal

Linux

輸出：myapp（ELF 二進位檔）

相依項目：

GTK3
WebKitGTK

桌面項目檔：

ini

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

安裝：

bash

# 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

建置效能

一般建置時間

階段	時間	備註
分析	<1s	掃描 Go 程式碼
繫結產生	<1s	產生 TypeScript 程式碼
前端建置	5-30s	取決於專案大小
Go 編譯	2-10s	取決於程式碼大小
資產嵌入	<1s	嵌入前端資產
總計	10-45s	首次建置
增量建置	5-15s	後續建置

加快建置速度

1. 使用建置快取：

bash

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

2. 僅執行所需項目：

bash

# 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本身以主機作業系統為目標。請參閱跨平台建置，瞭解支援的工作流程。

4。使用速度更快的工具：

bash

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

疑難排解

建置失敗

症狀：wails3 build結束時發生錯誤

常見原因：

Go 編譯錯誤

bash

# Check Go code compiles
go build

前端建置錯誤

bash

# Check frontend builds
cd frontend
npm run build

缺少相依套件

bash

# Install dependencies
npm install
go mod download

二進位檔過大

症狀：二進位檔大於 50 MB

解決方法：

移除偵錯符號（隨附的 Taskfile 已將-ldflags="-s -w"傳給go build）。
檢查嵌入的資產

bash

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

使用 UPX 壓縮

bash

upx --best bin/myapp.exe

建置速度緩慢

症狀：建置耗時超過1分鐘

解決方法：

使用建置快取

Go 會自動使用快取
前端快取（Vite）會自動啟用

只執行所需的工作

bash

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

最佳化前端建置

javascript

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

最佳實務

✅ 建議做法

在開發期間使用wails3 dev — 快速迭代
發行時使用wails3 build — 產生最佳化輸出
為建置加上版本資訊 — 使用-ldflags嵌入版本
在目標平台上測試建置 — 交叉編譯並不完美
維持前端建置速度 — 最佳化打包工具設定
使用建置快取 — 加快後續建置速度

❌ 請勿

請勿提交build/目錄 — 將其加入.gitignore
請勿略過建置測試 — 發行前務必測試
請勿嵌入不必要的資產 — 縮小二進位檔
請勿在正式環境中使用偵錯建置 — 請使用最佳化建置
請勿忘記程式碼簽署 — 發佈時必須進行簽署

後續步驟

建置應用程式 — 建置與封裝的詳細指南深入瞭解 →

跨平台建置 — 從一台電腦為所有平台進行建置深入瞭解 →

建立安裝程式 — 為使用者建立安裝程式深入瞭解 →

對建置有疑問嗎？請到Discord提問，或查看建置範例。

統一建置系統

建置流程概覽

建置階段

1. 分析階段

2. 產生階段

TypeScript 繫結

前端建置

3. 編譯階段

Go 編譯

資產嵌入

4. 輸出

開發環境與正式環境

建置命令

基本建置

跨平台與平台專屬建置

圖示與封裝

建置設定

Taskfile.yml

專案設定：build/config.yml

資產嵌入

運作方式

自訂資產

建置最佳化

前端最佳化

Go 最佳化

二進位檔壓縮

平台特定建置

Windows

macOS

Linux

建置效能

一般建置時間

加快建置速度

疑難排解

建置失敗

二進位檔過大

建置速度緩慢

最佳實務

✅ 建議做法

❌ 請勿

後續步驟

專案設定：`build/config.yml`