跳至内容

解决问题

必读内容

环境变量前提条件

必须正确设置环境变量 $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

其它信息

常见问题及解决方案

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 扩展:FirefoxChromium 以及 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, 请考虑以下步骤:

  1. 使用 firefox --ProfileManager 创建一个新配置文件。
  2. 使用新配置文件启动 Firefox,并再次安装 Plasma Integration 扩展。
  3. 使用新配置文件重新启动 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 的缓存。