docs: Add WiX Toolset error handling fix documentation

5 months ago · 29fe024b43
parent 63b3d15fcb
commit 29fe024b43
1 changed files with 307 additions and 0 deletions
--- a/docs/JENKINSFILE_WIX_FIX.md
+++ b/docs/JENKINSFILE_WIX_FIX.md
@ -0,0 +1,307 @@
+# Jenkinsfile WiX Toolset 错误处理修复
+
+**问题:** GUI 打包阶段在检查 WiX Toolset 时失败并退出（exit code 255）  
+**修复日期:** 2025-11-26  
+**状态:** ✅ 已修复
+
+---
+
+## 问题描述
+
+### 错误现象
+
+在 Jenkins 流水线的 GUI 打包阶段（Stage 7.2），当检查 WiX Toolset 是否安装时，如果 `where candle.exe` 命令找不到 `candle.exe`，整个批处理脚本会以错误代码 255 退出，导致流水线失败。
+
+### 错误日志
+
+```
+E:\2025-2026\GitAIOps\jenkins\.jenkins\workspace\SLMS>where candle.exe  1>nul 2>&1  
+<EFBFBD><EFBFBD>ʱ<EFBFBD><EFBFBD>Ӧ<EFBFBD><EFBFBD> \WiX<69><58>
+E:\2025-2026\GitAIOps\jenkins\.jenkins\workspace\SLMS>echo 当前 WIX_HOME: C:\Program Files (x86)\WiX Toolset v3.11 
+script returned exit code 255
+```
+
+### 根本原因
+
+1. **批处理脚本错误处理不当**
+   - `where candle.exe` 失败时返回非零退出码
+   - 批处理脚本没有正确捕获和处理这个错误
+   - 导致整个脚本异常退出
+
+2. **缺少错误恢复机制**
+   - 没有使用 `setlocal EnableDelayedExpansion`
+   - 没有在脚本末尾使用 `exit /b 0` 确保成功退出
+   - 错误检查逻辑不够健壮
+
+---
+
+## 修复方案
+
+### 修改 1: 添加脚本初始化
+
+**位置:** Jenkinsfile Stage 7.2 GUI 打包
+
+**修改前:**
+```groovy
+bat '''
+REM 使用 jpackage 创建 Windows EXE
+echo.
+echo ========== 使用 jpackage 创建 EXE ==========
+```
+
+**修改后:**
+```groovy
+bat '''
+@echo off
+setlocal EnableDelayedExpansion
+
+REM 使用 jpackage 创建 Windows EXE
+echo.
+echo ========== 使用 jpackage 创建 EXE ==========
+```
+
+**说明:**
+- `@echo off` - 关闭命令回显
+- `setlocal EnableDelayedExpansion` - 启用延迟变量扩展，支持 `!variable!` 语法
+
+### 修改 2: 改进 WiX 检查逻辑
+
+**修改前:**
+```batch
+REM 检查 WiX Toolset 是否安装
+where candle.exe >nul 2>&1
+if errorlevel 1 (
+    echo ⚠️ 警告: WiX Toolset 未找到，跳过 EXE 打包
+    echo 提示: 请检查 WiX Toolset 安装路径
+    echo 当前 WIX_HOME: %WIX_HOME%
+    goto skip_exe
+)
+echo ✓ WiX Toolset 可用
+```
+
+**修改后:**
+```batch
+REM 检查 WiX Toolset 是否安装
+set WIX_FOUND=0
+where candle.exe >nul 2>&1 && set WIX_FOUND=1
+
+if !WIX_FOUND! EQU 0 (
+    echo ⚠️ 警告: WiX Toolset 未找到，跳过 EXE 打包
+    echo 提示: 请检查 WiX Toolset 安装路径
+    echo 当前 WIX_HOME: %WIX_HOME%
+    echo 继续执行，但不创建 EXE 和 MSI
+    goto skip_exe
+)
+echo ✓ WiX Toolset 可用
+```
+
+**说明:**
+- 使用变量 `WIX_FOUND` 存储检查结果
+- 使用 `&&` 操作符在命令成功时设置变量
+- 使用延迟变量扩展 `!WIX_FOUND!` 读取变量值
+- 添加更详细的提示信息
+
+### 修改 3: 确保脚本成功退出
+
+**修改前:**
+```batch
+echo ✓ 已创建 README-GUI.txt
+'''
+```
+
+**修改后:**
+```batch
+echo ✓ 已创建 README-GUI.txt
+
+REM 确保脚本成功退出
+exit /b 0
+'''
+```
+
+**说明:**
+- `exit /b 0` - 以成功状态（0）退出批处理脚本
+- 即使跳过了 EXE/MSI 创建，脚本也会正常退出
+- 不会影响后续的流水线阶段
+
+---
+
+## 修复效果
+
+### 修复前
+
+- ❌ WiX Toolset 未找到时流水线失败
+- ❌ 错误代码 255
+- ❌ 无法继续后续阶段
+
+### 修复后
+
+- ✅ WiX Toolset 未找到时显示警告但继续执行
+- ✅ 跳过 EXE 和 MSI 创建
+- ✅ 仍然创建 GUI JAR 和启动脚本
+- ✅ 流水线正常完成
+
+---
+
+## 测试验证
+
+### 场景 1: WiX Toolset 已安装
+
+**预期行为:**
+1. 检测到 WiX Toolset
+2. 创建 app-image (包含 EXE)
+3. 创建 MSI 安装包
+4. 创建启动脚本和 README
+5. 流水线成功
+
+**验证命令:**
+```bash
+where candle.exe
+# 应该输出: C:\Program Files (x86)\WiX Toolset v3.11\bin\candle.exe
+```
+
+### 场景 2: WiX Toolset 未安装
+
+**预期行为:**
+1. 检测不到 WiX Toolset
+2. 显示警告信息
+3. 跳过 EXE 和 MSI 创建
+4. 仍然创建启动脚本和 README
+5. 流水线成功（不失败）
+
+**验证输出:**
+```
+⚠️ 警告: WiX Toolset 未找到，跳过 EXE 打包
+提示: 请检查 WiX Toolset 安装路径
+当前 WIX_HOME: C:\Program Files (x86)\WiX Toolset v3.11
+继续执行，但不创建 EXE 和 MSI
+```
+
+---
+
+## WiX Toolset 安装指南
+
+### 如果需要创建 EXE 和 MSI
+
+**下载 WiX Toolset:**
+1. 访问: https://wixtoolset.org/releases/
+2. 下载 WiX Toolset v3.11 或更高版本
+3. 安装到默认路径: `C:\Program Files (x86)\WiX Toolset v3.11`
+
+**验证安装:**
+```bash
+# 检查 candle.exe
+where candle.exe
+
+# 检查 light.exe
+where light.exe
+
+# 应该输出 WiX 工具的路径
+```
+
+**配置环境变量:**
+```bash
+# 添加到 PATH
+set PATH=%PATH%;C:\Program Files (x86)\WiX Toolset v3.11\bin
+
+# 或在 Jenkinsfile 中配置
+WIX_HOME = 'C:\\Program Files (x86)\\WiX Toolset v3.11'
+```
+
+### 如果不需要 EXE 和 MSI
+
+**无需安装 WiX Toolset**
+
+GUI 应用仍然可以通过以下方式运行:
+1. **JAR 方式:** `java -jar slms-gui.jar`
+2. **启动脚本:** 双击 `run-gui.bat`
+3. **模块路径:** `java --module-path libs --add-modules javafx.controls,javafx.fxml -jar slms-gui.jar`
+
+---
+
+## 相关文件
+
+### 修改的文件
+
+- `Jenkinsfile` - Stage 7.2 GUI 打包阶段
+
+### 相关文档
+
+- `docs/FOUR_APPS_TEST_REPORT.md` - 四端应用测试报告
+- `docs/PIPELINE_TEST_GUIDE.md` - 流水线测试指南
+- `docs/JENKINS_CONFIGURATION_GUIDE.md` - Jenkins 配置指南
+
+---
+
+## 最佳实践
+
+### 批处理脚本错误处理
+
+1. **使用 setlocal**
+   ```batch
+   @echo off
+   setlocal EnableDelayedExpansion
+   ```
+
+2. **捕获命令结果**
+   ```batch
+   set RESULT=0
+   command >nul 2>&1 && set RESULT=1
+   if !RESULT! EQU 0 (
+       echo Command failed
+   )
+   ```
+
+3. **确保成功退出**
+   ```batch
+   exit /b 0
+   ```
+
+4. **使用 goto 跳过可选步骤**
+   ```batch
+   if condition (
+       goto skip_optional
+   )
+   REM optional steps
+   :skip_optional
+   REM continue
+   ```
+
+### Jenkins 流水线最佳实践
+
+1. **可选功能应该优雅降级**
+   - 不应该因为可选功能失败而导致整个流水线失败
+   - 显示警告但继续执行
+
+2. **提供清晰的错误信息**
+   - 说明什么失败了
+   - 为什么失败
+   - 如何修复
+
+3. **测试多种场景**
+   - 正常情况
+   - 工具缺失情况
+   - 网络问题情况
+
+---
+
+## 提交信息
+
+**Commit:** 63b3d15  
+**Message:** fix: Improve WiX Toolset error handling in GUI packaging stage  
+**Date:** 2025-11-26  
+**Files Changed:** 1 (Jenkinsfile)  
+**Lines Changed:** +11 -2
+
+---
+
+## 总结
+
+此修复确保了即使 WiX Toolset 未安装，Jenkins 流水线也能正常完成。GUI 应用的 JAR 文件仍然会被创建，用户可以通过 JAR 或启动脚本运行应用。
+
+如果需要 EXE 和 MSI 安装包，只需安装 WiX Toolset 并重新运行流水线即可。
+
+---
+
+**修复状态:** ✅ 已完成并推送到 Gitea  
+**测试状态:** 待验证  
+**下一步:** 在 Jenkins 中触发构建以验证修复