解决问题

必读内容

环境变量前提条件

必须正确设置环境变量 $ILLOGICAL_IMPULSE_VIRTUAL_ENV，否则 AGS 配置将无法正常工作。

我们已在 ~/.config/hypr/hyprland/env.conf 中提供默认配置，但您需要确保该配置文件已被包含在 ~/.config/hypr/hyprland.conf 中。通常需要重启 Hyprland 才能生效。

你可运行 ./diagnose 重新检查该变量的值。

成功样例

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
declare -x ILLOGICAL_IMPULSE_VIRTUAL_ENV="/home/myself/.local/state/ags/.venv"
[---SUCCESS---]

其中 myself 应替换为实际用户名。

错误样例1

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
./diagnose: line 30: declare: ILLOGICAL_IMPULSE_VIRTUAL_ENV: not found
[---EXIT 1---]

这种情况下：

你可能仍在使用旧的 ~/.config/hypr/hyprland.conf，忘记用 ~/.config/hypr/hyprland.conf.new 替换。请运行 cd ~/.config/hypr;mv hyprland.conf{,.old};mv hyprland.conf{.new,}。
确保已重启 Hyprland。

错误样例2

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
declare -x ILLOGICAL_IMPULSE_VIRTUAL_ENV="\$XDG_STATE_HOME/ags/.venv"
[---SUCCESS---]

此情况中 $XDG_STATE_HOME 未被展开（可能是 Hyprland 的 bug）：

确保运行 install.sh 时没有跳过且正确执行了 install-python-packages()，这会生成非空的 ~/.local/state/ags/.venv。
可在 ~/.config/hypr/custom/env.conf 直接指定值：

env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, /home/myself/.local/state/ags/.venv

需替换 myself 为实际用户名。

出错后必要的尝试

重启 Hyprland 或系统（环境变量变更后必须）。
AGS 相关组件（如状态栏）异常时，按 Super+Ctrl+T 切换壁纸（若环境变量或安装有问题可能无效）。
install.sh 是幂等脚本，可随时重复运行。

如何获取日志

出现问题后在终端（Super+T）运行相关命令查看报错。
状态栏/侧边栏/快捷键表等由 AGS 驱动（非 waybar），可运行 pkill agsv1; agsv1。

其它信息

查阅本 Wiki（特别是本页）及现有 issues 和 discussions。
使用常识判断。若仍无法解决，请发起descussion 来寻求帮助。

常见问题及解决方案

AGS / 状态栏主题 / 图标 / CSS 异常

参考：end-4/dots-hyprland#1010

按 Super+Ctrl+T 切换壁纸。

概览图中应用缺失

参考：end-4/dots-hyprland#497 comment end-4/dots-hyprland#487

请使用以下办法：

使用 `gsettings` 设置图标主题

例如：Papirus （推荐，因为它涵盖许多 App）

gsettings set org.gnome.desktop.interface icon-theme Papirus

Arch 用户需先使用 sudo pacman -S papirus-icon-theme 来安装。

在 AGS 配置中添加替换规则

编辑 ~/.config/ags/user_options.jsonc，在 icons.substitutions 中添加：

    'icons': {
        substitutions: {
            'footclient': "foot",
        },
    },

设置图标搜索路径

适用于自定义图标文件的情况。

在 ~/.config/ags/user_options.jsonc 中修改 icons.searchPaths 项。

音乐控制面板不显示？

参考：end-4/dots-hyprland#168

确保你的播放器支持 Mpris（列表参见 Arch Wiki 链接）。
如果是浏览器，请安装 Plasma Integration 扩展：Firefox 或 Chromium 以及 plasma-browser-integration 软件包（此为 Arch 的包名）。

然后，当 Firefox 播放媒体时，运行以下命令：

dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames|grep mpris

输出中应包含以下内容：

string "org.mpris.MediaPlayer2.plasma-browser-integration"

只有名为 “plasma-browser-integration” 的名称才有效，其他名称无效。

如果由于某种原因，Firefox 仍然没有显示 dbus org.mpris.MediaPlayer2.plasma-browser-integration，请考虑以下步骤：

使用 firefox --ProfileManager 创建一个新配置文件。
使用新配置文件启动 Firefox，并再次安装 Plasma Integration 扩展。
使用新配置文件重新启动 Firefox，然后再次尝试。

注意：playerctl -F metadata 对于调试也可能有帮助。

图标显示为文字

缺少 Material Symbols 字体。你可以手动下载字体并放入 ~/.local/share/fonts 文件夹中。
注意是 Material Symbols, 而不是 Material Icons！
使用 fc-cache -fv 或重启来刷新字体缓存。

`loginctl lock-session` 无效

参考：end-4/dots-hyprland#278

根据 Arch Linux 论坛上的这篇帖子：

Something needs to listen to systemd-logind’s dbus signals for this to work.

Hypridle 正是这样的“thing”，所以你需要确保它正在运行，这样 loginctl lock-session 会发送信号给 hypridle，继而 hypridle 将通过执行其配置文件 ~/.config/hypr/hypridle.conf 中定义的 $lock_cmd 命令来锁定屏幕。

参见 Hyprland Wiki。

终端无法用 `Ctrl`+`C` 中断

在 foot 终端中，Ctrl+C 被映射为复制，请使用 Ctrl+Shift+C 中断。
恢复 Ctrl+C：
- 修改 ~/.config/foot/foot.ini 注释掉 clipboard-copy=Control+c 即可恢复默认行为。
- 若你经常使用终端应用，使用一个功能更丰富的终端是个好主意。

随机卡死

参考 https://github.com/end-4/dots-hyprland/issues/746 。

已过时的问题解决方案

以下内容因配置更新已不再适用，保留供未来参考。

AGS 安装失败

`PermissionError: [Errno 13] Permission denied: '/usr/local/lib/libgvc.so'`

运行以下命令检查该文件是否属于任何软件包（很可能不属于任何软件包，因为它在 /usr/local 内）：

pacman -Qo /usr/local/lib/libgvc.so

如果确实不属于某个软件包，那么直接移除它可能是安全的。运行以下命令进行移除：

sudo mv /usr/local/lib/libgvc.so /tmp/

其他错误

删除 ./cache/ags 并重新安装。

Hyprland 安装失败

有时 AUR 包并不安装全部依赖。Hyprland 则经常出现此类问题。

检查构建日志，安装需要补充的依赖。
注意：清除位于 ~/.cache/yay 的缓存。