排查

菜单变成安装指引、收到扩展未启用的通知、每次录制都弹授权框、管线起不来、扩展改了代码不生效 —— 这些常见问题分别是什么原因，怎么处理。

顶栏菜单只有「安装 Pika 录制程序…」

扩展装了，录制进程没装。扩展探测不到 D-Bus 上的 io.github.hungtcs.Pika， 所以把菜单换成了安装指引。按安装装上录制进程即可。

收到「Pika 的 Shell 扩展未启用」通知

反过来：录制进程装了，扩展没启用。录制进程没有任何界面， 所以它发完通知就退出了。

gnome-extensions enable pika@hungtcs.github.io

然后重新登录。

提示版本不匹配

两半是分别升级的，协议版本对不上时录制不会启动。把没升的那半升上来。

每次录制都弹授权框

门户认不出是哪个应用，所以记不住上次的授权。原因是录制进程落进了错误的 cgroup。

正式安装靠 D-Bus 激活文件里的 SystemdService= 解决。如果是自己 cargo run 起的进程，用 scripts/run-dev.sh，它会用 systemd-run --scope 把进程放进 正确的 scope。

录制不出来 / 管线起不来

先确认采集元件在：

gst-inspect-1.0 pipewiresrc

没有的话装 pipewire-gstreamer。

再确认有 H.264 编码器 —— 下面四个至少要有一个：

gst-inspect-1.0 vah264lpenc vah264enc x264enc openh264enc

Fedora 的 gstreamer1-plugins-bad-free 只提供 VA 硬编。没有 VA 支持的机器 需要 gstreamer1-plugin-openh264（RPM 包已经声明了这个依赖）。

扩展改了代码不生效

gnome-extensions disable / enable 不会重新导入 ESM 模块，旧代码会继续跑。 必须重启整个会话。

开发时用嵌套会话，不要为了测试反复注销登录：

./shell-extension/dev-session.sh

GNOME 升级后扩展消失了

metadata.json 里的 shell-version 是白名单不是下限。新的 GNOME 版本 需要往列表里加一行，重新打包。