這很重要
Windows 應用程式開發 CLI 目前處於 公開預覽。 功能與指令可能會在最終版本前有所變動。
本頁記錄了所有可用的 winapp CLI 指令。
全域選項
所有指令都支援以下全域選項：
| Option | 說明 |
|---|---|
--verbose、-v |
啟用詳細日誌記錄輸出 |
--quiet、-q |
抑制進度訊息 |
--help、-h |
顯示指令求助 |
全域快取目錄
WinApp 建立一個目錄來快取可在多個專案間共享的檔案。 根據預設，這會是 $UserProfile/.winapp。
若要使用不同位置，請設定 WINAPP_CLI_CACHE_DIRECTORY 環境變數：
$env:WINAPP_CLI_CACHE_DIRECTORY = "d:\temp\.winapp"
設定指令
初始化
用 Windows SDK、Windows App SDK，和現代 Windows 開發所需的資產來初始化目錄。
winapp init [base-directory] [options]
引數：
| Argument | 說明 |
|---|---|
base-directory |
應用程式/工作區的基礎/根目錄（預設：目前目錄） |
選項：
| Option | 說明 |
|---|---|
--config-dir <path> |
目錄用以讀取/儲存設定（預設：目前目錄） |
--setup-sdks |
SDK 安裝模式： stable （預設）、 preview、 experimental或 none |
--ignore-config、--no-config |
不要用設定檔來管理版本 |
--no-gitignore |
不要更新 .gitignore 檔案 |
--use-defaults、--no-prompt |
不要顯示任何提示，並對所有提示使用預設設定 |
--config-only |
只處理設定檔操作，跳過套件安裝 |
它的用途：
- 建立
winapp.yaml設定檔 - 下載 Windows SDK 及 Windows App SDK 套件
- 產生 C++/WinRT 標頭與二進位檔
- 建立 AppxManifest.xml
- 建立建置工具並啟用開發者模式
- 更新 .gitignore 以排除產生的檔案
自動 .NET 專案偵測：
當目標目錄中發現 .csproj 檔案時，init 會使用簡化的 .NET 特定流程：
- 驗證並將
TargetFramework更新為 Windows 相容的 TFM（例如net10.0-windows10.0.26100.0） - 將
Microsoft.WindowsAppSDK和Microsoft.Windows.SDK.BuildTools直接添加為.csproj中的NuGetPackageReference條目 - 產生
appxmanifest.xml、資產和開發證書 -
不會建立
winapp.yaml或下載 C++ 投影（用於dotnet restoreNuGet 套件）
範例：
# Initialize current directory
winapp init
# Initialize with experimental packages
winapp init --setup-sdks experimental
# Initialize specific directory without prompts
winapp init ./my-project --use-defaults
# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init
小提示
如果你執行了init--setup-sdks none，且之後需要 SDK，請重新執行winapp init --use-defaults --setup-sdks stable。 這樣可以保留現有檔案（清單等）。
回復
還原套件並根據現有 winapp.yaml 設定重新產生檔案。
winapp restore [options]
選項：
| Option | 說明 |
|---|---|
--config-dir <path> |
包含 winapp.yaml 的目錄（預設：目前目錄） |
它的用途：
- 讀取現有
winapp.yaml配置 - 下載/更新 SDK 套件至指定版本
- 重新產生 C++/WinRT 標頭與二進位檔
備註
對於以 winapp init 初始化的.NET專案，則沒有 winapp.yaml。 請使用 dotnet restore 來還原 NuGet 套件。
範例：
# Restore from winapp.yaml in current directory
winapp restore
更新
將套件更新到最新版本並更新設定檔。
winapp update [options]
選項：
| Option | 說明 |
|---|---|
--config-dir <path> |
包含 winapp.yaml 的目錄（預設：目前目錄） |
--setup-sdks |
SDK 安裝模式： stable （預設）、 preview、 experimental或 none |
它的用途：
- 讀取現有
winapp.yaml配置 - 將所有套件更新至最新版本
- 更新
winapp.yaml檔案並加入新的版本號 - 重新產生 C++/WinRT 標頭與二進位檔
範例：
# Update packages to latest versions
winapp update
# Update including experimental packages
winapp update --setup-sdks experimental
封裝指令
pack
從準備好的應用程式目錄建立 MSIX 套件。 需要 appxmanifest.xml 檔案存在於目標目錄、目前目錄中，或隨 --manifest 選項傳送。
winapp pack <input-folder> [options]
引數：
| Argument | 說明 |
|---|---|
input-folder |
包含要打包的應用程式檔案的目錄 |
選項：
| Option | 說明 |
|---|---|
--output <filename> |
輸出 MSIX 檔案名稱（預設： <name>.msix） |
--name <name> |
套件名稱（預設：來自清單） |
--manifest <path> |
AppxManifest.xml 的路徑（預設：自動檢測） |
--cert <path> |
簽署憑證路徑（啟用自動簽署） |
--cert-password <password> |
憑證密碼（預設：「password」） |
--generate-cert |
產生新的開發證書 |
--install-cert |
將憑證安裝到機器 |
--publisher <name> |
憑證產生的 Publisher 名稱 |
--self-contained |
捆綁 Windows App SDK 運行時緒 |
--skip-pri |
跳過 PRI 檔案產生 |
--executable <path> |
相對於輸入資料夾的執行檔路徑。 用來解析 $targetnametoken$ 清單中的佔位符。 |
它的用途：
- 驗證並處理檔案 AppxManifest.xml
- 解析
$placeholder$清單中的標記（參見 清單佔位符） - 確保適當的框架相依性
- 清單與登記並列更新
- 處理自包含式 Windows App SDK 部署
- 如果有證書，請提供標誌套件
範例：
# Package directory with auto-detected manifest
winapp pack ./dist
# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx
# Package with generated and installed certificate and self-contained runtime
winapp pack ./dist --generate-cert --install-cert --self-contained
# Package with explicit executable
winapp pack ./dist --executable MyApp.exe
建立除錯識別
建立應用程式身份，用於除錯時使用外部 位置/稀疏封裝，無需完整 MSIX 封裝。
winapp create-debug-identity [entrypoint] [options]
引數：
| Argument | 說明 |
|---|---|
entrypoint |
可執行檔（.exe）或需要識別的腳本路徑 |
選項：
| Option | 說明 |
|---|---|
--manifest <path> |
通往 AppxManifest.xml 的路徑（預設： ./appxmanifest.xml） |
--no-install |
建立套件後不要安裝 |
--keep-identity |
保持 manifest 的原樣身份，但不要在套件名稱和應用程式 ID 上附加 .debug |
它的用途：
- 修改可執行檔的並排清單
- 註冊稀疏套件以用於身份認證
- 啟用偵錯需身分驗證的 API
範例：
# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe
# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml
manifest 指令
manifest 生成
從範本產生 AppxManifest.xml。
winapp manifest generate [directory] [options]
引數：
| Argument | 說明 |
|---|---|
directory |
產生清單的目錄（預設：目前目錄） |
選項：
| Option | 說明 |
|---|---|
--package-name <name> |
套件名稱（預設：資料夾名稱） |
--publisher-name <name> |
Publisher CN（預設：CN=<current user>） |
--version <version> |
版本（預設：「1.0.0.0」） |
--description <text> |
說明（預設：「我的申請」） |
--entrypoint <path> |
入口點可執行檔或腳本 |
--template <type> |
範本類型： packaged （預設）或 sparse |
--logo-path <path> |
Logo 影像檔案的路徑 |
--if-exists <Error\|Overwrite\|Skip> |
如果檔案已經存在，預設操作為：錯誤 |
範本：
-
packaged- 標準打包應用程式清單 -
sparse- 使用稀疏/外部位置封裝的應用程式清單
顯現佔位符
生成清單使用以美元符號分隔的 $placeholder$ 標記，在打包時會自動解析：
| 預留位置 | 決心 | 範例 |
|---|---|---|
$targetnametoken$ |
無副檔名的可執行檔名稱 |
Executable="$targetnametoken$.exe" 變成 Executable="MyApp.exe" |
$targetentrypoint$ |
Windows.FullTrustApplication |
總是自動解決 |
占位符的解決方式：
-
winapp pack可透過--executable選項來解析$targetnametoken$，或在輸入資料夾中自動偵測單一.exe項目。 -
winapp create-debug-identity在提供時，從入口論點中解析出$targetnametoken$。 -
winapp manifest generate --executable從可執行檔中擷取元資料，但會$targetnametoken$.exe保留在清單中以便日後解決。
小提示
將 $targetnametoken$ 保留在已簽入的清單中，可以避免硬編碼執行檔名稱，且同時適用於 winapp pack 和 Visual Studio 建置。
範例：
# Generate standard manifest interactively
winapp manifest generate
# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite
清單更新資產
從單一來源映像產生所有必要的 MSIX 映像資產。
winapp manifest update-assets <image-path> [options]
引數：
| Argument | 說明 |
|---|---|
image-path |
來源圖片檔（PNG、JPG、GIF 等）的路徑 |
選項：
| Option | 說明 |
|---|---|
--manifest <path> |
AppxManifest.xml 檔案路徑（預設：搜尋目前目錄） |
它會取得單一來源影像，並自動以正確尺寸產生所有 12 個所需的 MSIX 影像資產。 資產會儲存到相對於清單位置的 Assets 目錄中。
範例：
# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png
# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/appxmanifest.xml
憑證與簽署指令
證書生成
產生用於套件簽署的開發憑證。
winapp cert generate [options]
選項：
| Option | 說明 |
|---|---|
--manifest <appxmanifest.xml> |
從 appxmanifest.xml中提取publisher資訊 |
--publisher <name> |
憑證的發行者名稱 |
--output <path> |
輸出憑證檔案路徑 |
--password <password> |
憑證密碼（預設：「password」） |
--valid-days <days> |
證書有效天數（預設：365） |
--install |
生成之後將憑證安裝到本地機器儲存 |
--if-exists <Error\|Overwrite\|Skip> |
如果憑證檔案已經存在，行為（預設：錯誤） |
憑證安裝
將憑證安裝到機器憑證儲存庫。
winapp cert install <cert-path>
引數：
| Argument | 說明 |
|---|---|
cert-path |
安裝憑證檔案的路徑 |
範例：
# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx
# Install certificate to machine
winapp cert install ./mycert.pfx
標記
用憑證簽署 MSIX 套件和執行檔。
winapp sign <file-path> [options]
引數：
| Argument | 說明 |
|---|---|
file-path |
在 MSIX 套件或可執行檔中進行簽署的路徑 |
選項：
| Option | 說明 |
|---|---|
--cert <path> |
簽署憑證的路徑 |
--cert-password <password> |
憑證密碼（預設：「password」） |
範例：
# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx
# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword
實用指令
工具
直接使用 Windows SDK 工具。 使用 Microsoft.Windows.SDK.BuildTools中可用的工具。
winapp tool <tool-name> [tool-arguments]
可用工具：
-
makeappx- 建立與操作應用程式套件 -
signtool- 簽署檔案並驗證簽名 -
mt- 並排組裝組態工具 - 以及 Microsoft.Windows.SDK.BuildTools 的其他 Windows SDK 工具
範例：
# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix
儲存
執行 Microsoft Store 開發者 CLI 指令。 此指令會下載Microsoft Store開發者CLI（如果尚未下載）。 欲了解更多，請參閱 Microsoft Store 開發者 CLI。
winapp store [args...]
引數：
| Argument | 說明 |
|---|---|
args... |
直接傳給 msstore CLI 的參數 |
範例：
# List all apps in your Microsoft Partner Center account
winapp store app list
# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>
get-winapp-path（取得 Windows 應用程式路徑）
取得已安裝的 Windows SDK 元件的路徑。
winapp get-winapp-path [options]
傳回.winapp工作區目錄的路徑、套件安裝目錄及生成的標頭檔位置。
Node.js/Electron 指令
這些指令僅在 NPM 套件中提供。
節點創建外掛
產生帶有 Windows SDK 和 Windows App SDK 整合的原生 C++ 或 C# 附加元件範本。
npx winapp node create-addon [options]
選項：
| Option | 說明 |
|---|---|
--name <name> |
外掛名稱（預設：「nativeWindowsAddon」） |
--template |
選擇外掛類型： cs 或 cpp （預設： cpp） |
--verbose |
啟用冗長輸出 |
它的用途：
- 建立帶有範本檔案的附加目錄
- 產生 binding.gyp 及帶有 Windows SDK 範例的附加檔案
- 安裝所需 npm 依賴
- 新增建置腳本指令到 package.json
範例：
# Generate addon with default name
npx winapp node create-addon
# Generate custom named C# addon
npx winapp node create-addon --name myWindowsAddon --template cs
節點添加electorn調試標識
透過使用稀疏封裝，將應用程式身份加入 Electron 的開發流程。 需要一個 appxmanifest.xml（使用winapp init或winapp manifest generate建立一個）。
這很重要
Electron 應用程式封裝稀疏時有已知問題，會導致應用程式啟動時當機或無法渲染網頁內容。 這個問題在 Windows 上已經修正，但還沒擴散到所有裝置。 你可以在 Electron 應用程式中使用--no-sandbox 標誌來關閉沙盒，作為一種解法。 此問題不影響完整的 MSIX 封裝。
要解除 Electron 偵錯身份，請使用 winapp node clear-electron-debug-identity。
npx winapp node add-electron-debug-identity [options]
選項：
| Option | 說明 |
|---|---|
--manifest <path> |
自訂 appxmanifest.xml 路徑（預設：目前目錄中的 appxmanifest.xml） |
--no-install |
請勿安裝或修改相依性;僅設定 Electron 除錯身份 |
--keep-identity |
保持清單識別不變，勿附加 .debug |
--verbose |
啟用冗長輸出 |
範例：
# Add identity to Electron development process
npx winapp node add-electron-debug-identity
# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/appxmanifest.xml
節點 清除 Electron 偵錯身份情報
透過從備份中還原原始的 electron.exe，移除 Electron 除錯程序中的套件身分識別。
npx winapp node clear-electron-debug-identity [options]
選項：
| Option | 說明 |
|---|---|
--verbose |
啟用冗長輸出 |
範例：
# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity
