Upscayl 兼容性与适配指南：操作系统版本要求与 GPU 兼容性全景解析

本文以 Upscayl 仓库中的 兼容性列表 为主体，系统梳理该 AI 图像放大工具在操作系统、核显与独显三个维度上的官方兼容范围；并结合源码中 GPU 检测与设备参数采集的实现，讲解如何通过 GPU ID 配置与日志验证手段，在升级前确认自己的硬件环境是否满足 Vulkan 运行条件。

为什么 Upscayl 存在兼容性边界：Vulkan 是硬性前提

Upscayl 的放大引擎基于 Real-ESRGAN 的 ncnn 实现，推理运行在 NCNN Vulkan 后端之上。README 的 FAQ 明确说明：

• Upscayl 使用 AI 模型对图像进行增强，采用 Real-ESRGAN 与 Vulkan 架构，其计算后端（upscayl-ncnn）完全开源；
• "Upscayl won't work with most iGPUs or CPUs"——大多数核显和纯 CPU 环境无法运行，但仍鼓励尝试。

这一点也是 通用排障文档 开篇的注意事项：放大图像需要一块 Vulkan 兼容的 GPU。因此，兼容性列表 的价值在于：它在"大多数核显不可用"的总体结论之下，列出了例外清单——哪些核显经社区验证可以工作、哪些独显被报告不能工作，帮助读者在动手前快速排除风险。

操作系统兼容范围

兼容性列表 给出的官方系统支持范围为：

操作系统	最低版本	备注
Ubuntu	20.04+	亦可通过 DEB 等其它 Linux 包格式安装（README 支持 Fedora 的 RPM、Debian/Ubuntu 系 DEB 及任意 x86 Linux 的 ZIP）
Windows	10+	建议将应用设置为"性能模式"（performance mode），否则系统可能覆盖 GPU 选择
macOS	12+	官方说明"在下一个版本中会重新加入对 macOS 11 的支持"

README 中 macOS 与 Windows 安装章节同样标注了 "(MacOS 12 and later)" 与 "(Windows 10 and later)"，与兼容性列表保持一致。

macOS 12（Monterey）的已知系统级缺陷

值得注意的是，macOS 排障文档 特别警告：虽然 Monterey（macOS 12）处于支持范围内，但可能出现空白黑屏问题——这是 Monterey 自身对 Electron 应用的系统级 bug，并非 Upscayl 能修复的问题，官方建议升级到设备支持的最新 macOS 版本。该文档还给出了清理残留数据的完整路径清单（~/Library/Application Support/Upscayl、~/Library/Saved Application State/org.upscayl.Upscayl.savedState/、~/Library/Group Containers/W2T4W74X87.org.upscayl.Upscayl、~/Library/Containers/Upscayl、~/Library/Preferences/org.upscayl.Upscayl.plist 等），并强调只删除名称中含 upscayl 的文件夹。

源码中的平台/架构识别

应用自身通过 get-device-specs.ts 采集设备规格：getPlatform() 将 os.platform() 归一化为 linux（覆盖 aix/freebsd/linux/openbsd/android）、mac（darwin/sunos）或 win（win32）；getArch() 归一化 CPU 架构为 x64/x86/arm/arm64。getDeviceSpecs() 还会尝试通过 IPC 通道 get-gpu-info 获取 GPU 信息（gpuDevice[0]），并在 renderer/components/sidebar/settings-tab/system-info.tsx 对应的系统信息面板中展示。这套平台归一化逻辑决定了 Windows 与 Linux 在命令行拼接时使用反斜杠还是正斜杠（见下文 get-arguments.ts）。

GPU 兼容性：哪些显卡能用、哪些不能

兼容性列表 将 GPU 分为两类结论：核显（integrated GPU）采用白名单制，独显（dedicated GPU）采用黑名单制。

经验证可工作的核显（白名单）

• Intel HD Graphics 620（Issue #382 报告）
• Intel Iris Graphics（社区讨论 #571 报告）
• AMD Vega 系列核显：Vega 8 Mobile（Issue #448 报告）、Vega 10（Issue #436 报告），列表中表述为 "Most AMD Vega GPUs"

这些条目均标注了报告来源，说明兼容性列表是社区驱动的实测记录。列表开头也明确邀请读者通过项目 Issues 标签页提交新硬件的建议来扩充这份清单。

被报告不能工作的独显（黑名单）

文档原文结论是："所有独显默认被认为可以工作，除非属于以下被报告不能工作的型号"：

• GTX 7xx 系列（GeForce GTX 750/760/770/780 等 Pascal 之前的 Kepler 一代）
• GT 920M（文档中带有 "?" 标记，即存在不确定性，源自 Issue #401 的一条评论）

从这两条黑名单可以推断其共性：均为架构较老、Vulkan 驱动支持不完善的 GPU——GTX 7xx 属于 Kepler 代（2012 年前后），GT 920M 为移动端老型号，Vulkan 生态对老架构的支持正是瓶颈所在。

核显/独显判定不唯一时的对策：GPU ID 手动指定

双显卡（核显 + 独显）笔记本上，系统可能默认把 Vulkan 工作交给不兼容的核显。Upscayl 提供的对策是 GPU ID 设置项：

• Guide.md 的 "GPU ID" 章节说明：GPU ID 用于手动指定一块启用 Vulkan 的 GPU，依据 Real-ESRGAN 文档，多 GPU 场景同样适用；
• 查找方法：打开 Upscayl 并尝试放大一张图 → 在设置页底部的日志区（log area）可以看到系统枚举出的全部 GPU ID（例如 0 为 AMD Radeon、1 为 Nvidia、2 为 llvmpipe）；
• 在 "GPU ID" 输入框中填入 0、1、2 甚至 0,1,2；
• Windows 特别提示：若 Upscayl 未设置为性能模式，系统可能覆盖该设置；且多 ID 并列时负载不会均匀分配（对应 Issue #465）。

源码验证：GPU ID 如何生效

从源码结构看，GPU ID 的完整链路是：设置页的 InputGpuId 组件将用户输入写入配置（在 Windows 平台下会额外显示一条 ADDITIONAL_DESCRIPTION 提示语，正对应"性能模式"注意事项）；随后 get-arguments.ts 在拼装 upscayl-ncnn 命令行时按 gpuId ? "-g" : "" 的条件注入 -g <gpuId> 参数——单图放大、两遍放大（double upscale）的首遍与第二遍、批量模式共 4 个参数构造函数（getSingleImageArguments / getDoubleUpscaleArguments / getDoubleUpscaleSecondPassArguments / getBatchArguments）都包含该参数，说明 GPU ID 在所有放大路径下均一致生效；最终由 spawn-upscayl.ts 通过 spawn 拉起 ncnn 可执行文件并记录 "📢 Upscayl Command" 日志——这条日志正是排障时观察实际生效参数的依据。

升级前的环境验证方法

综合仓库文档，推荐的硬件自检流程如下：

1. 运行 VulkanCapsViewer：Linux 排障文档 与 Windows 排障文档 的首要步骤都是用 VulkanCapsViewer 查看 GPU 是否支持 Vulkan；
2. 查看 Upscayl 日志中的 GPU 枚举：按 Guide.md 的步骤，在设置页日志区确认系统识别到了哪些 GPU 及其 ID；
3. 重装显卡驱动：Linux 与 Windows 排障文档都将"Reinstall graphics drivers"列为标准步骤。

出现不兼容问题时的排障路径

通用排障文档 给出的三板斧：

1. 卸载后重装应用；
2. 重启电脑；
3. 将 GPU ID 设置为你的独显。

Windows 平台的 专属排障清单 进一步补充：设置应用到性能模式、确认已安装正确的运行库（redistributables）、尝试 DirectX 修复、尽量关闭可切换显卡（switchable graphics）功能、开启硬件加速 GPU 调度（Windows 11）。Linux 平台则聚焦于 VulkanCapsViewer 检测与驱动重装两条。

小结

Upscayl 的兼容性边界可以概括为三层判断：

1. 系统层：Ubuntu 20.04+ / Windows 10+ / macOS 12+（macOS 11 支持规划在下一版本恢复）；
2. API 层：必须有一块 Vulkan 兼容的 GPU，绝大多数核显与纯 CPU 不可用，可用 VulkanCapsViewer 预检；
3. 硬件例外层：核显以 Intel HD 620、Intel Iris、AMD Vega（8 Mobile/10）为代表的白名单可用；独显以 GTX 7xx 系列、GT 920M（存疑）为代表的黑名单不可用，其余独显默认可用；双显卡环境可通过 GPU ID（-g 参数）手动锁定目标 GPU。

该兼容性列表由社区 Issue 报告持续维护，新的硬件验证结果可通过项目 Issues 标签页提交，使这份清单随用户硬件多样性不断丰富。