ArtCraft 黑屏、掉帧与渲染异常排查指南

PhotoCraft、VectorCraft、EffectCraft 这些带 GPU 渲染的 ArtCraft 软件，偶尔会遇到这几类问题：启动黑屏、画布花屏、交互掉帧、导出结果异常。它们的根源高度一致——GPU 后端与驱动。本指南给出一套适用于全系软件的排查方法论。

先理解：四大 GPU 后端

ArtCraft 的图形层支持四种后端，一份代码各平台挑选最合适的运行：

后端	主要平台	备注
Metal	macOS	苹果平台唯一选择
DirectX 12	Windows	Win 下默认，驱动成熟
Vulkan	Windows / Linux	跨平台候选，Linux 桌面主力
WebGPU	Web	浏览器版使用

关键认知：同一台机器上不同后端的表现可能天差地别。驱动程序对不同 API 的成熟度不同，出问题时「换后端」是最有效的单步操作。

排查路线图

1. 启动黑屏 / 窗口空白

1. 先确认是不是独显直连/混合显卡问题：笔记本双显卡环境里，强制软件运行在独立显卡（Windows 图形设置里为 exe 指定「高性能 GPU」；Linux 的 prime-run 等）
2. 黑屏伴随系统弹窗「显示驱动已停止响应」→ 驱动崩溃，直接跳第 3 步更新驱动
3. 仍黑屏 → 尝试切换后端（见下节）

2. 掉帧 / 交互卡顿

1. 降低文档复杂度观察趋势（Shape/图层数量减半还卡不卡）——区分「性能不足」和「驱动异常」
2. 打开软件的性能/诊断面板看帧率计数
3. 后台是否有抢占 GPU 的程序（游戏、视频播放、浏览器硬件加速的页面）
4. Linux 检查是否意外跑了 llvmpipe（软件渲染）：glxinfo | grep renderer，出现 llvmpipe 说明没有加载真正的 GPU 驱动

3. 渲染花屏 / 导出色块

1. 多为着色器兼容问题，换后端对比验证
2. 检查文档里是否用了 32 位浮点/宽色域特性 + 老显卡（老硬件对浮点纹理支持不全）
3. 导出异常但屏幕显示正常 → 分别截图反馈给官方

切换 GPU 后端

各软件在设置/首选项 → Graphics（或启动参数，随版本不同）里提供后端选择：

1. 优先试与默认不同的后端（Windows：DX12 ↔ Vulkan）
2. 改完重启软件
3. 逐个试，记录哪个稳定

找到稳定后端后，可以固定设置避免自动检测反复踩坑。Web 版依赖浏览器的 WebGPU/WebGL 实现，老浏览器请升级 Chrome/Edge/Firefox 最新版。

驱动检查清单

平台	检查项
Windows	用 GeForce/AMD 官方驱动面板更新，不用 Windows Update 的通用驱动
macOS	保持系统更新（Metal 随系统走）
Linux	发行版仓库的 Mesa/NVIDIA 驱动；AMD/Intel 用最新 Mesa，NVIDIA 官网驱动或仓库专版

日志收集

给官方反馈前，把日志打包好：

1. 各软件的日志通常在：

   系统	位置
   Windows	%APPDATA%\<产品名>\logs\（资源管理器地址栏直接粘贴）
   macOS	~/Library/Application Support/<产品名>/logs/
   Linux	~/.local/share/<产品名>/logs/ 或 ~/.config/<产品名>/

2. 复现一次问题（让报错写进最新日志）

3. 附上：系统版本、显卡型号、驱动版本、使用的 GPU 后端、复现步骤，到对应软件的 GitHub Issues 提交

一键自查清单

遇到图形问题，按顺序过一遍：

1. □ 更新 GPU 驱动到最新
2. □ 切换 GPU 后端（DX12 ↔ Vulkan）
3. □ 笔记本禁用核显运行（强制独立显卡）
4. □ Linux 确认没跑软件渲染（llvmpipe）
5. □ Web 版换 Chrome/Edge 最新版
6. □ 收集日志，规范提交 Issue

多数问题死在第 1、2 步。剩下 5% 的真 Bug，就是你要贡献给开源社区的那份报告。

小结

• 四后端（Metal/DX12/Vulkan/WebGPU）是 ArtCraft 图形问题的第一变量
• 黑屏查直连与驱动，掉帧查负载与后端，花屏换后端验证
• 日志在标准的 Application Support 目录，反馈 Issue 时一并发