عیب‌یابی پیشرفته و رفع مشکلات رایج Hyprland

Hyprland با وجود پایداری کلی، گاهی با مشکلاتی مواجه می‌شود که ریشه در پیکربندی Lua، درایورهای گرافیکی، پورتال‌های Wayland یا خود کامپوزیتور دارد

آخرین به‌روزرسانی: ۲۲ آبان ۱۴۰۵ · نسخهٔ ۴ · ۶ بازدید

این مقاله مستندات رسمی Arch Linux نیست؛ برای موارد حساس به ArchWiki مراجعه کنید.

عیب‌یابی پیشرفته و رفع مشکلات رایج Hyprland در Arch Linux

عیب‌یابی و بررسی لاگ‌های Hyprland در ترمینال

Hyprland با وجود پایداری کلی، گاهی با مشکلاتی مواجه می‌شود که ریشه در پیکربندی Lua، درایورهای گرافیکی، پورتال‌های Wayland یا خود کامپوزیتور دارد. در این مقاله از آرچی ها ، رایج‌ترین خطاهای Hyprland را به‌صورت دسته‌بندی‌شده بررسی می‌کنیم و برای هرکدام راه‌حل عملی ارائه می‌دهیم.

---

خطاهای پیکربندی Lua

از نسخهٔ 0.55 به بعد، Hyprland از Lua استفاده می‌کند و بسیاری از خطاهای رایج ناشی از سینتکس نادرست یا بارگذاری فایل‌های منسوخ است.

اعتبارسنجی پیکربندی پس از هر تغییر

بلافاصله پس از ویرایش هر فایل Lua، پیکربندی را دوباره بارگذاری و خطاها را بررسی کنید:

hyprctl reload
hyprctl configerrors

اگر configerrors خروجی تمیزی نداشت، خطاها را برطرف کنید و دوباره اجرا کنید تا خروجی خالی شود.

خطاهای سینتکس در سطح فایل (Fundamental Errors)

خطاهای بنیادی سینتکس Lua باعث می‌شوند Hyprland از بارگذاری پیکربندی خودداری کند و یک پیام خطا نمایش دهد. خطاهای زمان اجرا (Runtime) اجرای فایل جاری را متوقف می‌کنند و پیام خطا می‌دهند (مثلاً فراخوانی یک مقدار nil).

بارگذاری فایل اشتباه (صفحهٔ سیاه با مکان‌نمای تنها)

اگر پس از راه‌اندازی از TTY فقط یک صفحهٔ سیاه با مکان‌نمای ماوس می‌بینید، احتمالاً Hyprland به فایل پیکربندی اشتباهی اشاره می‌کند. مسیر درست را با -c مشخص کنید یا از start-hyprland استفاده کنید:

Hyprland -c ${XDG_DATA_HOME:-$HOME/.local/share}/hypr/hyde.lua

نکته: ~/.config/hypr/hyprland.lua ممکن است توسط HyDE بارگذاری شود و نقطهٔ ورود اصلی نباشد.

ناسازگاری با پیکربندی قدیمی `hyprland.conf`

اگر خطاهایی مانند «trying to read keybinds.conf» یا «togglesplit» می‌بینید، Hyprland در حال تلاش برای خواندن فایل‌های .conf قدیمی است. مطمئن شوید که فقط از فایل .lua استفاده می‌کنید و هیچ فایل .conf قدیمی در مسیر پیکربندی باقی نمانده است.

دستورهای `hyprctl dispatch exec` و `hyprctl keyword` در Lua

در پیکربندی Lua، این دو دستور کاری انجام نمی‌دهند. به‌جای آن‌ها از hyprctl eval استفاده کنید:

hyprctl eval 'hl.exec_cmd("kitty")'

همچنین تغییرات hl.env (از جمله PATH) فقط در ورود بعدی اعمال می‌شوند، نه با hyprctl reload.

---

مشکلات NVIDIA

پشتیبانی رسمی از NVIDIA در Hyprland وجود ندارد، اما با درایورهای جدیدتر (نسخهٔ 525.60.11 به بعد) بسیاری از مشکلات حل شده است.

صفحهٔ سیاه در بوت یا پس از به‌روزرسانی

اگر با صفحهٔ سیاه مواجه شدید، ابتدا مطمئن شوید که nvidia_drm.modeset=1 فعال است. این پارامتر باید در خط فرمان کرنل (GRUB یا systemd-boot) تنظیم شود.

صفحهٔ سیاه هنگام خروج از Hyprland با SDDM

اگر هنگام خروج از Hyprland با کارت NVIDIA و مدیر نمایش SDDM صفحه سیاه می‌شود یا سیستم هنگ می‌کند، از دستور hyprshutdown با فلگ --vt استفاده کنید:

hyprshutdown --vt 2

پرش تصویر (Flickering) یا پارگی (Tearing)

برای کاهش پرش، می‌توانید گزینهٔ VRR را روی حالت 2 (فقط تمام‌صفحه) تنظیم کنید تا VRR فقط در بازی‌ها فعال شود:

hl.config({
    misc = {
        vrr = 2,
    }
})

مکان‌نمای نامرئی یا گم‌شده

برای رفع مشکل مکان‌نمای نامرئی در برخی تنظیمات NVIDIA، از گزینهٔ no_hardware_cursors استفاده کنید:

hl.config({
    cursor = {
        no_hardware_cursors = true,
    }
})

---

XWayland و مقیاس‌پذیری (Pixelated Apps)

برنامه‌هایی که تحت XWayland اجرا می‌شوند (مانند بسیاری از برنامه‌های Electron و بازی‌های قدیمی) نمی‌توانند به‌درستی با مقیاس کسری (Fractional Scaling) سازگار شوند و پیکسلی به نظر می‌رسند.

راه‌حل: `force_zero_scaling`

با فعال‌سازی این گزینه، XWayland مجبور می‌شود پنجره‌ها را بدون مقیاس‌دهی نمایش دهد. این کار ظاهر پیکسلی را از بین می‌برد، اما ممکن است اندازهٔ برنامه‌ها کوچک‌تر از حد دلخواه شود:

hl.config({
    xwayland = {
        force_zero_scaling = true,
    }
})

اجبار برنامه‌ها به Wayland بومی

برای اینکه برنامه‌ها به‌جای XWayland از Wayland بومی استفاده کنند، متغیرهای محیطی مناسب را تنظیم کنید. برای برنامه‌های مبتنی بر Chromium/Electron:

hl.env("ELECTRON_OZONE_PLATFORM_HINT", "wayland")
hl.env("OZONE_PLATFORM", "wayland")

---

اشتراک‌گذاری صفحه در Wayland از طریق PipeWire و پورتال xdg-desktop-portal-hyprland انجام می‌شود.

پیش‌نیازهای اولیه

مطمئن شوید که بسته‌های لازم نصب و سرویس‌ها فعال هستند:

sudo pacman -S pipewire wireplumber xdg-desktop-portal-hyprland
systemctl --user enable --now pipewire wireplumber xdg-desktop-portal-hyprland

بررسی وضعیت پورتال

اگر اشتراک‌گذاری صفحه کار نمی‌کند یا برنامه‌ها دیر باز می‌شوند، وضعیت پورتال را بررسی کنید:

systemctl --user status xdg-desktop-portal-hyprland

اگر پورتال به‌طور خودکار اجرا نمی‌شود و خطایی هم ثبت نمی‌کند، احتمالاً متغیرهای محیطی XDG خراب شده‌اند. متغیرهای XDG_CURRENT_DESKTOP و XDG_SESSION_TYPE را بررسی کنید.

مشکل اشتراک‌گذاری در برنامه‌های XWayland (Discord، Skype و…)

برنامه‌های XWayland فقط می‌توانند پنجره‌های XWayland دیگر را ببینند و نمی‌توانند کل صفحه یا یک پنجرهٔ Wayland را به اشتراک بگذارند. راه‌حل، استفاده از xwaylandvideobridge است:

yay -S xwaylandvideobridge-git

پس از نصب، قوانین پنجرهٔ زیر را اضافه کنید تا پنجرهٔ اصلی bridge به‌درستی پنهان شود:

hl.window_rule({
    name = "xwayland-video-bridge-fixes",
    match = { class = "xwaylandvideobridge" },
    no_initial_focus = true,
    no_focus = true,
    no_anim = true,
    no_blur = true,
    max_size = {1, 1},
    opacity = 0.0,
})

تطابق عمق بیت (Bitdepth)

اطمینان حاصل کنید که bitdepth در پیکربندی مانیتور با عمق بیت مانیتور فیزیکی شما مطابقت دارد. عدم تطابق می‌تواند باعث شکست اشتراک‌گذاری شود.

---

لاگ‌ها و ابزارهای اشکال‌زدایی (Logs & Debugging)

وقتی مشکلی رخ می‌دهد، اولین قدم بررسی لاگ‌هاست.

فعال‌سازی لاگ‌ها

لاگ‌ها به‌طور پیش‌فرض فعال هستند، اما اگر غیرفعال شده‌اند، debug.disable_logs را روی false تنظیم کنید. برای دریافت پیام‌های OpenGL نیز debug.gl_debugging را فعال کنید:

hl.config({
    debug = {
        disable_logs = false,
        gl_debugging = true,
    }
})

هشدار: لاگ‌های اشکال‌زدایی بر عملکرد تأثیر منفی می‌گذارند. پس از پایان کار، آن‌ها را غیرفعال کنید.

مشاهدهٔ لاگ آخرین نشست

اگر در TTY هستید و آخرین نشست Hyprland کرش کرده است:

cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr/ | head -n 1)/hyprland.log

اگر درون نشست Hyprland هستید و می‌خواهید لاگ نشست قبلی را ببینید:

cat $XDG_RUNTIME_DIR/hypr/$(ls -t $XDG_RUNTIME_DIR/hypr/ | head -n 2 | tail -n 1)/hyprland.log

گزارش کرش (Crash Report)

اگر Hyprland کرش کرد، فایل گزارش کرش را در مسیر زیر پیدا کنید:

ls ${XDG_CACHE_HOME:-$HOME/.cache}/hyprland/hyprlandCrashReport*.txt

این فایل را می‌توانید به گزارش اشکال در GitHub یا Discord پیوست کنید.

تشخیص کرش در زمان راه‌اندازی

معنای خطاهای رایج در لاگ:

ابزارهای `hyprctl` برای عیب‌یابی

hyprctl version        # نسخه و اطلاعات ساخت
hyprctl monitors       # وضعیت مانیتورها و حالت‌های پشتیبانی‌شده
hyprctl clients        # لیست پنجره‌ها و ویژگی‌های آن‌ها
hyprctl activewindow   # پنجرهٔ فعال
hyprctl getoption general:border_size  # بررسی مقدار یک گزینه

---

مشکلات اسکرین‌شات (Grim & Slurp)

Grim هنگ می‌کند یا تصویر خالی می‌گیرد

مشکل هنگ کردن grim ممکن است به تنظیم misc:vfr مربوط باشد. اگر misc:vfr روی false باشد، grim ممکن است هنگام اسکرین‌شات هنگ کند. برای رفع این مشکل، vfr را روی true تنظیم کنید:

hl.config({
    misc = {
        vfr = true,
    }
})

اسکرین‌شات خالی با HDR

اگر HDR فعال است، ممکن است اسکرین‌شات‌ها خالی ثبت شوند. در این صورت، HDR را موقتاً غیرفعال کنید یا از ابزارهای جایگزین مانند hyprshot استفاده کنید.

دستور صحیح اسکرین‌شات ناحیه‌ای

دستور استاندارد برای انتخاب ناحیه و گرفتن اسکرین‌شات:

grim -g "$(slurp)" ~/Pictures/screenshot.png

برای کپی مستقیم در کلیپ‌بورد:

grim -g "$(slurp)" - | wl-copy

---

مشکلات نمایشگر خارجی (External Monitor)

مانیتور خارجی سیگنال نمی‌گیرد (لپ‌تاپ)

این مشکل در سیستم‌های با سخت‌افزار محدود (iGPU، USB-C، هاب USB) ممکن است با تنظیم AQ_NO_MODIFIERS=1 برطرف شود.

برای تشخیص دقیق‌تر، لاگ DRM را بررسی کنید و به دنبال خطای Requested display configuration exceeds system DDB limitations بگردید.

راه‌حل‌های جایگزین

استفاده فقط از مانیتور خارجی: با تنظیم AQ_DRM_DEVICES=/dev/dri/card1 (یا card0)، Hyprland را مجبور به استفاده از dGPU کنید. صفحهٔ لپ‌تاپ غیرفعال می‌شود اما مانیتور خارجی کار می‌کند.
استفاده از همهٔ خروجی‌ها: در BIOS لپ‌تاپ را روی حالت «فقط dGPU» تنظیم کنید. همهٔ خروجی‌ها کار می‌کنند اما مصرف باتری افزایش می‌یابد.

نکته: این راه‌حل‌ها به مدل دستگاه بستگی دارند و ممکن است همیشه کار نکنند. استفاده از مبدل USB-C به HDMI نیز می‌تواند مانیتور خارجی را از طریق iGPU مسیریابی کند.

---

مشکلات رایج دیگر

خطاهای `symbol lookup` و `undefined symbol`

اگر با خطاهایی مانند symbol lookup error یا undefined symbol مواجه شدید، احتمالاً Hyprland را خودتان کامپایل کرده‌اید و کتابخانه‌ها با هم ناسازگار شده‌اند. اگر از بسته‌های -git استفاده می‌کنید، این بسته‌ها در حکم کامپایل دستی هستند. راه‌حل: از بسته‌های رسمی مخازن استفاده کنید و همهٔ اجزای hypr* را با هم به‌روزرسانی کنید.

برنامه‌ها پیکسلی هستند

این مشکل به XWayland مربوط می‌شود (بخش XWayland را ببینید).

OBS کار نمی‌کند

برای OBS علاوه بر پورتال، بستهٔ qt6-wayland را نیز نصب کنید:

sudo pacman -S qt6-wayland

مانیتور هنگام فعال‌سازی VRR سوسو می‌زند

گزینهٔ VRR را روی 2 (فقط تمام‌صفحه) تنظیم کنید تا VRR فقط در بازی‌ها فعال شود.

---

منابع و لینک‌های مرتبط

FAQ رسمی Hyprland: https://wiki.hypr.land/faq/
صفحهٔ NVIDIA: https://wiki.hypr.land/nvidia/
کرش‌ها و باگ‌ها (Crashes and Bugs): https://wiki.hypr.land/crashes-and-bugs/
XWayland: https://wiki.hypr.land/configuring/extra/xwayland/
اشتراک‌گذاری صفحه: https://wiki.hypr.land/useful-utilities/screen-sharing/
xdg-desktop-portal-hyprland: https://wiki.hypr.land/hypr-ecosystem/user/xdg-desktop-portal-hyprland/
اسکرین‌شات و ضبط صفحه: https://wiki.hypr.land/useful-utilities/screenshots-and-recording/
xwaylandvideobridge (AUR): https://aur.archlinux.org/packages/xwaylandvideobridge-git

مطالب مرتبط در سایت آرچی ها

ویکی سایت آرچی ها: https://archiha.ir/wiki
حل مشکل قفل شدن موس در CS2 روی Arch Linux + Hyprland (انجمن): مشاهده در انجمن
صفحه اصلی سایت آرچی ها: https://archiha.ir

---

این مقاله بر اساس مستندات رسمی Hyprland (نسخه‌های 0.56 تا 0.57) و ArchWiki گردآوری شده و برای جامعهٔ ARCHIHA تهیه شده است. آخرین به‌روزرسانی: نوامبر 2026.

عیب‌یابی پیشرفته و رفع مشکلات رایج Hyprland