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 中触发构建以验证修复