macOS 封裝

私有 macOS API

Wails v3 預設使用公開的 macOS API。若要選用需要未公開 Apple API 的功能，請使用單一 Go 建置標籤private_mac_apis建置應用程式：

bash

wails3 build -tags private_mac_apis
EXTRA_TAGS=private_mac_apis wails3 dev
wails3 package GOOS=darwin EXTRA_TAGS=private_mac_apis

若直接使用 Go 建置，請使用go build -tags private_mac_apis .（正式環境則使用-tags production,private_mac_apis）。依賴私有行為的現有應用程式必須加入此標籤，才能保留該行為。此標籤僅適用於 macOS 桌面版建置。

如需受影響功能與選項值的完整清單、公開版本建置的確切備援行為、Liquid Glass 樣式對應，以及檢查器建置組合，請參閱私有 macOS API。若未使用此標籤，僅限私有 API 的操作不會執行任何動作；公開 Go API 則維持不變。

應用程式套件組合

將應用程式封裝為標準 macOS.app套件組合：

bash

wails3 package GOOS=darwin

這會建立包含下列項目的bin/<AppName>.app：

位於Contents/MacOS/中的已編譯二進位檔
位於Contents/Resources/中的應用程式圖示（來自icons.icns；若有資產目錄Assets.car，則從該目錄取得）
包含應用程式中繼資料的Info.plist

同步資料夾中的專案

某些 macOS 檔案提供者會在 .app 目錄中加入 Finder 中繼資料。這會導致 codesign 拒絕套件組合，或使簽章在簽署後失效。如果提供者會再次加入中繼資料，僅移除中繼資料並不足夠。

產生的 macOS 建置任務會檢查這種行為。偵測到後，Wails 會將專案產生的輸出目錄移至 ~/Library/Application Support/Wails/build-output/<project>-<hash> ，並以符號連結取代原本的輸出目錄。既有的輸出檔案會保留，封裝、簽署和開發模式仍使用 bin/<AppName>.app 路徑。CLI 會在移動時顯示本機儲存位置。

設定 WAILS_MACOS_OUTPUT_ROOT 可選擇其他不參與同步的本機儲存位置。移動目的地的根目錄必須與專案位於同一個檔案系統。明確指定在專案外部的 BIN_DIR 會依照設定使用。既有專案需要更新後的 build/darwin/Taskfile.yml ，才能使用這項處理方式。

散布時，請複製 bin/<AppName>.app 或建立 DMG。僅複製 bin 符號連結不會包含建置產物。直接執行 wails3 tool sign 命令時，如果輸入資料夾再次加入中繼資料，命令會回報錯誤；請先將該套件組合移至不參與同步的資料夾，再進行簽署。

套件組合資源

Contents/Resources/是 macOS 應用程式隨附唯讀檔案的標準位置。請將其用於較大的範本、種子資料、媒體、語言套件，或其他應按需開啟、而非透過embed編譯至 Go 可執行檔中的內容。

Wails 已將應用程式圖示放在此目錄中。若要加入自己的檔案，請將檔案放入build/resources/之類的來源目錄，然後在build/darwin/Taskfile.yml的create:app:bundle任務中加入複製步驟：

yaml

tasks:
  create:app:bundle:
    cmds:
      # Existing bundle creation commands...
      - |
          if [ -d build/resources ]; then
            cp -R build/resources/. "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/Resources/"
          fi

若使用 Taskfile 的darwin:run任務，請將對等的命令加入其run任務，並將目標設為{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Resources/。

從 Go 讀取資源

匯入 macOS 平台套件：

import (
	"io/fs"

	"github.com/wailsapp/wails/v3/pkg/mac"
)

對於小型檔案，請使用LoadResource：

func loadSplash() ([]byte, error) {
	return mac.LoadResource("images/splash.png")
}

對於較大的檔案，請使用ResourceFS。它會傳回以Contents/Resources為根目錄的io/fs.FS，讓呼叫端無須先將整個資源載入 Go 位元組切片，即可開啟並以串流方式處理資源：

func openCatalogue() (fs.File, error) {
	resources, err := mac.ResourceFS()
	if err != nil {
		return nil, err
	}

	return resources.Open("catalogue/defaults.json")
}

資源名稱是相對於Contents/Resources、以斜線分隔的路徑。除非可執行檔從.app/Contents/MacOS執行，否則ResourceFS與LoadResource會傳回mac.ErrNotInAppBundle。

請將套件組合資源視為不可變。變更已簽署應用程式內的檔案會使其程式碼簽章失效；下載、產生或可由使用者編輯的資料應改存於使用者的 Application Support 目錄。

通用二進位檔

同時為 Apple Silicon 與 Intel Mac 建置：

bash

wails3 task darwin:package:universal

這會建立可在兩種架構上原生執行的單一.app。通用二進位檔可在任何平台上建置；在 Linux 與 Windows 上，系統會自動使用wails3 tool lipo。

自訂套件組合

編輯build/darwin/Info.plist以自訂下列項目：

套件組合識別碼（CFBundleIdentifier）
應用程式名稱與版本
最低 macOS 版本
檔案關聯
URL 協定名稱

應用程式圖示由build/目錄中的資產產生。請使用generate:icons任務：

bash

wails3 task common:generate:icons

此任務使用build/appicon.png產生darwin/icons.icns與windows/icon.ico。在 macOS 上，您也可以提供build/appicon.icon（Icon Composer 格式）：此任務會傳遞-iconcomposerinput appicon.icon -macassetdir darwin，以從.icon檔案產生Assets.car與darwin/icons.icns（在非 macOS 平台上會略過）。若存在Assets.car，請執行update:build-assets任務，以便相應更新Info.plist與CFBundleIconName：

bash

wails3 task common:update:build-assets

若要從build/目錄手動執行圖示命令：

bash

cd build
wails3 generate icons -input appicon.png -macfilename darwin/icons.icns -windowsfilename windows/icon.ico -iconcomposerinput appicon.icon -macassetdir darwin

程式碼簽署

簽署應用程式以供發佈：

bash

# Using the wrapper (auto-detects platform)
wails3 sign GOOS=darwin

# Or using the task directly
wails3 task darwin:sign

在build/darwin/Taskfile.yml中設定簽署：

yaml

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  ENTITLEMENTS: "build/darwin/entitlements.plist"

公證

對於在 Mac App Store 以外發佈的應用程式，Apple 要求進行公證：

bash

wails3 task darwin:sign:notarize

首先儲存您的認證資訊。您可以執行互動式精靈（wails3 setup signing），或直接呼叫notarytool：

bash

xcrun notarytool store-credentials "my-notarize-profile" \
  --apple-id "you@email.com" \
  --team-id "TEAMID" \
  --password "app-specific-password"

在build/darwin/Taskfile.yml中進行設定：

yaml

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"

如需詳細資訊，請參閱簽署應用程式。

DMG 安裝程式

Wails 3隨附的範本提供wails3 task darwin:package:dmg。它會先建立.app，然後使用 DMG 程式庫建置具樣式的 DMG。DMG 預設使用帶有紅色龍形標誌與 WAILS 文字標誌的 Wails 品牌漸層背景。

bash

wails3 task darwin:package:dmg

較低階的darwin:create:dmg任務會從現有的.app套件組合建立 DMG，並可直接從 Taskfile 進行設定：

yaml

vars:
  # These are the template defaults; override them when needed.
  DMG_BACKGROUND: build/darwin/dmg-background.png
  DMG_VOLUME_ICON: build/darwin/icons.icns
  DMG_FILE_ICON: build/darwin/dmg-file-icon.icns
  DMG_WINDOW_WIDTH: 540
  DMG_WINDOW_HEIGHT: 380
  DMG_FILES: "Install.command=build/darwin/Install.command,README.txt=README.md"

預設配置

產生的 DMG 包含：

左側的應用程式套件組合
右側的Applications連結
大小為540×380像素的 Finder 視窗
圖示大小為96點，且每個圖示下方都有標籤
來自build/darwin/dmg-background.png的 Wails 品牌背景

應用程式與Applications圖示的位置會根據所設定的視窗尺寸決定，因此變更DMG_WINDOW_WIDTH或DMG_WINDOW_HEIGHT時，預設的雙圖示配置仍會維持等比例間距。為獲得最佳效果，請使用像素尺寸與 Finder 視窗相同的背景圖片。

取代 DMG 資產

build/darwin/下產生的檔案是一般的專案資源，可以替換：

DMG_BACKGROUND控制顯示在 Finder 視窗內容後方的影像。
DMG_VOLUME_ICON控制掛載卷宗所顯示的圖示。
DMG_FILE_ICON控制產生的.dmg檔案在 Finder 中顯示的圖示。

卷宗圖示與 DMG 檔案圖示是不同的資源。替換應用程式圖示不會自動替換其中任何一個。

新增額外檔案

使用DMG_FILES，將安裝程式指令碼、版本資訊、授權條款或其他資源連同應用程式一起加入。其值是以逗號分隔的name=path配對清單：

yaml

vars:
  DMG_FILES: "Install.command=build/darwin/Install.command,README.txt=README.md"

=之前的名稱是在 DMG 內顯示的檔名。=之後的路徑是專案中的來源檔案。開頭與結尾的空白會被忽略。

每個顯示名稱都必須是唯一的。額外檔案不能取代封裝工具已建立的項目，包括應用程式套件或Applications項目。名稱衝突會導致封裝失敗並顯示錯誤，而不會產生損壞的 DMG。

疑難排解

「應用程式已損毀，無法開啟」

此應用程式尚未簽署。您可以使用 Developer ID 憑證簽署，也可以讓使用者略過 Gatekeeper：

bash

xattr -cr /path/to/YourApp.app

公證失敗

常見問題：

認證資訊無效：重新執行xcrun notarytool store-credentials（或wails3 setup signing）
需要強化執行階段：如有需要，請確認權利設定包含com.apple.security.cs.allow-unsigned-executable-memory
缺少時間戳記：簽署程序應會自動加入時間戳記

交叉編譯的應用程式無法執行

交叉編譯的 macOS 二進位檔未經簽署。請將其傳輸至 Mac，並在測試前完成簽署：

bash

codesign --force --deep --sign - YourApp.app

無障礙功能

編輯此文件

私有 macOS API

應用程式套件組合

同步資料夾中的專案

套件組合資源

從 Go 讀取資源

通用二進位檔

自訂套件組合

程式碼簽署

公證

DMG 安裝程式

預設配置

取代 DMG 資產

新增額外檔案

疑難排解

「應用程式已損毀，無法開啟」

公證失敗

交叉編譯的應用程式無法執行