企业官网建设流程全解析

• 桌面应用

Noctalia 是一个直接构建在 Wayland 与 OpenGL ES 之上的原生桌面 Shell（desktop shell），目标用户是希望在 Wayland 合成器之上获得一体化、可配置桌面体验的 Linux 用户。本文以仓库 README.md 为主线，结合 example.toml、BUILDING.md、CONTRIBUTING.md 以及docs/user/文档与src/源码，系统讲解它的定位、功能边界、技术栈、从源码构建流程和完整的配置体系，读完后你将掌握如何评估、构建并配置这套桌面壳层。

什么是 Noctalia

Noctalia 是一个原生的 Wayland 桌面 Shell，面向那些想要一个精致、可配置的 Linux 桌面、却不想自己把独立的顶栏（bar）、启动器（launcher）、通知守护进程、锁屏、壁纸工具和设置界面拼装起来的用户。

它提供的是环绕在合成器（compositor）周围的 Shell 层，包括：顶栏、小部件（widgets）、Dock、启动器、控制中心、通知、壁纸、锁屏、会话动作、剪贴板历史、OSD 浮层、系统托盘集成和桌面小部件。项目没有 Qt 或 GTK 依赖，UI、渲染、配置和 IPC 模型被设计为单一内聚的 Shell，而不是一堆互不相干的面板和脚本的集合。

这与常见的"拼接式" Wayland 桌面形成鲜明对比：大多数 Wayland 方案需要把一个小工具栈拼在一起——一个顶栏、另一个启动器、再一个通知守护进程、一个锁屏、一个壁纸守护进程，加上会话脚本，而且每个组件都有自己的配置格式。这种方案灵活，但也让完整桌面显得脆弱、难以保持视觉一致。Noctalia 通过一个可配置的 Shell 层统一拥有这些常见的桌面表面与服务，同时仍然融入合成器驱动的 Wayland 工作流，适合那些想要自定义桌面环境的控制力、又希望减少活动部件并保持 UI 一致的用户。

核心功能清单

根据 README 的 "What It Includes" 一节，Noctalia 提供以下开箱即用的功能：

• 多显示器顶栏：可配置小部件、任务栏、工作区、系统托盘、媒体、网络、电池、亮度、天气、剪贴板，以及自定义脚本驱动的小部件；
• 桌面表面：Dock、启动器、控制中心、通知 toast/历史、壁纸选择器、OSD 浮层、锁屏、会话面板和桌面小部件；
• 配置体系：TOML 配置 + 热重载（hot reload）、GUI 托管的覆写（overrides）、主题/调色板支持、模板应用（template application），以及用于运行时控制的 IPC；
• 直接的 Wayland 集成：layer-shell、session lock、idle 行为、剪贴板、foreign toplevels、工作区、分数缩放（fractional scaling），以及按需的合成器专属工作区后端。

这些功能在源码中都有对应模块：例如src/shell/bar/是顶栏实现（158 个文件的子树），src/shell/dock/、src/shell/control_center/、src/shell/launcher/、src/shell/lockscreen/、src/shell/wallpaper/分别对应 Dock、控制中心、启动器、锁屏与壁纸；剪贴板历史位于src/shell/clipboard/，OSD 位于src/shell/osd/。

Wayland 合成器支持

Noctalia 支持那些提供 Shell 表面所需的layer-shell 协议的 Wayland 合成器。工作区集成在需要时通过合成器原生的后端实现，或者在使用ext-workspace-v1的合成器上通过该通用协议实现。

当前已集成的合成器包括：Niri、Hyprland、Sway、Scroll、Mango、Labwc、Triad、dwl以及其他兼容的 Wayland 合成器。其他合成器可以运行 Noctalia，但根据它们暴露的协议和 IPC，工作区、窗口、输出或会话动作集成可能有所缩减。

在源码中，这一抽象由 src/compositors/ 目录实现：compositor_platform.cpp 是统一入口，它通过compositors::detect()检测当前合成器，并为输出电源控制（createOutputPowerBackend）、聚焦输出解析（createFocusedOutputBackend）、工作区元数据（createWorkspaceMetadataBackend）和键盘布局切换（createKeyboardLayoutBackend）分别选择后端。从源码结构可以看到，每个合成器一个子目录：

• src/compositors/niri/：Niri 运行时、输出/键盘/工作区后端；
• src/compositors/hyprland/：Hyprland 运行时与hyprland-toplevel-mapping协议辅助；
• src/compositors/sway/、src/compositors/mango/、src/compositors/triad/、src/compositors/umbriel/、src/compositors/labwc/、src/compositors/dwl/：各自的运行时与后端；
• src/compositors/kde/：KDE KWin 的活跃窗口与虚拟桌面集成（通过org_kde_plasma_virtual_desktop协议）；
• src/compositors/ext_workspace/：通用的ext-workspace-v1工作区与输出后端。

例如在createOutputPowerBackend中，Hyprland/Niri/Sway/Triad/Mango/Umbriel 各有专属实现，而 dwl、Labwc、KDE 与未知合成器则回退到ext-workspace通用实现（见 compositor_platform.cpp）。用到的 Wayland 协议 XML 全部固化在仓库 protocols/ 目录下，包括wlr-layer-shell-unstable-v1.xml、wlr-foreign-toplevel-management-unstable-v1.xml、ext-workspace相关文件、wlr-screencopy-unstable-v1.xml等。

边界与范围：Shell 而非桌面环境

README 明确指出：Noctalia 是一个桌面 Shell，不是完整的桌面环境（DE）。它提供的是合成器之上的视觉与服务层：顶栏、面板、启动器、通知、Dock、锁屏、idle 行为、OSD、主题、壁纸、桌面小部件和多显示器 Shell 表面。

以下内容不属于 Noctalia 的范围，而是由合成器、专用桌面应用或系统服务负责：

• 窗口管理与平铺（tiling）；
• 合成器配置，如显示器排列与位置；
• 文件管理、可移动驱动器挂载、打印机管理；
• 屏幕镜像/投屏。

显示/登录欢迎器（greeter）支持位于独立的 Noctalia Greeter 项目中，Noctalia 会在有用时与这些组件集成，但不会替代它们。核心 Noctalia 是非侵入式的：它不管理你的合成器设置，也不接管你的 dotfiles。合成器专属的控制可以通过可选的插件提供，而不是成为核心 Shell 行为。

插件系统面向用户安装的扩展。对部分用户有用但并非核心 Shell 必需的功能可以放在插件里：额外的顶栏小部件、启动器 provider、桌面小部件、面板、快捷键、后台服务、合成器专属扩展与控制、硬件专属控制，以及第三方服务集成。插件以 Luau 脚本编写，运行时位于 src/scripting/（Luau 运行时是 vendored 的第三方依赖）。

技术栈与架构实现

技术栈一览

CONTRIBUTING.md 的 "Stack" 一节给出了完整的技术栈清单（直系依赖，传递依赖由系统包负责）：

设计原则（见 CONTRIBUTING.md）是：只使用直接的 Wayland + OpenGL ES，无工具包开销；采用领域特定的最小场景图（minimal scene graph）；打包需要覆盖主流发行版（Arch、NixOS、Fedora、Gentoo、Debian、Void、openSUSE）。

源码布局

仓库以src/为源码根，main.cpp是入口。关键目录映射（详见 CONTRIBUTING.md 的 Project Layout）：

• src/app/：应用引导、主循环、poll sources；
• src/compositors/：合成器检测、运行时适配器、工作区/输出/键盘后端；
• src/config/：配置 schema、校验、热重载、状态存储、覆写（其中schema/是类型化配置 schema 引擎）；
• src/dbus/：会话/系统总线封装与服务集成（accounts、bluetooth、logind、mpris、network、notification、polkit、power、tray、upower 等）；
• src/render/：GLES 渲染后端、着色器程序、场景图、动画、文本渲染；
• src/shell/：顶栏、面板、Dock、控制中心、桌面小部件、锁屏、OSD、壁纸等 Shell 表面；
• src/scripting/：Luau 插件运行时、manifest、注册表、源码管理、绑定；
• src/system/：桌面条目、亮度、天气、位置、系统监控、硬件服务；
• src/theme/：调色板生成、模板引擎、主题服务、模板应用；
• src/ipc/：IPC 客户端/服务与 CLI 命令解析。

测试位于 tests/，包含 100 多个单元测试文件（配置校验、合成器后端、模板、日历、网络等），例如 config_schema_roundtrip_test.cpp、hyprland_workspace_backend_test.cpp、niri_workspace_backend_test.cpp。Nix 打包与模块定义在 nix/，含nixos-module.nix、home-module.nix、hjem-module.nix。

运行时资产（Runtime Assets）

Noctalia 运行时必须携带assets/目录树，只复制noctalia二进制是不够的。meson install按前缀布局安装：

/usr/local/bin/noctalia /usr/local/share/noctalia/assets/...

也支持两种便携式 bundle 布局：

bundle/ noctalia assets/

bundle/ bin/noctalia share/noctalia/assets/

运行时资产查找顺序（见 CONTRIBUTING.md）：

1. NOCTALIA_ASSETS_DIR环境变量；
2. 可执行文件旁的assets/；
3. 可执行文件上一级目录的assets/；
4. 相对可执行文件的../share/noctalia/assets；
5. Meson 编译时安装路径（<prefix>/<datadir>/noctalia/assets）；
6. 源码树中的assets/（开发回退）。

只有当资产根目录包含预期的出厂文件（如emoji.json、fonts/noctalia-tabler.ttf、templates/builtin.toml、translations/en.json）时才会被接受。assets/中确实包含这些文件：字体 assets/fonts/noctalia-tabler.ttf、内置模板 assets/templates/builtin.toml、各语言翻译 assets/translations/。

从源码构建

README 将构建细节指向 BUILDING.md，该文档覆盖源码依赖、各发行版的包安装命令、构建模式与安装布局。

环境要求

• 源码以C++23构建，需要GCC 13+ 或 Clang 16+。当前滚动版与较新的稳定发行版（Arch、Fedora 38+、Debian 13、Ubuntu 24.04+）默认自带；Debian 12 "bookworm" 需安装g++-13并指定CXX=g++-13 just configure；
• 构建工具：just+meson；
• 打包方式：meson（+ninja），just是命令行封装。

系统依赖（按发行版）

Arch：

sudo pacman -S meson gcc just \ wayland wayland-protocols \ libglvnd freetype2 fontconfig \ cairo pango harfbuzz \ libxkbcommon glib2 \ libsecret libsodium \ sdbus-cpp libpipewire wireplumber polkit \ pam curl libwebp libjxl libsndfile librsvg \ libqalculate libxml2 \ md4c tomlplusplus libical \ nlohmann-json stb \ jemalloc

Fedora：

sudo dnf install meson gcc-c++ just \ wayland-devel wayland-protocols-devel \ libEGL-devel mesa-libGLES-devel \ freetype-devel fontconfig-devel \ cairo-devel pango-devel harfbuzz-devel \ libxkbcommon-devel glib2-devel \ libsecret-devel libsodium-devel \ sdbus-cpp-devel pipewire-devel wireplumber-devel \ pam-devel polkit-devel libcurl-devel libwebp-devel libjxl-devel libsndfile-devel librsvg2-devel \ libqalculate-devel libxml2-devel \ md4c-devel tomlplusplus-devel libical-devel \ json-devel stb_image_resize2-devel stb_image_write-devel \ jemalloc-devel

Debian / Ubuntu：

sudo apt install meson g++ just \ libwayland-dev wayland-protocols \ libegl-dev libgles-dev \ libfreetype-dev libfontconfig-dev \ libcairo2-dev libpango1.0-dev libharfbuzz-dev \ libxkbcommon-dev libglib2.0-dev \ libsecret-1-dev libsodium-dev \ libsdbus-c++-dev libpipewire-0.3-dev libwireplumber-0.5-dev \ libpam0g-dev libpolkit-agent-1-dev libpolkit-gobject-1-dev \ libcurl4-openssl-dev libwebp-dev libjxl-dev libsndfile1-dev librsvg2-dev \ libqalculate-dev libxml2-dev \ libmd4c-dev libtomlplusplus-dev libical-dev \ nlohmann-json3-dev libstb-dev \ libjemalloc-dev

openSUSE Tumbleweed/Slowroll、Void Linux 与 AerynOS 的完整命令见 BUILDING.md 的 Dependencies 一节。值得注意的依赖语义：

• Vendored 依赖（无需系统包）：Wuffs（栅格图像解码）、Luau（插件脚本运行时）、fzy（模糊匹配）、Material Color Utilities（Material Design 色彩生成）；
• libwebp负责 WebP 解码与缩略图编码，libjxl负责 JPEG XL 解码，libsndfile解码 Shell 音效（WAV、FLAC、Ogg/Vorbis、Opus、MP3、AIFF），libqalculate驱动启动器计算器（算术、单位与货币换算）；
• PipeWire：构建需要库/头文件，运行还需要 pipewire daemon——连接不上 daemon 时 Noctalia 会中止启动；
• Polkit agent：需要提供polkit-agent-1和polkit-gobject-1pkg-config 模块的开发文件；
• upower（电池/电源设备集成）与ddcutil（显示器亮度控制）是可选依赖；
• 凭据与加密状态持久化需要运行时 Secret Service 提供者（如 GNOME Keyring、KWallet 或 KeePassXC）；没有提供者时 Noctalia 仍可运行，但需要持久化机密的功能无法保存。CalDAV 账号可以改为从一个显式配置的普通文件读取密码（支持 agenix、sops-nix 等密件供应器）；Google refresh token 等可写凭据仍要求 Secret Service；
• jemalloc推荐但可选，可减少长会话中的内存碎片，glibc 系统上检测到即自动使用；可用-Djemalloc=enabled|disabled显式控制。

构建与安装

Release 构建（默认可移植，优化构建在build-release/）：

just configure release just build release # 安装所选构建模式（不会重新构建或重新配置） sudo just install release

需要本机原生 CPU 优化时，在配置后启用：

meson configure build-release -Dnative_optimizations=true just build release

自定义前缀（默认/usr/local）：

just configure release "$HOME/.local" just build release just install release

卸载使用just uninstall release（install/uninstall都要求显式构建模式，避免误装 debug 构建）。

Debug 构建（本地开发与排障）：

just configure just build just run

单元测试不会随just build编译（它只构建 Noctalia 可执行文件），显式运行just test（或just test release强制对 release 构建启用）；直接使用 Meson 的用户可用-Dtests=enabled|disabled|auto控制。生产源码只编译一次，进入内部静态库，由 Shell 与测试可执行文件共享。

ASan（AddressSanitizer）构建（内存错误排查，见 CONTRIBUTING.md）：先停止合成器启动的 Noctalia 实例，然后：

just configure asan && just build asan ASAN_OPTIONS=log_path=/tmp/noctalia-asan ./build-asan/noctalia 2>&1 | tee noctalia-asan-terminal.log

复现崩溃后，将终端日志与/tmp/noctalia-asan.*一并附上。

配置体系

README 指出：开箱即用的全默认配置在 example.toml，完整配置参考在文档站，其源码 MDX 文件位于 docs/user/，可用 tools/sync-docs.sh 同步到本地 docs 检出。

两层配置：手写文件与 GUI 覆写

Noctalia 的配置分为两层（详见 docs/user/configuration/index.mdx）：

1. 手写配置，位于$NOCTALIA_CONFIG_HOME/noctalia/、$XDG_CONFIG_HOME/noctalia/或~/.config/noctalia/。Noctalia 读取该目录下所有*.toml文件，按字母序排序后合并成一个配置。单个config.toml是最简单的用法：

# ~/.config/noctalia/config.toml [theme] mode = "dark" [bar.default] position = "top"

也可以拆分维护（如bar.toml、theme.toml、widgets.toml）。NOCTALIA_CONFIG_HOME与标准 XDG 变量有相同的 "home root" 形状：例如NOCTALIA_CONFIG_HOME=/tmp/profile会读取/tmp/profile/noctalia/，适合在不想改变启动应用继承的环境时建立独立的 Shell profile。

2. GUI 托管覆写，位于$NOCTALIA_STATE_HOME/noctalia/settings.toml、$XDG_STATE_HOME/noctalia/settings.toml或~/.local/state/noctalia/settings.toml。通过设置界面、setup 流程、IPC 控制的控件等运行时操作修改的设置都会写入该文件；如果它是符号链接，Noctalia 会写入链接目标并保持链接不变。

合并顺序：谁赢？

加载顺序为：

1. 内置默认值；
2. 配置目录下你的*.toml文件——每个文件先合并其[include]引入的内容，再叠加自身设置；
3. 状态目录settings.toml中的 GUI 托管覆写。

由于settings.toml最后加载，当它与手写配置含有同一设置时，它以胜利者身份生效。当 Settings 写入的值与下层解析值一致时，Noctalia 会删除这个冗余键而不是保留为 GUI 覆写。所以排障口诀是：如果 GUI 修改后你的文件似乎"失效"，去检查~/.local/state/noctalia/settings.toml。

[include]支持引入子目录文件、指定文件或控制加载顺序：

# ~/.config/noctalia/config.toml [include] files = [ "widgets/", # 目录：加载其中每个 *.toml（排序、非递归） "bars/top.toml", # 单个文件 "~/.config/shared/base.toml", # ~ 、$VAR 和 ${VAR} 会被展开 ] [theme] mode = "dark"

相对路径相对于发起 include 的文件所在目录解析；发起 include 的文件自身胜出——被 include 的文件先合并为可复用基础，文件自身的设置叠加其上。include 可以嵌套，每个文件最多加载一次，循环会被检测并跳过。[include]只在你的配置文件中有意义，在 app 管理的settings.toml中无效。

如果需要多套方案并存（如profile_a.toml与profile_b.toml），在入口文件设置autoload = false，则只有设置它的文件（及其 include）会被加载，其余根文件被忽略：

[include] autoload = false files = ["profiles/work.toml"]

热重载与自动迁移

两层目录都会被监听并热重载（config_service.cpp中使用 inotify，mask 为IN_MODIFY | IN_CLOSE_WRITE | IN_MOVED_TO | IN_CREATE，见 src/config/config_service.cpp）。如果两层都不存在，则使用内置默认值。

当新版本改变某个设置的形状时，Noctalia 会在解析前迁移旧值。~/.config/noctalia/下的文件永远不会被改写——需要迁移的值每次加载时在内存中临时归一化，Settings 会保持警告可见，直到你更新源 TOML。警告和通知会标明源文件、行、列和确切的旧键名；settings.toml则会被一次性升级并打上内部config_version标记（该标记不导出到用户配置）。

example.toml：全默认配置速览

仓库根目录的 example.toml 是"所有设置取默认值"的完整参考（复制为~/.config/noctalia/config.toml后按需修改，多数修改通过 inotify 热重载，启动期设置会在文件内标注）。其核心区块如下：

Shell 全局（[shell]）：corner_radius_scale（0=方角、1=默认、2=更圆）、font_family、time_format/date_format（默认{:%H:%M}与%A, %x）、offline_mode（true 时阻断所有对外 HTTP）、telemetry_enabled、polkit_agent、password_style（default|random）、clipboard_enabled、clipboard_history_max_entries（10–10000，未固定条数上限）、clipboard_auto_paste（off|auto|ctrl_v|ctrl_shift_v|shift_insert）、shared_gl_context（启动期设置，false 为故障驱动隔离 GPU 上下文）等。剪贴板有一项值得注意的语义：Wayland 选择集由拥有它的应用提供，应用退出后数据即失效；clipboard_keep_from_closed_apps = true让 Shell 代为认领，使最后复制的条目在来源应用关闭后仍可粘贴（已排除声明x-kde-passwordManagerHint的应用，依赖不声明该提示的密码管理器时建议设为 false）。

Wallpaper（[wallpaper]）：fill_mode（center|crop|fit|stretch|repeat|span）、transition（fade/wipe/disc/stripes/zoom/honeycomb）、transition_duration（毫秒）、directory/directory_light/directory_dark（空 = XDG Pictures 目录）、[wallpaper.automation]（间隔秒数、random|alphabetical 顺序、是否递归）。

Theme（[theme]）：mode（dark|light|auto）、source（builtin|wallpaper|community）、builtin（Ayu、Catppuccin、Dracula、Eldritch、Gruvbox、Kanagawa、Noctalia、Nord、Rosé Pine、Tokyo-Night）、wallpaper_scheme（m3-tonal-spot/m3-content/m3-fruit-salad/m3-rainbow/m3-monochrome/vibrant/faithful/dysfunctional/muted）、pure_black_dark（OLED 纯黑，适用于所有调色板来源）。模板部分[theme.templates]可启用内置/社区模板；用户自定义模板直接在配置中声明：

# [theme.templates.user.my_app] # input_path = "templates/my-app.css" # output_path = "~/.config/my-app/theme.css" # post_hook = "my-app --reload-theme"

Bar（[bar.main]）：position（top|bottom|left|right）、thickness、background_opacity、radius、margin_ends/margin_edge、padding、widget_spacing、scale/font_scale、auto_hide、reserve_space、capsule及胶囊化参数。三个布局槽位定义内容：

start = ["launcher", "wallpaper", "workspaces"] center = ["clock"] end = ["media", "tray", "notifications", "clipboard", "network", "bluetooth", "volume", "brightness", "battery", "control-center", "session"]

还支持死区动作（[bar.main.dead_zone.actions]，如left = "panel-toggle launcher"）与按显示器覆写（[bar.main.monitor.dp1]，match = "DP-1"，仅列出要覆写的字段）。

Dock（[dock]）：默认enabled = false，可设位置、图标大小、边距、透明度、圆角、缩放（active/inactive/magnification）、show_dots、pinned等。

Notification / OSD / Lockscreen：[notification]支持layer（top|overlay）、scale、offset_x/y、动作按钮、DND 过滤（[notification.filter.*]按应用匹配，控制 toast/历史/声音/urgency）；[osd]支持 8 个位置、水平/垂直方向、[osd.kinds]逐个开关 volume/brightness/wifi/bluetooth/power_profile/caffeine/nightlight/dnd/lock_keys/keyboard_layout/privacy 等 OSD；[lockscreen]支持blurred_desktop（需 wlr-screencopy）、模糊/着色强度、独立壁纸与按显示器显示。

服务类：[system.monitor]（CPU/内存/网络/温度/GPU VRAM/磁盘的轮询周期与 CPU 频率阈值）、[calendar]（CalDAV/Google，默认关闭）、[weather]、[audio]（enable_overdrive允许音量超过 100% 至 150%）、[brightness]（enable_ddcutil及按显示器后端auto|none|backlight|ddcutil）、[nightlight]（色温，默认 6500K 白天/4000K 夜晚）、[location]（单一"我在哪里"来源，同时供 Weather、Night Light 与 Theme auto 模式使用）、[idle]（lock/screen-off 行为，支持pre_action_fade_seconds渐变覆盖层）。

Keybinds（[keybinds]）：定义 Shell 内的导航键——validate/cancel/left/right/up/down/tab_next/tab_previous/delete，默认值如["return", "kp_enter", "space"]、["escape"]等。

Hooks（[hooks]）：事件驱动自动化，支持started、wallpaper_changed、theme_mode_changed（环境变量$NOCTALIA_THEME_MODE）、session_locked、battery_state_changed（$NOCTALIA_BATTERY_STATE）、battery_under_threshold（${NOCTALIA_BATTERY_PERCENT}%）、power_profile_changed等，均配置为 shell 命令。

这些配置项都有对应的类型化 schema 在源码中（如 src/config/schema/config_schema.cpp 中的audioSchema、osdSchema、backdropSchema、lockscreenSchema等），校验会给出带文件、行、列的诊断信息。

校验与导出配置

校验（发现潜在问题再让它静默生效）：

noctalia config validate # 校验合并后的配置（含 settings.toml） noctalia config validate ./my-config-dir # 只校验指定目录的 *.toml noctalia config validate ./config.toml # 只校验单个文件（不合并 settings.toml）

诊断带文件、行、列前缀，随后是点分配置路径：

WARN /home/you/.config/noctalia/bar.toml:14:10: bar.main.foo: unknown setting ERROR /home/you/.config/noctalia/widgets.toml:22:12: widget.clock.timezone: unknown timezone "Europe/Berln"

错误（TOML 语法、解析失败的值、非法跨字段组合、include 指向不存在的路径等）退出码为 1；警告（未知/过时设置、有规范替代的值、越界被钳制的值、非法枚举）只是提示，不导致失败。只有警告时仍输出✓ Config is valid并退出 0，因此未知键不会破坏 pre-commit 钩子或 CI。Shell 日志带同样的前缀，屏幕上的配置错误通知会把位置放在标题里（如config.toml:22:12）。

导出（合并后的用户配置，stdout 输出）：

noctalia config export > noctalia-config.toml # 合并用户配置 noctalia config export full > noctalia-full-config.toml # 完整有效配置（含内置默认）

导出在任一配置解析失败或 include 指向不存在的文件时以错误终止且不写任何内容，保证损坏的配置不会产生误导性的部分导出。因为输出是 TOML，可管道给yq等 TOML 感知工具：

noctalia config export full | yq -p toml -r '.theme.mode' noctalia config export full | yq -p toml -r '.shell.offline_mode' noctalia config export full | yq -p toml '.bar.default'

Settings 的 actions 菜单也提供 Export Config...：Merged User Config（推荐用于 dotfiles，合并显式配置与 GUI 覆写，隐含默认值）与Full Effective Config（导出含默认值的当前快照，适合检查或分享精确状态，但不适合长期维护，因为它会钉住本可演进的默认值）。

文件位置速查

可以归纳为三个存储所有者：你的（~/.config/noctalia/与~/.local/share/noctalia/）、Noctalia 的（~/.local/state/noctalia/）与凭据提供者的（Secret Service 或外部供应器管理的凭据/密钥文件——删除 Noctalia 的状态目录不会移除它们）。

IPC 与自动化

Noctalia 通过noctalia msg提供运行时 IPC 命令，供快捷键、脚本、自动化与 hooks 使用（CLI 解析在 src/ipc/cli.cpp 的runCli实现，要求noctalia msg <command>形式，支持noctalia msg --help与每个子命令的--help）。example.toml 中给出了多个内联示例，例如：

noctalia msg clipboard-clear noctalia msg notification-invoke-latest noctalia msg notification-clear-active noctalia msg notification-clear-history noctalia msg session lock

hooks 中的[hooks]键值对即通过这些命令与 shell 命令组合实现事件驱动自动化；tools/下还有通知相关的集成测试脚本（如 tools/notifications-test.sh、tools/notifications-inline-reply-test.sh）可以验证通知管线。

从 README 继续深入

• 安装：发行版包选项与手动安装步骤见 docs/user/getting-started/installation.mdx；
• 运行：从合成器启动 Shell、配置快捷键见 docs/user/getting-started/running-the-shell.mdx；
• 配置：合并顺序、热重载与 GUI 覆写详见 docs/user/configuration/index.mdx；
• Shell 细节：全局 UI 缩放、字体、动画、阴影、OSD、锁屏、快捷键见 docs/user/configuration/shell.mdx；
• 自动化：事件驱动 hooks 见 docs/user/automation/；
• 栏与部件：docs/user/bar/ 与 docs/user/bar/ 下的 widgets 文档覆盖顶栏及内部小部件；
• 插件：Luau 插件安装与配置见 docs/user/plugins/；
• 开发者：架构概览、代码风格、项目布局与调试命令见 CONTRIBUTING.md（含dev.noctalia.DebugD-Bus 服务的SetVerboseLogs等调试命令）；
• 打包：发行版打包说明（描述、依赖、安装布局、Meson 选项）见 PACKAGING.md；
• Nix：nix/ 提供 NixOS/home-manager/hjem 模块与 devshell，根目录 flake.nix 可直接使用。

简而言之，Noctalia 用一个内聚的原生 Shell 层替代了"顶栏 + 启动器 + 通知 + 锁屏 + 壁纸"的碎片化拼接，把配置统一进 TOML、把扩展交给 Luau 插件、把边界明确在"Shell 而非桌面环境"。对想要可控、可配置且视觉一致的 Wayland 桌面的用户来说，从 example.toml 起步、按 BUILDING.md 构建、以 docs/user/ 为参考，是完整的上手路径。

• 桌面应用