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

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

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

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

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

```bash
gnome-extensions enable pika@hungtcs.github.io
```

然后重新登录。

## 提示版本不匹配

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

## 每次录制都弹授权框

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

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

## 录制不出来 / 管线起不来

先确认采集元件在：

```bash
gst-inspect-1.0 pipewiresrc
```

没有的话装 `pipewire-gstreamer`。

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

```bash
gst-inspect-1.0 vah264lpenc vah264enc x264enc openh264enc
```

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

## 扩展改了代码不生效

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

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

```bash
./shell-extension/dev-session.sh
```

## GNOME 升级后扩展消失了

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