常见坑速查
按现象组织，不是按模块。找到你看到的那个症状，往下读。
下载
大文件被压成单连接，速度只有 0.29 MB/s。 分片能力必须按通道判定。BMCLAPI 的 /maven 返回整文件不支持 Range，它的 /meta 却支持 206——按主机一刀切会把整个文件压成单连接。健康度按 SourceChannel(Meta/Client/Assets/Maven) 分开记。
并发数被池首的限流值压死。ConcurrencyFor 取候选源里最宽松的限流值（max），不是第一个。池首常是被 429 限过的镜像（限到 1 条），按它收并发等于把官方 CDN 扛着的文件降成单连接。
进度条冲到 100% 之后又掉回去。 换源重试会重复上报同一段字节。进度上报要 Math.Min(raw, totalBytes) 夹住，并按 100ms 节流。
某镜像的请求永远不返回，表现为「点下载无反应」。 MCIMAPI 会把请求 302 到 P2P 节点，节点常常不响应。必须有源级超时 + 换源。另外 LooksLikeHtml() 判首个非空白字符是 < 就当成错误页抛「返回的是站点页面(HTML)」。
安装
装了加载器但启动报「找不到主类」。 库有两条来源：Mojang 的 downloads.artifact 和 Fabric/Quilt 的纯 Maven 坐标。只处理一条就会缺 loader jar。
「装了多份但只有一份有名字」。 装了同一版本的第二份后，JSON 里的 id 和目录名不符（目录 1.20.1-2，JSON 里还是 1.20.1）。InstallVanillaAsync 里要调 InstanceLayout.PatchJsonId 改写。
Forge 构建列表恒为空。IsForgeBuildSuffix 必须用点号判定。现代版本是 47.4.5，旧版本是 10.13.4.1614-1.7.10——用 int.TryParse 会把两者都判失败。
整合包里的中文文件名乱码。 zip 未设 UTF-8 标志时按 GBK（代码页 936）回退解码。PackZip.Open 要注册 CodePagesEncodingProvider。
zip 解压写出到目录外。PackPathGuard.Normalize 拒绝绝对路径、盘符、.. 和含 : 的段，Resolve 再做一次 GetFullPath + 前缀校验防 zip-slip。
启动
启动的是第一份实例，不是你点的那份。实例目录名才是「这次启动的实例」，JSON 里的 id 可能还是原版号。用 id 拼路径会去找 versions/1.20.1/1.20.1.jar——那正好是第一份的 jar。
路径含空格时启动直接失败。 不能按空格切命令行（Java 常在 Program Files）。用引号感知切分后交给 ProcessStartInfo.ArgumentList 逐项转义。
恢复出来的运行态永远停在「运行中 + 采样已暂停」。 恢复路径（Recovered）没有 Exited 事件，进程死掉只能在第 1 次采样失败时收口落历史。晚一步就永远收不了口。
CPU 占用率出现假尖峰。 CPU% 需要间隔 >0.5s 才能做差分，且要除以 ProcessorCount 再 clamp 到 0–100。
游戏输出把启动器卡住。 stdout/stderr 重定向后必须持续读流——写满管道会阻塞游戏进程本身。
账户
微软登录报 AADSTS700016。 Minecraft 官方 client_id 00000000402b5328 不属于任何 Entra 租户，必须走 login.live.com/oauth20_connect.srf 这个 legacy 设备码端点，不能用 v2 端点。
刚拿到 token 就 401。 令牌下发时服务端可能还没传播完，需要退避重试。
「导入一张皮肤」之后皮肤库里只剩这一张。TryLoad 读失败时读路径兜底为空库、写路径必须拒绝。否则一次瞬时读失败会把你整个库清空。
第三方皮肤站返回 HTTP 200 但业务失败。 Blessing Skin 系协议的语义是 code ≠ 0 就算失败，不能只看 HTTP 状态码。
界面
定时器让 UI 疯狂自旋。DispatcherQueueTimer 的默认 Interval 是 0，意思是「尽最快速度」。每一处都必须显式设值。
列表滚动时行错位。 位移走 RenderTransform 的 TranslateTransform.Y，不要动 Visual.Offset——那会覆盖 XAML 布局结果。
背景模糊看起来是重影。 模糊用 composition 的 GaussianBlurEffect 作用于图片表面而不是 backdrop，「背景不透明度」的语义才干净。模糊不可用时静默退化为清晰图。
文字颜色在强调色按钮上变成黑色。ScText 基样式故意不设 Foreground：强调色按钮模板里的字色是靠 ContentPresenter 继承下来的。
原生
着色器编译失败 / 编译出来是乱的。 Vortice 把 HLSL 源码按 ANSI 交给 D3DCompile，源码里的中文注释会被截断。HLSL 必须纯 ASCII，有单测守着。
MF 报错看着像「加缓冲区失败」，实际是槽位错位。IMFAttributes 的 30 个方法如果写成继承基接口，运行时的方法槽位可能对不上，报 MF_E_ATTRIBUTENOTFOUND。做法是把它们全部显式展开抄一遍。
录屏静止画面时没有帧。 不能用 FrameArrived 驱动编码——WGC 是按画面变化推帧的，静止桌面收不到回调。必须由固定帧率的编码线程补重复帧。
卸载器卡在删除阶段下不来。 卸载器的工作目录必须移出安装目录（SetOutPath "$TEMP"）。cwd 占住 $INSTDIR 时 RMDir /r 删不掉。
静默安装时安装器一直挂着。 不能用 FindWindow + 重试框——/S 时没人点弹窗。直接 taskkill /F /T 结束旧进程。
构建与更新
关窗后进程残留，下一次 build 报 MSB3021。 WinUI 3 的退出流程要等 DispatcherQueue 停下，循环定时器让它永远停不下来。退出前必须停掉所有常驻定时器。
更新功能整体失效。latest.json 必须是 UTF-8 无 BOM——PowerShell 5.1 的 Set-Content -Encoding UTF8 默认带 BOM，而 System.Text.Json 遇到开头 U+FEFF 直接判非法 JSON。
用户永远看不到更新提示。System.Version 把缺省的 Build/Revision 视为 -1，"0.2.1" != "0.2.1.0"。比较前要归一化。
重新编译报 GetLatestMSVCVersion 任务意外失败。 XAML 编译器需要 MSVC 工具链。显式指定：-p:VCToolsInstallDir="…\VC\Tools\MSVC\14.44.35207\"。
PS 脚本莫名其妙少了一行。 Windows PowerShell 5.1 把无 BOM 的 .ps1 按 ANSI 读，中文注释会吞掉下一行。tools/*.ps1 一律纯 ASCII。
更新后启动器打不开 / 缺文件。 安装器先 RMDir /r "$INSTDIR" 再铺文件，为的是杜绝新旧 dll 混装；NSIS 用 RMDir /r 删不掉的目录要重试一次。