PhotoCraft 故障排除：闪退、安装与显示问题

PhotoCraft 启动闪退、显卡与 Wayland 兼容、数位板没有压感、文件无法保存、选中文字被删等常见问题的原因和解决办法，以及日志位置、重置设置和反馈 Bug 的方法。

非官方社区指南更新于 2026 年 10 月 9 日

PhotoCraft 启动失败或闪退，大多和显卡（GPU）后端或旧的设置文件有关。Linux 上的显示和输入怪问题，大多出在 Wayland。先做下面几项快速检查，再按症状查找。PhotoCraft 仍处于早期测试阶段，下文各问题的状态以 2026 年 10 月 9 日为准，当时最新版本是 v0.5.0。

先做这几步

更新到最新版。下文不少问题已在 v0.3.0 或 v0.5.0 修复。请从官方发布页下载，不要用镜像站或重新打包的“汉化版”。
用 CPU 渲染启动一次。启动时加参数 --safe-gpu，这一次会用 CPU 渲染器运行。
查看帮助 › 系统信息…（Help › System Info…）。这里显示显卡、图形后端、驱动和回退状态，还有“复制”按钮，方便贴进 Bug 报告。
重置设置。如果刚更新或刚改过某个首选项后就启动即崩，请看下文“安全地重置设置”一节。

闪退与 GPU 问题

PhotoCraft 如何自动绕开显卡崩溃

v0.3.0 起，PhotoCraft 在创建 GPU 设备前会写一个标记文件 gpu-starting.json。如果上次启动死在显卡驱动里，下次启动会自动换用更稳妥的后端：

系统	回退顺序
Windows	Vulkan → DX12 → CPU
Linux	Vulkan → GL → CPU
macOS	Metal → CPU

PhotoCraft 会记住能用的那个后端，你可以在 首选项 › 性能 › GPU 后端（Preferences › Performance › GPU Backend）查看或修改，那里还有 重置 GPU 后端 按钮。v0.5.0 在同一页面新增了 渲染模式（Rendering Mode），可选自动、GPU 或 CPU / 兼容模式。如果使用中 GPU 画布出错，PhotoCraft 会改用 CPU 合成，并提供 继续使用 CPU 和 重试 GPU 两个选项。

要强制指定后端，可以设置环境变量 WGPU_BACKEND，取值为 vulkan、dx12、metal 或 gl。它的优先级高于首选项和自动回退。

Windows：Intel 核显启动即崩

症状：打开就闪退，Windows 事件查看器里能看到 igvk64.dll（Intel 的 Vulkan 驱动）报访问冲突 0xc0000005。
影响范围：Windows 上的 Intel 核显（例如 UHD Graphics 630），v0.2.0 及更早版本。
解决：更新到 v0.3.0 或更高版本。Intel 显卡在 Windows 上已默认使用 DX12，崩溃一次后下次启动也会自动回退。旧版本可以在安装目录打开命令提示符，用 DX12 启动：
```
set WGPU_BACKEND=dx12
photocraft.exe
```
状态：#4 仍开放，等待受影响的硬件确认。自动回退机制已在同系列的另一款应用上验证有效。

更新后或改了界面字体大小后无法启动

症状：无法启动。从终端运行会看到 FontFamily::Name("medium") is not bound to any fonts，或 Error: Wgpu(CustomNativeAdapterSelectionError("no graphics adapter found"))。
原因：把 界面字体大小（UI font size）设成“小”以外的值后，下次启动会崩溃（#1503）。沿用旧版本留下的设置文件夹也可能导致无法启动（#1461，Arch/EndeavourOS + v0.5.0）。
临时办法：在 preferences.json 的 interface 下把 "uiFontSize" 改成 "small"；或者退出后把整个设置文件夹挪走（见下文“安全地重置设置”）。#1461 的报告者清空 ~/.config/photocraft 后恢复正常。
状态：字体大小导致的崩溃已在 v0.5.0 之后的 main 分支修复。#1461 仍开放。

Linux：切到 CPU 渲染后提示 “no graphics adapter found”

症状：把渲染模式切到 CPU 后，下次启动直接退出并提示 “no graphics adapter found”，改回 GPU 也没用。
影响范围：有人在 v0.5.0、KDE X11、NVIDIA 闭源驱动环境下遇到。
临时办法：删除 ~/.config/photocraft/gpu-starting.json。
状态：#1337，开放中。

虚拟机里只有黑窗口

症状：窗口全黑。有人在 VMware 中发现只有窗口最大化时才显示内容。
影响范围：Windows 虚拟机中的 v0.5.0，有报告称 v0.3.0 正常。
临时办法：在 #1788 中，把窗口最大化可以显示内容。除此之外暂无已知办法。
状态：#1647 和 #1788 均开放。

超大文档

尺寸特别大的画布可能超出 GPU 内存预算。这时画布会退回很慢的 CPU 绘制，极端尺寸下程序可能失去响应（#1015，开放中）。如果提示图层超出 GPU 内存预算，可以在 首选项 › 性能 中提高内存使用量，预算最多可达本机内存的四分之一。

安装与启动

macOS：较老的 Intel Mac

症状：程序坞图标跳几下就消失。在“终端”里运行 /Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft 会报 Error: Wgpu(RequestDeviceError(... Device(Lost) ...))，加 --safe-gpu 也一样。
影响范围：通过 OpenCore Legacy Patcher 运行新版 macOS 的 Intel Mac，例如 2013 年末款 iMac 和 Haswell 核显的 iMac，包括 v0.5.0。
原因：PhotoCraft 的 macOS 窗口即使在 CPU 模式下也依赖 Metal，开发者怀疑问题出在打过补丁的显卡驱动。
状态：#600 和 #1859 均开放，暂无已知办法。

macOS 的 DMG 已签名并经过公证，正常情况下 Gatekeeper 会直接放行，无需额外操作。

Linux：缺少依赖库的警告

启动时，PhotoCraft 会检查显示会话所需的库。缺库时会打印 could not find these libraries ...，附上 apt/dnf 安装命令，然后照常启动。按提示安装即可。在 Alpine 等基于 musl 的发行版上，即使库已存在也可能误报（#1144，开放中）。程序能正常运行的话，可以忽略。

Linux 桌面（Wayland）

把文件拖进窗口没有反应

原因：PhotoCraft 使用的窗口库目前不支持 Wayland 下的拖放。
临时办法：用文件 › 打开…，或者在文件管理器里复制图片，再到 PhotoCraft 里粘贴。如果一定要拖放，可以让 PhotoCraft 在 XWayland 下运行：
```
WAYLAND_DISPLAY= photocraft
WAYLAND_DISPLAY= ./photocraft-0.5.0-linux-x86_64.AppImage
flatpak run --nosocket=wayland --socket=x11 ai.storyteller.photocraft
```
v0.5.0 之后的 main 分支新增了设置：把 首选项 › 性能 › Linux 显示服务器 设为 X11，PhotoCraft 就会始终在 XWayland 下启动。
状态：#386，在上游支持原生拖放之前保持开放。

数位板没有反应或没有压感

Linux Wayland（#639，已关闭）：v0.5.0 及更早版本中，压感笔完全没有反应。修复已合入 main，会随下个版本发布：检测到数位板时，PhotoCraft 通过 Xwayland 打开窗口，由 X11 数位板读取模块获取压感、倾斜和橡皮擦端。设置 PHOTOCRAFT_NATIVE_WAYLAND=1 可以保持原生 Wayland。Flatpak 版需要授予 --socket=x11。在此之前，有用户在 X11 会话中可以正常使用压感笔和压感。原生 Wayland 压感在 #79 跟踪（开放中）。
Windows（#759，开放中）：只有在数位板驱动中开启 Windows Ink 时才有压感，多位用户在 v0.5.0 上确认过。目前还没有 WinTab 选项。
macOS（#759）：压感修复已合入 main，尚未在实机上确认。

其他显示与输入问题

症状	状态	临时办法
用 Ctrl+A、Shift+方向键或鼠标选中文字后文字被删掉（#1381）	v0.5.0 之后的 `main` 已修复	用 `WAYLAND_DISPLAY=` 启动
文本框里按一次键却无限重复（#585）	v0.5.0 已修复，请更新
下拉菜单盖住菜单标题（#565）	v0.3.0 已修复，请更新
打开文件对话框几秒后，合成器（如 Hyprland）提示程序未响应（#574）	v0.5.0 之后的 `main` 已修复	点“等待”即可，对话框仍可正常使用
分数缩放下界面太小或太大（#1072、#843）	v0.5.0 提供 75%–300% 的固定档位，`main` 上“自动”会跟随系统缩放	在首选项 › 界面 › 界面缩放中选一个固定值

中文输入法相关问题（例如 #451 Ubuntu + fcitx5）见 PhotoCraft 怎么设置中文界面。

macOS 显示

外接显示器颜色过饱和（#569，已关闭）：双显示器、显示器配置文件设为自动时，v0.2.0 不会跟随窗口所在的显示器切换配置文件。v0.5.0 已修复，请更新。现在自动模式会按每个窗口所在的显示器取配置文件。

文件

Windows：保存时报 “The system cannot find the file specified. (os error 2)”

症状：在“图片”等文件夹中，保存、另存为、导出全部失败，提示原文件未被修改（the original file was not changed）。
原因与解决：Windows 安全中心的文件夹保护拦截了 PhotoCraft。报告者在 Windows 安全中心（Defender）中允许 PhotoCraft 访问受保护的文件夹后解决。
状态：#1311，已按上述办法关闭。

另一个相关问题：保存对话框会给其他格式多加 .psd 后缀（如 photo.webp.psd），已由 #1178 在 main 分支修复。

其他文件问题

症状	状态
新建文档时输入的宽高无效，总是 1920 × 1080（#340、#588）	v0.3.0 已修复，请更新
打开含画板的大型 PSD 时崩溃（#332）	v0.3.0 已修复，请更新
Photoshop 制作的 PSD 中的文字无法编辑（#1317，开放中）	用文字工具（T）双击文字。安装缺失的字体。已栅格化、转为形状或放在智能对象里的文字本来就不是可编辑文字。v0.3.0 之后已有多项 PSD 文字修复

崩溃恢复

PhotoCraft 默认每 10 分钟自动保存一次有未保存更改的文档。相关设置是 首选项 › 文件处理 中的 自动保存、自动保存间隔（分钟） 和 启动时恢复。崩溃后再次启动，这些文档会以未保存状态重新打开，状态栏会显示恢复了几个文档。v0.3.0 起，恢复数据会一直保留到你保存或关闭文档，即使再崩一次也不会丢。网页版没有崩溃恢复功能。

日志、设置与反馈 Bug

设置文件夹

系统	位置
Windows	`%APPDATA%\Photocraft`
macOS	`~/Library/Application Support/Photocraft`
Linux	`~/.config/photocraft`（或 `$XDG_CONFIG_HOME/photocraft`）

设置环境变量 PHOTOCRAFT_CONFIG_DIR，或使用便携版的数据文件夹时，位置会相应改变。文件夹里有 preferences.json、gpu-starting.json、画笔预设 Presets 和崩溃恢复数据 Recovery。

安全地重置设置

先退出 PhotoCraft，把设置文件夹改名（例如改成 photocraft.old），不要直接删除，然后重新启动。直接删除会把画笔预设和尚未保存的恢复数据一起删掉。

日志

v0.5.0：从终端启动 PhotoCraft，复制终端输出。macOS 运行 /Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft，Linux 在终端里运行 AppImage 或 photocraft。
main 分支（下个版本）：程序还会在设置文件夹里写入 logs/photocraft.log，并保留前两次运行的 photocraft.1.log 和 photocraft.2.log，所以崩溃那次的日志在重启后仍在。
在 main 分支上，启动前设置 RUST_LOG=debug 可以记录更详细的信息。

提交 Issue 前的检查清单

已是最新版本（在帮助 › 关于 PhotoCraft 中查看）。
已搜索过现有 Issue，包括已关闭的。
启动类问题已试过 --safe-gpu 和重置设置文件夹。
已复制 帮助 › 系统信息… 的内容。
准备好终端输出或日志文件，以及准确的复现步骤。
文件类问题，准备好可以附上的小样本文件。

然后通过 帮助 › 报告问题…（会打开 GitHub 的 Issue 页面）提交，并把上面的信息都贴上。简单的问题也可以去社区 Discord 问。快捷键问题可参考快捷键大全。

本页目录

先做这几步
闪退与 GPU 问题
安装与启动
Linux 桌面（Wayland）
macOS 显示
文件
崩溃恢复
日志、设置与反馈 Bug

相关指南