跳至主要内容

Velopack 打包與部署指南

本文件說明 ProcessVision 的 Velopack 打包、安裝、自動更新流程與常見問題。

1. 核心概念​

項目值說明
PackIdProcessVision安裝識別名稱，不可變更
MainExeJope.App.ProcessVision.exe主執行檔名稱，不可變更
安裝目錄%LOCALAPPDATA%\ProcessVision\使用者目錄，不需 Admin
資料目錄%APPDATA%\ProcessVision\使用者資料（不受更新影響）
更新來源GitHub Releasesgather-system/GST.App.ProcessVision
Velopack 版本0.0.1298NuGet Package

重要原則：PackId 和 MainExe 一旦部署就不可更改，否則會導致捷徑斷裂、反安裝失敗。

2. 打包流程 Pipeline​

Stage 1: PUBLISH
  dotnet publish -c Release -r win-x64 --self-contained
  └→ bin/Release/net8.0-windows/win-x64/publish/

Stage 2: PROTECT（可選）
  Protect-GstAssemblies.ps1
  └→ .NET Reactor 三級保護

Stage 3: PACK
  vpk pack --packId ProcessVision --mainExe Jope.App.ProcessVision.exe
  └→ .nupkg + Setup.exe + RELEASES

Stage 4: RELEASE（可選）
  gh release create v{version}
  └→ 上傳到 GitHub Releases

2.1 執行方式​

# 預設（Publish + Protect + Pack）
.\publish-velopack.ps1 -Version "1.0.6"

# 跳過保護
.\publish-velopack.ps1 -Version "1.0.6" -SkipProtection

# 完整流程 + 上傳 GitHub
.\publish-velopack.ps1 -Version "1.0.6" -UploadToGitHub

# Prerelease（Beta Channel）
.\publish-velopack.ps1 -Version "1.0.6-beta.1" -Channel "beta" -UploadToGitHub -Prerelease

# 只到 Publish（除錯用）
.\publish-velopack.ps1 -Step Publish

2.2 產出檔案​

releases/v1.0.6/
├── ProcessVision-1.0.6-full.nupkg    ← 完整安裝包
├── ProcessVision-1.0.6-delta.nupkg   ← 差異更新包
├── ProcessVision-win-Setup.exe       ← 安裝程式
├── RELEASES                          ← Release metadata
└── releases.win.json                 ← 更新 manifest

3. .csproj 設定​

<PropertyGroup>
    <OutputType>WinExe</OutputType>
    <AssemblyName>Jope.App.ProcessVision</AssemblyName>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Version>1.0.6</Version>
    <PublishSingleFile>false</PublishSingleFile>  <!-- Velopack 不支援 SingleFile -->
</PropertyGroup>

<ItemGroup>
    <PackageReference Include="Velopack" Version="0.0.1298" />
</ItemGroup>

4. app.manifest 設定​

<requestedExecutionLevel level="asInvoker" uiAccess="false" />

必須使用 asInvoker。requireAdministrator 會導致 Setup.exe 安裝後啟動失敗（OS Error 740），因為 Velopack 安裝到使用者目錄，不需要 Admin 權限。

5. 應用程式初始化​

5.1 App.xaml.cs 啟動順序​

// 1. Velopack 初始化（必須最先執行）
VelopackApp.Build().Run();

// 2. License 檔案複製（在 DI 之前）
CopyLicenseFiles();

// 3. 單一實例檢查
SingleInstanceGuard("Jope.App.ProcessVision");

// 4. DI 註冊
services.AddSingleton<IUpdateService>(sp =>
    new VelopackUpdateService(logger, localizationService, updateSource));

// 5. 延遲更新檢查（UI 就緒後 3 秒）
await Task.Delay(3000);
await CheckForUpdatesOnStartupAsync();

5.2 VelopackUpdateService​

  • 更新來源：GitHub Releases（可透過 appsettings.json 的 UpdateSource 覆蓋）
  • Token 優先順序：環境變數 PROCESSVISION_UPDATE_TOKEN > 內嵌 Token
  • 重試機制：檢查更新 3 次（間隔 2 秒）、下載 3 次（間隔 5 秒）
  • 非阻塞：更新檢查不影響主程式啟動

5.3 更新 UI 流程​

啟動 → 3 秒延遲 → CheckForUpdatesAsync()
  ↓ 有更新
UpdateWindow Dialog（顯示版本差異）
  ↓ 使用者點「立即更新」
DownloadUpdatesAsync()（進度條 0-100%）
  ↓ 下載完成
ApplyUpdatesAndRestart()（重啟應用）

6. Channel 管理​

Channel用途打包指令
stable正式發行（預設）-Channel "stable" 或不指定
beta測試版本-Channel "beta" -Prerelease
alpha開發版本-Channel "alpha" -Prerelease

VelopackUpdateService 預設只檢查 prerelease: false（stable），不會自動更新到 beta/alpha。

7. 排除檔案​

以下檔案不包含在 Velopack 更新包中，更新時不會被覆蓋：

appsettings.json       ← 應用設定（使用者可能已修改）
deviceconfig.json      ← 設備配置

透過 vpk 的 --exclude regex 實現："appsettings\.json$|deviceconfig\.json$"

8. 常見問題​

8.1 OS Error 740（安裝後啟動失敗）​

原因：app.manifest 設定了 requireAdministrator。 解法：改為 asInvoker。（JOP-163）

8.2 捷徑空白 icon​

原因：Windows icon cache 過期。 解法：

ie4uinit.exe -show

8.3 改了 exe 名稱後捷徑斷裂、無法反安裝​

原因：Velopack 在安裝時將 MainExe 名稱寫入 registry 和捷徑，改名後不一致。 解法：手動清除舊安裝後重新全新安裝：

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ProcessVision"
Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\ProcessVision" -Recurse -ErrorAction SilentlyContinue

8.4 開發模式下顯示「非 Velopack 安裝」​

預期行為。透過 dotnet run 或 Visual Studio 執行時，IsInstalled 為 false，更新檢查會跳過。

文件版本：v1.0 | 建立日期：2026-03-16 | 對應 Issue：GST-164