桌宠背景是黑的 / 拖动时出现黑框
适用范围：下文依据历史 issue 整理。原因、绕过方法与限制需结合报告版本判断；本文没有在所有平台实机验证，也不把 issue 关闭当作已发布修复。
「黑底」有三种完全不同的原因，解法也完全不同。先按平台和触发时机对号入座，别乱试。
| 你在哪看到的 | 什么时候出现 | 往下看 |
|---|---|---|
| iPhone / iPad 的 Safari | 一直有，一个矩形黑底 | 情况一 |
| Windows 桌面模式 | 只有拖动时出现，停下就消失 | 情况二 |
| 桌面模式（各平台） | 静止时有一圈极浅的灰框 | 情况三 |
情况一：iPhone / iPad Safari 上一整块黑底
这是最常见的一种，而且是设计上的取舍，不是 bug 没修。
你会看到
桌宠动画本身播放正常，但背后是一个 16:9 的黑色矩形。同一地址在电脑 Chrome 上完全透明、正常。
原因（两层）
第一层：Safari 不认 webm 的透明通道。
dsh-pet 的素材是 VP9 编码的 .webm，透明依赖 WebM 的 alpha 通道。
Safari / WKWebView 能解码 VP9，但会丢弃 alpha，视频层按不透明合成 → 黑底。
官方 README 里其实写了这一点（「Safari/WKWebView 不认 webm alpha」）。
第二层：.mov 素材不在 npm 包里。
Safari 需要的是 HEVC-alpha 编码的 .mov。这些文件体积大（约 79 MB），
官方没放进 npm 包，而是单独放在 GitHub Release 的 assets-mov 里。
更麻烦的是：当 .mov 缺失时，服务端会静默回退到 .webm，
不报错。你请求 .mov，拿到的其实是 video/webm，于是继续黑底。
怎么解决
-
下载 mov 素材包
去官方 Release 页找
assets-mov： PC2005-cloud/dsh-pet releases -
解压到指定目录
# 目录结构必须是这个 ~/.dsh/dsh-pet/main-animation/mov/ # Windows 完整路径 C:\Users\<你的用户名>\.dsh\dsh-pet\main-animation\mov\解压后这个目录里应该是一堆
.mov文件（约 106 个），文件名和 webm 一一对应。 -
重启 DSH，用手机重新打开
iPhone 上可能要清一下缓存，或者换个无痕窗口验证。
0.4.0 用户注意：0.4.0 的 webm 素材增加到 109 个，但 Release 上的 assets-mov
还是 106 个，缺少「睡觉-开始 / 睡觉-循环 / 睡觉-起来」三个。
这三个动画在手机上仍然会黑底，只能等官方补齐。
如果你不用手机看：这个问题对你没影响，不用折腾。桌面 Chrome / Edge 一直是正常的。
情况二：Windows 上拖动宠物时四周出现黑框
你会看到
宠物静止时正常透明。一旦拖动，四周（包括气泡框所在的留白区）立刻出现一个黑色矩形边框。 松手静止后黑框消失。
原因
桌面模式的宠物窗口是一个 transparent: true + frame: false 的
Electron 窗口，在 Windows 上就是分层窗口（WS_EX_LAYERED）。
拖动时窗口位置逐帧更新，DWM 会把还没重绘的透明区域合成成黑色。
怎么解决
关掉这个 helper 进程的硬件加速。编辑这个文件：
# 找到 dsh-pet 的安装目录下的
runtime/electron-helper/main.js
# npm 全局安装通常在
~/.dsh/profiles/web/node_modules/dsh-pet/runtime/electron-helper/main.js在文件顶部 require('electron') 之后、app.whenReady() 之前加一行：
app.disableHardwareAcceleration();然后重启 DSH。拖拽时的黑框会消失。
代价：这会让宠物窗口改用软件渲染，低端机上 CPU 占用会上升。 另外升级 dsh-pet 会覆盖这个文件，每次升级后要重新加。
如果你不想改代码：别拖它。用设置里的「停靠位置」和边距来定位宠物， 就不会触发这个渲染问题。
情况三：静止时有一圈极浅的灰框
不是纯黑，是一圈几乎看不出来的浅灰色边框，一直存在。
这个问题目前还没有确定的根因，官方 issue 里仍在讨论。 已知的是它和「透明余量区」有关——宠物窗口比宠物本体大一圈，那一圈透明区域在某些 合成设置下会显示成极浅的灰。
暂时没有可靠的解决办法。可以试试上面「情况二」的关硬件加速，部分环境下能改善。 如果没效果，去 issue #279 补充你的显卡和环境信息。
还有一种「黑」：不是黑底，是宠物根本不显示
如果你看到的不是黑色矩形，而是什么都没有，那不是这个页面说的问题—— 去看 桌宠装好了但桌面上不显示。
相关 issue：#214 iOS Safari 黑底、 #260 0.4.0 仍黑底、 #37 拖拽黑框、 #279 透明灰框
早期 WKWebView 透明兼容与素材体积请求也见#48；它包含 mov 资源建议，不能据此保证任意浏览器转格式后可用。
资料来源（历史报告）：#18、#37、#48、#214、#260、#279。整理日期：2026-11-03，适用版本及证据限制见正文。