诊断并解决所有已记录的 Hookshot v2.0.11 运行时崩溃、GPU 驱动卡死、纹理异常及构建器提取错误。通过下方的问题标签（#1161、#817、#57、#1176）或故障现象搜索筛选 10 张经过验证的故障工单，查阅三个分栏诊断面板（故障现象、环境变量、解决方案），并应用针对性的 RX_* 环境覆盖项。
按主要问题标签（#1161、#817、#57、#1176、RX_* 诊断）筛选或按现象关键字搜索。每份故障工单均展示三个分栏面板——观察到的现象、环境变量/启动参数，以及经过验证的 v2.0.11 解决方案，并提供互联的关联故障。
在复杂的海拉鲁平原或神殿场景切换期间，当 ASTC 纹理池加上级联阴影超出物理 VRAM，或触发驱动 TDR 超时时发生。
在 Steam Deck（Mesa RADV）上进入德库树内部或蜘蛛网房间时，由于着色器 2c56dc1006942f74 上的网格块子组剔除，可能导致 GPU 命令缓冲区挂起。
部分 AMD Windows Adrenalin 与 Linux 驱动会错误编译计算 ASTC 转 BC7 转码器，导致 HUD 图标与柯基里植被上出现彩色的 4x4 宏块伪影。
若提供了缺少补丁 v131072 的基础版 v0 转储、非 Switch 2 Title ID 0400486024DEC000 的 N64/3DS ROM，或在 v2.0.11 之前包含非 ASCII 字符的 Windows 路径，资源构建器均会中止。
跳过一个或多个 64 位 NVN2 着色器哈希的绘制调用，方便玩家与协作者精准定位引发驱动崩溃或视觉错误的 SPIR-V 管线。
将单个客户机函数地址 (`0x7100xxxxxx`) 或整个二进制文件分流至软件 ARM64 解释器执行，绕过静态 C 转译。
控制 stdout/stderr 从 trace 到 error 的日志详细级别，并在提交 GitHub issue 时记录目标客户机函数的出入口寄存器状态（`X0`–`X7`）。
初始化空操作的空渲染器并设置 RX_BOOT_DIRECT=1，以便不支持网格着色器的机器上的开发者能够 verify RomFS 挂载、音频和存档解析。
在 On Ubuntu 22.04/24.04 或缺少 libfuse2 的精简发行版中，双击 Hookshot-v2.0.11-Linux-x86_64.AppImage 会静默启动失败，除非赋予可执行权限或使用 --appimage-extract 参数。
写入中断时回退至 autosave.sav，或通过 scripts/oot_saves.py 重新计算 CRC32C 文件头校验和（`0x0008`）来恢复数据。
当降低 VRAM 预设仍无法解决崩溃或软死锁时，可结合使用 RX_LOG_LEVEL=debug 与 RX_SKIP_SHADERS=<hash> 排查是否由特定 NVN2 SPIR-V 管线引起，或设置 RX_FORCE_INTERP=0x7100xxxxxx（或 RX_FORCE_INTERP=all）将客户机函数交由软件 ARM64 解释器执行，而非静态 C。
ASTC 纹理池 + 级联阴影超出物理 VRAM，或独立呈现队列触发 TDR 超时 → 将 Insert/F1 预设降至 Low/Medium 并添加 Hookshot v2.0.11 运行。
进入德库树内部时执行网格着色器 2c56dc1006942f74 → RADV wave64 ballot 导致 GPU 命令缓冲区停滞 → 传入 RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%。
Adrenalin / RADV 计算着色器损坏了柯基里植被和 HUD 图标上的 4×4 BC7 块 → 导出 RX_VK_ASTC_RGBA8=1 强制使用 CPU/软件 RGBA8 纹理解码。
| 故障名称与 Issue 编号 | 受影响平台 | 环境变量 / 参数 | 关联故障 |
|---|---|---|---|
VK_ERROR_DEVICE_LOST GPU Timeout 或 VRAM 耗尽（#1161） Issue #1161 | 4 GB - 6 GB VRAM GPU 或超频的 Vulkan 驱动程序 | graphics_preset=Low/Medium 或 RX_SKIP_SHADERS=<hash> | |
Steam Deck / Linux RADV 德库树内部卡死 (#817) Issue #817 | Steam Deck LCD/OLED 与 Linux AMD RADV（Mesa < 24.3） | RX_VK_MESH_NOCULL=2c56dc1006942f74 | |
AMD RDNA 2 / RDNA 3 方块状树叶与 HUD 纹理瑕疵 (#57 / #1006) Issues #57 与 #1006 | AMD Radeon RX 6000 / RX 7000 系列（Windows 与 Linux） | RX_VK_ASTC_RGBA8=1 | |
HookshotBuilder 资源提取失败或 NSO 哈希不匹配 (#1176 / #990) Issues #1176 与 #990 | Windows x64 与 Linux x86_64 HookshotBuilder | 需要 Title ID 0400486024DEC000 v131072（e0f3ccfa） | |
隔离有问题的自定义或 Driver 专有 Shaders (RX_SKIP_SHADERS) docs/DEVELOPMENT.md | 所有 Vulkan 1.3 平台 | RX_SKIP_SHADERS=<hash1>,<hash2> | |
通过 ARM64 Interpreter 绕过提升后 C 函数的回归问题 (RX_FORCE_INTERP) docs/DESIGN.md 与 docs/DEVELOPMENT.md | Windows x64 与 Linux x86_64 | RX_FORCE_INTERP=0x7100123450 或 RX_FORCE_INTERP=all | |
启用详细的 Vulkan 与 HLE 系统调用日志（RX_LOG_LEVEL 与 RX_TRACE_FUNC） docs/DEVELOPMENT.md | Windows x64 与 Linux x86_64 | RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1 | |
在无 网格着色器 环境下测试资源加载与启动逻辑（RX_GPU_BACKEND=null） docs/DEVELOPMENT.md | 无头 CI 运行节点及不支持网格着色器的测试机 | RX_GPU_BACKEND=null RX_BOOT_DIRECT=1 | |
Linux AppImage 启动失败（缺失 chmod +x 或 libfuse2） README.md Linux Setup | Linux x86_64 (Ubuntu, Debian, Fedora, Arch) | chmod +x *.AppImage 或 --appimage-extract-and-run | |
存档槽位损坏或手动覆盖存档路径（RX_SAVE_PATH 与 oot_saves.py） docs/SAVES.md | Windows x64 与 Linux x86_64 | python3 scripts/oot_saves.py verify save_00.sav / RX_SAVE_PATH |
社区反馈的大多数问题集中于三类特定硬件故障 Hookshot。其一，Issue #1161 (VK_ERROR_DEVICE_LOST) 常见于两种场景：在 NVIDIA 621 系列驱动上，启动着色器预编译完成后且启用了独立 Vulkan 呈现队列时直接报错（已在 v2.0.9 缓解，并在 v2.0.11 进一步优化，即保持关闭独立呈现队列的同时重新启用 RX_VK_WB_DIFF=1）；或在 4 GB 至 6 GB 显卡上，于海拉鲁平原/神殿复杂场景切换期间，因 ASTC 纹理池与级联阴影超出物理 VRAM 导致。在 Insert / F1 菜单中将图形预设降至 Low（1.5 GB 纹理池）或 Medium（2.5 GB 纹理池）可防止 VRAM 耗尽。
其二，Issue #817 会影响运行低于 24.3 版本 Mesa 的 Steam Deck LCD/OLED 与 Linux AMD RADV 系统：进入德库树内部或蜘蛛网房间时，音频正常循环但 GPU 命令缓冲区卡死。该挂能源自 NVN2 网格着色器 2c56dc1006942f74 内部的子组 meshlet 剔除问题；在 Steam 启动项中设置 RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% 即可跳过该着色器的剔除，且对 FPS 毫无肉眼可见的负面影响。其三，AMD Radeon RX 6000 / RX 7000 系列显卡上的 Issues #57 与 #1006 会导致植被和 HUD 图标出现彩虹 4x4 色块，原因为驱动对计算 ASTC 转 BC7 转码器误编译；设置 export RX_VK_ASTC_RGBA8=1 即可切换为无损软件 RGBA8 解压。
当 HookshotBuilder 在资源提取或 C 编译阶段失败时，请verify三项前置条件：(1) 你的 Dump 必须匹配 Switch 2 Title ID 0400486024DEC000，已打上 v131072 补丁且 ExeFS main NSO SHA-1 前缀为 e0f3ccfa (e0f3ccfa56256410941279ef0b2501356be2222c)，而非未经补丁的 v0 基础版或 N64/3DS ROM；(2) 正在运行 Hookshot v2.0.11，该版本修复了包含非 ASCII 字符的 Windows 用户路径异常 (#1176)、残留生成的 C 转译冲突 (#1197) 以及缺失 Linux AppImage 头文件问题 (#990)；(3) 至少保留 30 GB 可用磁盘空间，以容纳 26.2 GB 解包 RomFS 以及 1.4 GB 生成的 C 源码。
针对高级调试，Hookshot 提供了 docs/DEVELOPMENT.md 中记录的细粒度环境变量：RX_LOG_LEVEL=debug 与 RX_ABORT_ON_UNIMPL=1 用于暴露未实现的 Horizon OS HLE 系统调用；RX_SKIP_SHADERS=<hash1>,<hash2> 用于禁用特定的 64 位 NVN2 着色器管线以排查画面损坏；RX_FORCE_INTERP=0x7100xxxxxx 用于将可疑的客户机函数分流至软件 ARM64 解释器；RX_GPU_BACKEND=null 配合 RX_BOOT_DIRECT=1 可用于无头启动验证。
在 On Steam Deck 或 Linux Steam 中，右键点击 Hookshot -> 属性 -> 启动选项，输入：RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%（或在 %command% 之前组合多个环境变量）。在 On Windows PowerShell 中，在构建目录运行 $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe，或在 Windows System 属性 -> 环境变量中添加该变量。
在 v2.0.10 之前，若更新中断或跨版本升级，work/sa/gen/ 内可能会残留旧版生成的 C 文件，引发 clang/lld 链接错误。升级至 Hookshot v2.0.11 后，构建器在编译前会自动丢弃残余的部分生成代码并清理旧的转译分片。
首先检查存档目录中的 autosave.sav，并将其覆盖复制到 save_00.sav。如果你手动编辑过存档文件，请运行 python -m nx2.oot_saves verify save_00.sav（或 export-json 后接 import-json），让 Hookshot 在文件头偏移 0x0008 处重新计算所需的 CRC32C 校验和。
已知 Issues #57、#817、#990、#1006、#1161、#1176 及硬件规格需求的主要参考来源。
记录了 RX_VK_MESH_NOCULL、RX_VK_ASTC_RGBA8、RX_SKIP_SHADERS、RX_FORCE_INTERP、RX_LOG_LEVEL 及 RX_GPU_BACKEND=null 的相关说明。
规范了 64 KB save_00.sav 布局、偏移 0x0008 处的 CRC32C 校验和、autosave.sav 回退机制及 scripts/oot_saves.py。
验证了 v2.0.9 NVIDIA 621 热修复补丁 (#1161)、v2.0.10 构建器清理逻辑 (#1176/#1197) 及 v2.0.11 恢复 RX_VK_WB_DIFF=1 的改动。