433 lines
13 KiB
Markdown
433 lines
13 KiB
Markdown
# Velopack 操作手册 — 恒诺迁移工具（便携模式）
|
||
|
||
## 一、Velopack 是什么
|
||
|
||
Velopack 是一个**自动更新框架**，核心功能：
|
||
1. **打包** — 把程序编译输出打包成更新包（.nupkg）
|
||
2. **自动更新** — 程序启动时自动检查服务器，发现新版本就下载并提示用户重启
|
||
|
||
**核心优势**：更新器用 Rust 编写，不需要 .NET Runtime，彻底解决 AutoUpdater.NET 的 .NET 8 依赖问题。
|
||
|
||
**本模式**：便携模式（`--noInst`），不生成安装包，用户直接解压 ZIP 使用。
|
||
|
||
---
|
||
|
||
## 二、项目结构（打包相关）
|
||
|
||
```
|
||
henlo_migration_wpf10/
|
||
├── henlo_migration_wpf10.csproj # 项目文件（已添加 Velopack 包）
|
||
│ └── <Version>1.0.2</Version> # 【版本号唯一来源】
|
||
├── App.xaml.cs # 启动时初始化 Velopack
|
||
├── Views/HomeWindow.xaml.cs # "检查更新"按钮逻辑
|
||
├── publish/ # 【发布输出目录】dotnet publish 生成
|
||
├── releases/ # 【打包输出目录】vpk pack 生成
|
||
│ ├── henlo_migration-1.0.2-full.nupkg # 更新包（上传到服务器）
|
||
│ ├── henlo_migration-win-Portable.zip # 便携版（给用户第一次使用）
|
||
│ ├── RELEASES # 更新索引文件（上传到服务器）
|
||
│ ├── assets.win.json # 资源清单
|
||
│ └── releases.win.json # 发布配置
|
||
└── pack.bat # 一键打包脚本（已创建）
|
||
```
|
||
|
||
---
|
||
|
||
## 三、版本号管理（重要）
|
||
|
||
### 唯一来源：csproj 文件
|
||
|
||
**版本号只存在于一个地方**：`henlo_migration_wpf10.csproj` 中的 `<Version>` 标签
|
||
|
||
```xml
|
||
<PropertyGroup>
|
||
<Version>1.0.2</Version> <!-- 唯一需要修改的地方 -->
|
||
</PropertyGroup>
|
||
```
|
||
|
||
### 版本号格式（SemVer2）
|
||
|
||
```
|
||
主版本.次版本.补丁
|
||
```
|
||
|
||
| 格式 | 示例 | 说明 |
|
||
|------|------|------|
|
||
| ✅ 正确 | `1.0.2`、`1.1.0`、`2.0.0` | 三段数字，无前导零 |
|
||
| ❌ 错误 | `1.0.02`、`1.0.002` | 不能前导零 |
|
||
| ❌ 错误 | `1.0` | 必须是三段 |
|
||
|
||
### 版本号递增规则
|
||
|
||
| 位置 | 什么时候改 | 示例 |
|
||
|------|-----------|------|
|
||
| 补丁（第3位） | Bug 修复 | `1.0.1` → `1.0.2` |
|
||
| 次版本（第2位） | 新增功能 | `1.0.2` → `1.1.0` |
|
||
| 主版本（第1位） | 重大更新/不兼容 | `1.1.0` → `2.0.0` |
|
||
|
||
**重要**：版本号必须递增，不能回退（Velopack 不允许降级）。
|
||
|
||
### 版本号同步机制
|
||
|
||
```
|
||
csproj <Version> 标签
|
||
│
|
||
├──→ 程序集版本（编译时自动嵌入 DLL）
|
||
├──→ 程序运行时显示（SysConfig.version 从程序集读取）
|
||
└──→ Velopack 打包版本（pack.bat 自动读取）
|
||
```
|
||
|
||
**只需要改一处**，其他地方全部自动同步。
|
||
|
||
---
|
||
|
||
## 四、发布流程（完整步骤）
|
||
|
||
### 步骤 1：修改版本号
|
||
|
||
打开 `henlo_migration_wpf10.csproj`，修改 `<Version>`：
|
||
|
||
```xml
|
||
<!-- 修改前 -->
|
||
<Version>1.0.1</Version>
|
||
|
||
<!-- 修改后 -->
|
||
<Version>1.0.2</Version>
|
||
```
|
||
|
||
**注意**：
|
||
- 只改这个数字，不要改其他地方
|
||
- 确保新版本号比旧版本大
|
||
- 保存文件
|
||
|
||
---
|
||
|
||
### 步骤 2：编译发布
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd D:\work\恒诺\长期支持\恒诺迁移工具\henlo_migration_wpf10
|
||
|
||
# 发布（Release 模式，输出到 publish/ 目录）
|
||
dotnet publish henlo_migration_wpf10.csproj -c Release -o publish --self-contained false -r win-x64
|
||
```
|
||
|
||
**参数说明**：
|
||
| 参数 | 含义 |
|
||
|------|------|
|
||
| `-c Release` | Release 模式（优化过的，体积小） |
|
||
| `-o publish` | 输出到 `publish/` 目录 |
|
||
| `--self-contained false` | 不包含 .NET Runtime（假设用户已装 .NET 10） |
|
||
| `-r win-x64` | 目标平台：Windows x64 |
|
||
|
||
**输出**：`publish/` 目录下生成完整的程序文件（.exe、.dll 等）
|
||
|
||
---
|
||
|
||
### 步骤 3：Velopack 打包（便携模式）
|
||
|
||
```bash
|
||
# 打包（使用 vpk 命令行工具，--noInst 表示不生成安装包）
|
||
vpk pack -u henlo_migration -v 1.0.2 -p publish -e 恒诺迁移工具.exe -o releases --noInst
|
||
```
|
||
|
||
**参数说明**：
|
||
| 参数 | 含义 |
|
||
|------|------|
|
||
| `-u henlo_migration` | 应用唯一标识符（URL 友好的名字） |
|
||
| `-v 1.0.2` | 版本号（必须是 SemVer2 格式） |
|
||
| `-p publish` | 输入目录（步骤 2 的输出） |
|
||
| `-e 恒诺迁移工具.exe` | 程序入口 EXE 文件名 |
|
||
| `-o releases` | 输出目录（打包结果放这里） |
|
||
| `--noInst` | **不生成安装包**（便携模式） |
|
||
|
||
**输出**：`releases/` 目录下生成 5 个文件（无 Setup.exe）
|
||
|
||
---
|
||
|
||
### 步骤 4：上传到服务器
|
||
|
||
把以下文件上传到更新服务器：
|
||
|
||
```
|
||
http://zjhenlo.henlo.net:8878/henlo_migration/auto_update/
|
||
├── henlo_migration-1.0.2-full.nupkg ← 必须（更新包）
|
||
└── RELEASES ← 必须（更新索引）
|
||
```
|
||
|
||
**注意**：
|
||
- 每次发布新版本，上传新的 `.nupkg` 文件即可
|
||
- `RELEASES` 文件会被 Velopack 自动更新（包含所有版本列表）
|
||
- 不需要上传 `Portable.zip` 到服务器（那是给用户第一次下载用的）
|
||
|
||
---
|
||
|
||
## 五、一键打包脚本
|
||
|
||
已创建 `pack.bat`，用法：
|
||
|
||
```batch
|
||
# 直接运行，版本号自动从 csproj 读取
|
||
pack.bat
|
||
```
|
||
|
||
**脚本内容**：
|
||
```batch
|
||
@echo off
|
||
setlocal enabledelayedexpansion
|
||
|
||
REM Velopack pack script (portable mode, no installer)
|
||
REM Reads <Version> from csproj automatically
|
||
|
||
set "PROJECT_DIR=%~dp0"
|
||
set "PUBLISH_DIR=%PROJECT_DIR%publish"
|
||
set "RELEASE_DIR=%PROJECT_DIR%releases"
|
||
set "CSPROJ=%PROJECT_DIR%henlo_migration_wpf10.csproj"
|
||
|
||
REM Read <Version> from csproj via PowerShell (handles UTF-8)
|
||
for /f "usebackq delims=" %%a in (`powershell -NoProfile -Command "[regex]::Match(([System.IO.File]::ReadAllText('%CSPROJ%', [System.Text.Encoding]::UTF8)), '<Version>(.+?)</Version>').Groups[1].Value"`) do set "VERSION=%%a"
|
||
|
||
if "!VERSION!"=="" (
|
||
echo ERROR: Cannot read version from csproj
|
||
exit /b 1
|
||
)
|
||
|
||
echo ========================================
|
||
echo Henlo Migration Tool - Velopack Pack
|
||
echo Version: !VERSION!
|
||
echo ========================================
|
||
|
||
echo [1/3] Cleanup...
|
||
if exist "!PUBLISH_DIR!" rmdir /s /q "!PUBLISH_DIR!"
|
||
if exist "!RELEASE_DIR!" rmdir /s /q "!RELEASE_DIR!"
|
||
|
||
echo [2/3] dotnet publish...
|
||
dotnet publish "%CSPROJ%" -c Release -o "!PUBLISH_DIR!" --self-contained false -r win-x64
|
||
if errorlevel 1 (
|
||
echo ERROR: dotnet publish failed!
|
||
exit /b 1
|
||
)
|
||
|
||
echo [3/3] vpk pack (--noInst)...
|
||
vpk pack -u "henlo_migration" -v "!VERSION!" -p "!PUBLISH_DIR!" -e "恒诺迁移工具.exe" -o "!RELEASE_DIR!" --noInst
|
||
if errorlevel 1 (
|
||
echo ERROR: vpk pack failed!
|
||
exit /b 1
|
||
)
|
||
|
||
echo ========================================
|
||
echo Pack complete!
|
||
echo Output:
|
||
echo henlo_migration-win-Portable.zip
|
||
echo henlo_migration-!VERSION!-full.nupkg
|
||
echo RELEASES
|
||
echo Server deploy to:
|
||
echo http://zjhenlo.henlo.net:8878/henlo_migration/auto_update/
|
||
echo ========================================
|
||
|
||
endlocal
|
||
```
|
||
|
||
---
|
||
|
||
## 五点五、重要：中文路径编码问题
|
||
|
||
### 问题描述
|
||
|
||
项目路径包含中文字符（如 `D:\work\恒诺\...`），在某些场景下会导致编码问题：
|
||
|
||
| 工具/场景 | 是否受影响 | 说明 |
|
||
|----------|----------|------|
|
||
| **pack.bat 双击运行** | ❌ 正常 | CMD 直接执行，编码正确 |
|
||
| **手动执行 PowerShell** | ❌ 正常 | PowerShell 能正确处理 UTF-8 |
|
||
| **通过 AI Agent exec 工具** | ⚠️ **受影响** | 中文路径可能被损坏，导致命令执行失败 |
|
||
|
||
### 问题表现
|
||
|
||
当 exec 工具执行包含中文路径的命令时，可能出现：
|
||
```
|
||
# 预期命令
|
||
dir /b "D:\work\恒诺\长期支持\..."
|
||
|
||
# 实际执行的命令（路径被截断）
|
||
dir /b "D:\b"
|
||
```
|
||
|
||
### 解决方案
|
||
|
||
如果需要通过 AI Agent 执行涉及中文路径的操作，使用以下策略：
|
||
|
||
1. **写入脚本文件再执行**
|
||
```
|
||
# 不要直接执行带中文路径的命令
|
||
❌ exec: dir "D:\work\恒诺\..."
|
||
|
||
# 应先写脚本文件，再执行简单路径
|
||
✅ write: 将 Node.js/Python 脚本写入 _helper.js/_helper.py
|
||
✅ exec: node "D:\work\恒诺\...\_helper.js" # 路径简单时可行
|
||
# 或使用英文路径的项目目录
|
||
```
|
||
|
||
2. **使用相对路径**（如果在项目目录内操作）
|
||
```
|
||
cd /d "D:\work\恒诺\长期支持\恒诺迁移工具\henlo_migration_wpf10"
|
||
dir /b publish # 使用相对路径避免中文
|
||
```
|
||
|
||
3. **创建符号链接**（临时方案）
|
||
```cmd
|
||
mklink /D C:\henlo "D:\work\恒诺\长期支持\恒诺迁移工具"
|
||
# 之后操作使用 C:\henlo\... 路径
|
||
```
|
||
|
||
### 最佳实践
|
||
|
||
- **打包操作**：直接在项目目录双击 `pack.bat` 运行，不要通过 AI Agent 执行
|
||
- **文件操作**：AI Agent 使用 `write`/`read` 工具（这些工具能正确处理中文路径）
|
||
- **命令执行**：尽量使用不含中文字符的路径，或先写脚本再执行
|
||
|
||
---
|
||
|
||
## 六、打包目录说明
|
||
|
||
### 输入目录（`-p` 参数）
|
||
|
||
```
|
||
publish/ ← 你指定的输入目录
|
||
├── 恒诺迁移工具.exe ← 入口程序（-e 参数指定）
|
||
├── 恒诺迁移工具.dll
|
||
├── 各种依赖 DLL
|
||
├── HandyControl.dll
|
||
├── Velopack.dll
|
||
└── ...其他文件
|
||
```
|
||
|
||
**来源**：`dotnet publish` 的输出
|
||
|
||
### 输出目录（`-o` 参数）
|
||
|
||
```
|
||
releases/ ← 打包结果
|
||
├── henlo_migration-1.0.2-full.nupkg # 完整更新包（上传服务器）
|
||
├── henlo_migration-win-Portable.zip # 便携版（给用户第一次用）
|
||
├── RELEASES # 版本索引（上传服务器）
|
||
├── assets.win.json # 资源清单
|
||
└── releases.win.json # 发布配置
|
||
```
|
||
|
||
**注意**：没有 `Setup.exe`（因为用了 `--noInst`）
|
||
|
||
---
|
||
|
||
## 七、用户侧体验
|
||
|
||
### 第一次使用（新用户）
|
||
|
||
1. 从服务器下载 `henlo_migration-win-Portable.zip`
|
||
2. 解压到任意目录（如 `D:\恒诺迁移工具\`）
|
||
3. 双击 `恒诺迁移工具.exe` 运行
|
||
|
||
### 以后更新（自动）
|
||
|
||
1. 打开程序（旧版本）
|
||
2. Velopack 自动检查服务器 `RELEASES` 文件
|
||
3. 发现新版本 → 后台下载 `.nupkg` 更新包
|
||
4. 弹出提示："发现新版本 1.0.2，是否重启更新？"
|
||
5. 用户点击"是" → 程序关闭 → 自动安装更新 → 重启程序
|
||
6. 打开后就是新版本
|
||
|
||
### 手动检查更新
|
||
|
||
用户也可以点击菜单「帮助」→「检查更新」手动触发。
|
||
|
||
---
|
||
|
||
## 八、服务器配置
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
/var/www/henlo_migration/auto_update/ # Nginx 根目录
|
||
├── henlo_migration-1.0.0-full.nupkg # 旧版本（保留）
|
||
├── henlo_migration-1.0.1-full.nupkg # 旧版本（保留）
|
||
├── henlo_migration-1.0.2-full.nupkg # 当前版本
|
||
└── RELEASES # 版本索引（自动维护）
|
||
```
|
||
|
||
**注意**：不需要放 `Setup.exe` 和 `Portable.zip` 在服务器上。
|
||
|
||
### RELEASES 文件示例
|
||
|
||
```
|
||
9467F3A6D8E1B2C henlo_migration-1.0.0-full.nupkg 5915018
|
||
A7B8C9D0E1F2A3B henlo_migration-1.0.1-full.nupkg 5915018
|
||
C3D4E5F6A7B8C9D henlo_migration-1.0.2-full.nupkg 5915018
|
||
```
|
||
|
||
**注意**：不要手动修改 `RELEASES` 文件，Velopack 会自动维护。
|
||
|
||
---
|
||
|
||
## 九、常见问题
|
||
|
||
### Q1：打包时提示 "VelopackApp.Run() was found in OnStartup"
|
||
|
||
**原因**：Velopack 建议把初始化代码放在 `Main()` 方法开头，而不是 WPF 的 `OnStartup`。
|
||
|
||
**解决**：可以忽略（当前位置也能工作），或者按提示移到 `Main()` 里。
|
||
|
||
### Q2：用户无法自动更新
|
||
|
||
**检查清单**：
|
||
1. 服务器 URL 是否正确？（`App.xaml.cs` 中的 `UpdateUrl`）
|
||
2. `RELEASES` 文件是否在服务器上？
|
||
3. `.nupkg` 文件是否上传到服务器？
|
||
4. 防火墙是否允许访问服务器？
|
||
5. 版本号是否递增？（Velopack 不允许降级）
|
||
|
||
### Q3：如何回滚版本？
|
||
|
||
Velopack **不支持回滚**。如果新版本有问题：
|
||
1. 修复 bug
|
||
2. 发布更高版本号（如 1.0.3）
|
||
3. 用户更新到 1.0.3
|
||
|
||
### Q4：用户第一次如何获取程序？
|
||
|
||
把 `henlo_migration-win-Portable.zip` 发给用户：
|
||
- 通过 QQ、微信、邮件发送
|
||
- 或放在网盘/服务器上下载
|
||
- 用户下载后解压即可使用
|
||
|
||
---
|
||
|
||
## 十、发布检查清单
|
||
|
||
每次发布前检查：
|
||
|
||
- [ ] 代码已提交 Git
|
||
- [ ] **版本号已更新**（只改 `csproj` 里的 `<Version>`）
|
||
- [ ] `dotnet publish` 成功
|
||
- [ ] `vpk pack --noInst` 成功（或 `pack.bat` 成功）
|
||
- [ ] 测试程序能正常启动
|
||
- [ ] 上传 `.nupkg` 和 `RELEASES` 到服务器
|
||
- [ ] 测试自动更新流程
|
||
- [ ] 把 `Portable.zip` 发给需要的新用户
|
||
|
||
---
|
||
|
||
## 十一、命令速查表
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 修改版本号 | 编辑 `henlo_migration_wpf10.csproj` 中的 `<Version>` |
|
||
| 编译发布 | `dotnet publish -c Release -o publish --self-contained false -r win-x64` |
|
||
| Velopack 打包（便携模式） | `vpk pack -u henlo_migration -v 1.0.2 -p publish -e 恒诺迁移工具.exe -o releases --noInst` |
|
||
| 一键打包 | `pack.bat`（版本号自动从 csproj 读取） |
|
||
| 安装 vpk 工具 | `dotnet tool install -g vpk` |
|
||
| 更新 vpk 工具 | `dotnet tool update -g vpk` |
|
||
|
||
---
|
||
|
||
*文档版本：2026-04-22（便携模式）*
|
||
*适用项目：恒诺迁移工具 WPF*
|