故障排查

创意工坊浏览无法工作

请先检查 Steam Web API 密钥。

• 打开设置。
• 确认 Steam Web API Key 已填写。
• 如果创意工坊搜索提示缺少密钥，请使用提示中的设置入口，保存密钥后再回到创意工坊搜索。
• 如有需要，从 https://steamcommunity.com/dev/apikey 创建或复制密钥。
• 确认你登录的是拥有 Wallpaper Engine 的 Steam 账号。

同时确认本机已安装 Steam 和 Wallpaper Engine。

搜索结果仅用于发现内容。在线看到某个项目，并不代表它已经下载或同步到本机；请使用在 Steam 中打开到 Steam 中订阅或查看项目。

壁纸可见但无法应用

查看 LWE 显示的兼容性状态。

在 Library 中，请先查看卡片徽标：可运行视频项可以应用；仅识别的场景/网页项会被当前运行时有意阻止。打开详情面板可以看到同一策略的更多上下文。

创意工坊在线结果卡片也使用同样区分：视频在本地同步后才是当前可运行目标；场景/网页结果为仅识别；应用程序结果不支持运行时。

可能原因包括：

• 壁纸类型可识别，但当前运行时不支持；
• 项目是超出当前支持水平的网页或场景壁纸；
• 本地创意工坊内容不完整或尚未同步完成；
• 当前桌面会话尚未验证。
• 运行时后端无法初始化 Wayland layer-shell、EGL 或目标输出。
• $XDG_CONFIG_HOME/lwe/session.toml 或 $HOME/.config/lwe/session.toml 中保存的分配指向缺失的显示器或 Library 项。

视频类壁纸是首发运行时重点。不要假定所有 Wallpaper Engine 项目都能在 Linux 上运行。

应用壁纸后桌面没有变化

先确认你在受支持或已知可用的会话中测试。当前已验证环境是 Wayland + niri。LWE 的动态壁纸运行时仅面向 Wayland，并需要 wl_compositor、wl_output、zwlr_layer_shell_v1 等协议能力；它不会回退到 X11 运行时。

然后尝试：

1. 在 LWE 中清除当前分配；
2. 重新选择显示器；
3. 再次应用壁纸；
4. 如果会话状态看起来过期，重启 LWE；
5. 如果过期分配持续恢复，请检查或移除 $XDG_CONFIG_HOME/lwe/session.toml 或 $HOME/.config/lwe/session.toml 中的 LWE 会话文件。

从终端启动时，如果运行时错误能指出以下阶段，最有助于诊断：

• 后端启动；
• 输出发现；
• 首帧应用；
• 按显示器清除；
• 启动时恢复。

常见底层原因包括缺少 zwlr_layer_shell_v1、EGL 不可用、显示器/输出名称不匹配、本地视频资源缺失，或壁纸类型不受支持。设置页诊断信息会包含 Wayland 能力报告，可在运行时启动前显示合成器是否暴露所需协议。

当错误提到输出名称不匹配时，请刷新 Desktop 页面，重新选择显示器，并在报告问题时附上请求的输出名称和运行时列出的输出名称。

如果问题只在其他合成器上出现，报告问题时请附上合成器、会话类型和显示器布局。

应用壳在 GNOME/Mutter Wayland 上崩溃

某些 GNOME/Mutter + WebKitGTK 组合可能在应用壳启动阶段遇到 Wayland 显式同步错误，例如 Explicit Sync only supported on dmabuf buffers。作为应用壳 workaround，可以尝试这样启动 LWE：

WEBKIT_DISABLE_DMABUF_RENDERER=1 lwe-shell

这个 workaround 只影响 Tauri/WebKit 应用窗口，不代表 GNOME/Mutter 支持 LWE 的动态壁纸运行时。壁纸运行时仍依赖 Wayland 协议能力，尤其是 zwlr_layer_shell_v1；缺少必要协议时，LWE 会优雅降级。

AppImage 无法启动

确保 AppImage 具有可执行权限：

chmod +x LWE*.AppImage

然后从终端启动以捕获日志：

./LWE*.AppImage

AUR 包构建失败

尝试更新包数据库，并在干净环境中重新构建。如果失败与包本身相关，报告问题时请说明使用的是 lwe 还是 lwe-git。

语言或主题没有持久化

再次修改设置并重启应用。如果问题仍然存在，请附上发行版、桌面会话、安装包类型，以及应用是否能够写入其配置目录。