解决问题
必读内容
环境变量前提条件
必须正确设置环境变量 $ILLOGICAL_IMPULSE_VIRTUAL_ENV
,否则 AGS 配置将无法正常工作。
我们已在 ~/.config/hypr/hyprland/env.conf
中提供默认配置,但您需要确保该配置文件已被包含在 ~/.config/hypr/hyprland.conf
中。通常需要重启 Hyprland 才能生效。
你可运行 ./diagnose
重新检查该变量的值。
成功样例
[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENVdeclare -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_ENVdeclare -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 异常
按 Super
+Ctrl
+T
切换壁纸。
概览图中应用缺失
请使用以下办法:
使用 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
项。
音乐控制面板不显示?
- 确保你的播放器支持 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
无效
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
的缓存。