使用 Winapp CLI 搭配 Rust

本指南示範如何在 Rust 應用程式中使用 winapp CLI，以套件身分來除錯及將應用程式封裝為 MSIX。

想要完整的工作範例，可以參考這個倉庫中的 Rust 範例。

套件身份是 Windows app 模型中的核心概念。它讓你的應用程式能存取特定的 Windows API（例如通知、安全、AI API 等）、乾淨安裝/卸載體驗等等。

標準執行檔（例如用 cargo build建立的）沒有套件身份。本指南說明如何新增它用於除錯，然後再打包以供發佈。

先決條件

Rust 工具鏈：使用 rustup 或 winget 安裝 Rust（若已安裝則更新）：
```
winget install Rustlang.Rustup --source winget
```
Winapp CLI：透過 Winget 安裝工具 winapp （若已安裝則更新）：
```
winget install microsoft.winappcli --source winget
```

1. 建立新的 Rust 應用程式

先從建立一個簡單的 Rust 應用程式開始：

cargo new rust-app
cd rust-app

執行它以確保一切正常：

cargo run

輸出應該是「哈囉，世界！」

2. 更新代碼以驗證身份

我們會更新應用程式，以檢查它是否運行於具有套件識別的狀態。這將幫助我們在後續步驟中驗證身份是否正確運作。我們會使用 windows 函式庫來存取 Windows API。

首先，執行以下命令將 windows 依賴性加入到 Cargo.toml 中：

cargo add windows --features ApplicationModel

這新增了 Windows API 綁定，並附有 ApplicationModel 功能，讓我們能存取 Package API 來驗證身份。

接著，將整個 src/main.rs 內容替換成以下程式碼。此程式碼嘗試取得目前的套件身份。若成功，則會列印封包族名;否則，會顯示「未包裝」。

Note

full sample 也包含了若身份存在時會顯示 Windows 通知的程式碼，但本指南將著重於身份檢查。

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3. 無身份運行

現在，照常建立並執行應用程式：

cargo run

你應該會看到輸出「未打包」。這確認了標準執行檔在沒有任何套件身份的情況下執行。

4. 使用 Winapp CLI 初始化 Project

在一次性操作中，winapp init 指令會設定您所需的所有內容，包括應用程式清單和資產。清單定義了你應用程式的身份（名稱、發佈者、版本），Windows 用來授權 API 存取。

執行以下指令並依照提示操作：

winapp init

出現提示時：

套件名稱：按 Enter 以接受預設（rust-app）
Publisher name：按 Enter 接受預設或輸入你的名字
版本：按下 "Enter" 以接受 1.0.0.0
說明：按 Enter 接受預設或輸入描述
設定 SDK：選擇「不要設定 SDK」（Rust 使用自己的 windows crate，不是 C++ SDK 標頭）

這個命令將會執行以下作業：

Create Package.appxmanifest — 定義你應用程式身份的清單
建立 Assets 資料夾 — MSIX 包裝與商店提交所需的圖示

Note

因為沒有管理任何 SDK 套件，所以不會建立 winapp.yaml——Rust 通過 Cargo 使用 windows crate，因此沒有任何對象給 winapp restore/update 追蹤。

你可以開啟 Package.appxmanifest 來進一步自訂屬性，例如顯示名稱、發佈者和功能。

新增執行別名（用於控制台應用程式）

因為 cargo new 建立主控台應用程式，我們需要在清單中加入執行別名。沒有它時， winapp run 會透過 AUMID 啟動應用程式，開啟一個新視窗——而當主控台應用程式結束時，該視窗會立即關閉，吞噬所有輸出。

別名也讓使用者安裝 MSIX 後，能在任何終端機以名稱執行你的應用程式。清單會註冊一個別名，例如 rust-app.exe （預設為你專案的執行檔名稱），使用者可以呼叫為 rust-app 或 rust-app.exe。

如果你在做 UI 應用程式（Rust 應用程式，會渲染自己的視窗），可以跳過這步驟。這些應用程式在預設的 AUMID 啟動下運作正常。

加上別名：

winapp manifest add-alias

這會在Package.appxmanifest中加入一個uap5:ExecutionAlias元素。

5. 利用身份驗證除錯

若要測試需要身份識別的功能（如通知），但不完全包裝應用程式，請使用 winapp run。這會將整個建置輸出資料夾註冊為一個鬆散的版面套件——就像真實的 MSIX 安裝一樣——然後啟動應用程式。除錯不需要憑證或簽署。

建立執行檔：
```
cargo build
```
以身份行事：
```
winapp run .\target\debug --with-alias
```

這個 --with-alias 旗標會透過執行別名啟動應用程式，因此主控台輸出會留在目前的終端機。這需要我們在步驟 4 中加入的uap5:ExecutionAlias

Note

winapp run 同時也會在你的系統上註冊包裹。這也是為什麼當你在第 6 步嘗試安裝時，MSIX 可能會顯示為「已安裝」。完成後，請使用 winapp unregister 清理開發套件。

你現在應該會看到類似的輸出：

Package Family Name: rust-app_12345abcde

這能確認你的應用程式是以有效的套件身份執行！

小提示

關於進階除錯工作流程（附加除錯器、IDE 設定、啟動除錯），請參閱除錯指南。

6. MSIX 封裝

當你準備好發佈應用程式時，可以用相同的清單打包成 MSIX。 MSIX 提供乾淨安裝/卸載、自動更新及可信賴的安裝體驗。

準備套件目錄

首先，將應用程式建置在發佈模式以達到最佳效能：

cargo build --release

接著，建立一個只包含發行所需檔案的目錄。資料夾 target\release 包含不屬於你應用程式的建置產物——我們只需要執行檔：

mkdir dist
copy .\target\release\rust-app.exe .\dist\

產生開發證書

MSIX 套件必須簽署。本地測試時，產生自簽開發憑證：

winapp cert generate --if-exists skip

Important

證書的發行者必須與您 Publisher 中的 Package.appxmanifest 相符。 cert generate指令會自動從你的清單讀取這些資訊。

簽名與包裝

現在你可以一步打包並簽收：

winapp pack .\dist --cert .\devcert.pfx

注意：pack 命令會自動使用目前目錄中的 Package.appxmanifest，並在打包前將它複製到目標資料夾。產生的 .msix 檔案會放在目前的目錄中。

安裝憑證

在安裝 MSIX 套件之前，你需要先信任你機器上的開發憑證。以管理員身份執行這個指令（你只需要在每個憑證上執行一次）：

winapp cert install .\devcert.pfx

安裝並執行

Note

如果你在步驟5使用 winapp run 過，包裹可能已經在你的系統上註冊了。使用 winapp unregister 先移除開發註冊，然後再安裝正式發行套件。

透過雙擊產生 .msix 的檔案安裝套件，或透過 PowerShell 安裝：

Add-AppxPackage .\rust-app.msix

現在你可以在終端機的任何地方輸入以下關鍵字來執行應用程式：

rust-app

你應該會看到「Package Family Name」的輸出，確認它已安裝並以身份執行。

小提示

如果你需要重新打包應用程式（例如程式碼變更後），在再次執行winapp pack前，先在你的Package.appxmanifest中增加Version。 Windows 需要更高的版本號才能更新已安裝的套件。

Tips

一旦準備好分發，你可以用憑證授權中心的程式碼簽署憑證來簽署 MSIX，這樣使用者就不必安裝自簽憑證
Microsoft Store 會幫你簽署 MSIX，提交前不需要簽名。
你可能需要建立多個 MSIX 套件，分別針對你支援的每種架構（x64、Arm64）

後續步驟

透過 winget 發佈：請將您的 MSIX 提交至 Windows 封裝管理員社群倉庫
發佈至Microsoft Store：請使用 winapp store 提交您的套件
設定 CI/CD：使用 setup-WinAppCli GitHub Action 在管線中自動化打包
探索Windows API：透過套件身份，你現在可以使用Notifications、on-device AI，以及其他依賴身份相關的 API

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-12

使用 Winapp CLI 搭配 Rust

先決條件

1. 建立新的 Rust 應用程式

2. 更新代碼以驗證身份

3. 無身份運行

4. 使用 Winapp CLI 初始化 Project

新增執行別名（用於控制台應用程式）

5. 利用身份驗證除錯

6. MSIX 封裝

準備套件目錄

產生開發證書

簽名與包裝

安裝憑證

安裝並執行

Tips

後續步驟

意見反應

其他資源