fix(ci): ui-golden 需要机器级 SDL2 SDK——补 DTU_SDL2_DIR、配置期护栏与 build 缓存自愈

simulator/CMakeLists.txt

@@ -9,7 +9,15 @@ set(LVGL_DIR        "${PROJECT_ROOT}/Lib/lvgl")
 set(UI_DIR          "${PROJECT_ROOT}/Drivers/BSP/UI")
 set(NET_DIR         "${PROJECT_ROOT}/Drivers/BSP/NET")
 set(NETCFG_DIR      "${PROJECT_ROOT}/Drivers/BSP/NETCFG")
-set(SDL2_DIR       "${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")
+# SDL2 是**下载来的第三方 SDK**，simulator/SDL2/ 被 .gitignore 排除、**不入库**（§3.1 部署文档）。
+# 于是 CI/runner 的工作区里天然没有它：2026-10-27 远程 CI（run 45）第一次跑到 ui-golden 就
+# 报 C1083 找不到 SDL2/SDL.h——本地有 SDK 所以本地一直是绿的，照不出来。允许用机器级
+# DTU_SDL2_DIR 指向任意一份 SDK；**不设该变量时行为与今天完全一致**。
+if(DEFINED ENV{DTU_SDL2_DIR} AND NOT "$ENV{DTU_SDL2_DIR}" STREQUAL "")
+    set(SDL2_DIR "$ENV{DTU_SDL2_DIR}")
+else()
+    set(SDL2_DIR       "${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")
+endif()
 
 #=============================================================================
 # 编译标准
@@ -33,7 +41,21 @@ endif()
 # LVGL SDL 驱动内部 #include "SDL2/SDL.h"，include 目录下已有 SDL2/ 子目录
 set(SDL2_INCLUDE_DIR "${SDL2_DIR}/include" CACHE PATH "SDL2 include directory for LVGL")
 
-#=============================================================================
+# 缺 SDK 就在**配置期**一行说清。过去这里只打印拼出来的路径、不校验存在，于是配置阶段
+# 照样输出 "SDL2: <路径>"，直到编译 LVGL 的 SDL 驱动才炸出几百行 C1083，看着像代码错了
+# 缺 SDK 就在**配置期**一行说清。过去这里只打印拼出来的路径、不校验存在，于是配置阶段
+# 照样输出 "SDL2: <路径>"，直到编译 LVGL 的 SDL 驱动才炸出几百行 C1083，看着像代码错了
+# （CI run 45 的第一反应就是"像素回归红了吗"）。查的是 SDL2_INCLUDE_DIR 而非 SDL2_DIR：
+# 它是 CACHE 变量，复用旧 build 目录时缓存值可能比 SDL2_DIR 更旧，两处都得被这一条盖住。
+if(NOT EXISTS "${SDL2_INCLUDE_DIR}/SDL2/SDL.h")
+    message(FATAL_ERROR
+        "SDL2 SDK 不可用：找不到 ${SDL2_INCLUDE_DIR}/SDL2/SDL.h"
+        "  - 本机首次部署：照 docs/UI设计/LVGL模拟器部署与使用说明.md §3.1 下载 SDK 到 simulator/SDL2/"
+        "  - CI / runner：工作区里没有、也不该有这份 SDK；请设机器级 DTU_SDL2_DIR 指向一份 SDK"
+        "    （scripts/ci_runner_bootstrap.ps1 -SetEnv 会自动发现并写入该变量）"
+        "  - 若刚换过 SDK 位置：build 目录里的旧缓存可能仍指向旧路径，删掉 simulator/build 再配置"
+    )
+endif()
 # LVGL 子目录（引用项目自带的 LVGL v9.3.0 源码）
 #=============================================================================
 # LVGL 内部会自动检测 lv_conf.h（通过 LV_CONF_INCLUDE_SIMPLE 宏）

simulator/build_sim.ps1

@@ -117,6 +117,16 @@ if (Test-Path $cache) {
     }
 }
 
+# 半截缓存检查：上一次配置如果在 CMakeLists 里 FATAL_ERROR 中断（例如缺 SDL2 SDK），
+# CMakeCache.txt 已经写下、工程文件却根本没生成，于是下面「有缓存就不配置」会跳过配置，
+# 失败点跑到离根因很远的 MSBuild（MSB1009: 项目文件不存在）——2026-10-27 在 CI 等价工作区
+# 实测：设好 DTU_SDL2_DIR 之后仍然红，红因就是这个残留缓存。与上面的生成器不符同理，
+# 删掉 build/ 重来，让报错回到配置期那一行。
+if ((Test-Path $cache) -and -not (Test-Path (Join-Path $buildDir 'ALL_BUILD.vcxproj'))) {
+    Write-Host '[build_sim] build/ 有缓存但没有工程文件（上次配置中断）-> 删除重建' -ForegroundColor Yellow
+    if (-not (Remove-BuildDir $buildDir)) { exit 3 }
+}
+
 # --- 4. 配置 + 构建 ---------------------------------------------------------
 if (-not (Test-Path (Join-Path $buildDir 'CMakeCache.txt'))) {
     Write-Host '[build_sim] CMake 配置 ...'