桌宠装好了，但桌面上不显示

整理：大肥鱼桌宠排障手册 · 上线 2026-11-04 · 页面维护 2026-11-04 · 资料快照 2026-11-03

本页目录

第一步：分清是哪一种「不显示」
情况 A：网页有、桌面没有（检查 helper 与窗口）
三种常见根因
情况 B：网页和桌面都没有
还是不行

适用范围：下文依据历史 issue 整理。原因、绕过方法与限制需结合报告版本判断；本文没有在所有平台实机验证，也不把 issue 关闭当作已发布修复。

浏览器里能看到、桌面上没有——这是 dsh-pet 最常见的问题。先按下面三步定位，大部分情况不用重装。

先看版本。下文整理的是特定历史版本的报告；先记录 DSH、插件和 Electron 版本，对照对应发布说明，不承诺升级到某个版本就能解决。

第一步：分清是哪一种「不显示」

现象	说明	往下看
网页里能看到，桌面上没有	浏览器 overlay 正常，桌面窗口没出来	情况 A
网页和桌面都没有	插件可能没加载，或显示位置设错了	情况 B

情况 A：网页有、桌面没有（检查 helper 与窗口）

桌面上的宠物是由一个独立的 Electron helper 进程画出来的。这个进程没启动，桌面上就什么都没有。

查 helper 进程在不在
Windows：打开任务管理器，搜 electron.exe。
macOS / Linux：终端执行 ps aux | grep electron-helper。

当前没有相关进程，既可能未启动，也可能启动后迅速退出；继续查第 2 步日志。
查日志，找真实报错
先从应用的日志入口查找。下列是部分历史版本的常见路径，不存在时以本机实际日志目录为准：
```
# macOS
~/Library/Logs/DSH Desktop/harness.log

# Windows
%APPDATA%\DSH Desktop\logs\harness.log
# 或看 helper 自身目录是否被创建：
%APPDATA%\dsh-pet-electron-helper\
```
在日志里搜 dsh-pet desktop helper，看它后面跟的是什么错。
对号入座，看下面「三种常见根因」

三种常见根因

① 报 `Cannot find module 'electron'`

这是最常见的一种。报错长这样：

[dsh-pet desktop helper] Error: Cannot find module 'electron'
[dsh-pet desktop helper]     at .../runtime/electron-helper/main.js:23
[dsh-pet desktop helper] crashed 12 consecutive times; circuit breaker tripped

原因：DSH Desktop 本身也是个 Electron 应用，它在启动子进程时设置了 ELECTRON_RUN_AS_NODE=1。这个变量被 dsh-pet 的 helper 继承了，导致 Electron 以「纯 Node 模式」启动——require('electron') 直接失败，进程在建窗口之前就崩了。

崩了之后守护逻辑会重启，但每次都继承同样的脏变量、在同一个地方崩， 连续 12 次后熔断，从此再也不重试，而且界面上没有任何提示。

怎么解决：先对照所装版本的修复说明，暂用仅网页显示。历史 #98 表明已有环境清理代码也不代表所有宿主都正常；保留真实报错和版本，见helper 秒退排查。

② helper 进程在，但窗口不显示

这种情况更隐蔽：进程列表里能看到 electron.exe，日志也没报错，但桌面上就是没有。用工具查会发现窗口存在、但 IsWindowVisible 是 false。

原因：旧版本里 paintWhenInitiallyHidden: false 和 ready-to-show 构成了死锁——窗口设成「显示前不渲染」，而 show() 只挂在 ready-to-show 上，两者互相等，永远等不到。

怎么解决：#55 报告了这条死锁分析；本文没有独立确认修复发行版本。先用网页模式，对照当前发布说明再升级与复测。

③ 装了虚拟显示器 / 远程桌面环境

如果这台机器上有虚拟显示器（比如 ToDesk 虚拟屏、Parsec、部分远程桌面工具）， Windows 上 helper 可能直接崩在 GPU 进程沙箱这一步（STATUS_BREAKPOINT）。

怎么确认：日志里出现 GPU process、sandbox、 STATUS_BREAKPOINT 之类的字样。

临时办法：先使用仅网页模式，记录虚拟显示适配器型号与 GPU 错误。不要为试错卸载驱动或默认禁用沙箱，见虚拟显示器排查。

情况 B：网页和桌面都没有

先查显示位置是否为 none；若配置正确，也可能是插件未加载、网页资源失败或其他冲突。

打开 DSH 设置 → 桌宠配置
看「显示位置」这一项是什么。如果是「都不显示」，那两边都不会渲染——这是预期行为，不是 bug。改成「桌面」或「两者」。
如果设置页也打不开
可能遇到了历史入口恢复问题：设成「都不显示」再重启后，入口会全部消失。这种情况看显示位置设成「都不显示」后桌宠消失，怎么恢复。

还是不行

把这三样东西整理好，去官方 issue 里搜或提：

dsh-pet 版本号（npm ls dsh-pet 或插件页能看到）
DSH Desktop 版本号 + 操作系统
日志里 dsh-pet desktop helper 后面那几行

官方仓库：PC2005-cloud/dsh-pet issues。提之前先搜一下，先查同版本和同一报错，避免把相似症状当成同一原因。

资料来源（历史报告）：#55、#63、#98、#168、#195。整理日期：2026-11-03，适用版本及证据限制见正文。