pu6zrsfoy
/
slms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
slms/docs/JENKINSFILE_WIX_FIX.md

6.7 KiB
Raw Permalink Blame History Escape

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  
<0A><>ʱ<EFBFBD><CAB1>Ӧ<EFBFBD><D3A6> \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 打包

修改前:

bat '''
REM 使用 jpackage 创建 Windows EXE
echo.
echo ========== 使用 jpackage 创建 EXE ==========

修改后:

bat '''
@echo off
setlocal EnableDelayedExpansion

REM 使用 jpackage 创建 Windows EXE
echo.
echo ========== 使用 jpackage 创建 EXE ==========

说明:

  • @echo off - 关闭命令回显
  • setlocal EnableDelayedExpansion - 启用延迟变量扩展，支持 !variable! 语法

修改 2: 改进 WiX 检查逻辑

修改前:

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 可用

修改后:

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: 确保脚本成功退出

修改前:

echo ✓ 已创建 README-GUI.txt
'''

修改后:

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. 流水线成功

验证命令:

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

验证安装:

# 检查 candle.exe
where candle.exe

# 检查 light.exe
where light.exe

# 应该输出 WiX 工具的路径

配置环境变量:

# 添加到 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

    @echo off
setlocal EnableDelayedExpansion

  2. 捕获命令结果

    set RESULT=0
command >nul 2>&1 && set RESULT=1
if !RESULT! EQU 0 (
    echo Command failed
)

  3. 确保成功退出

    exit /b 0

  4. 使用 goto 跳过可选步骤

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