> For the complete documentation index, see [llms.txt](https://hacking-notes.jord4n.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hacking-notes.jord4n.pro/zh/useful-resources/gh0stzk-bspwm-dotfiles.md).

# 使用 BSPWM 的 Arch Linux 黑客环境搭建

[gh0stzk/dotfiles](https://github.com/gh0stzk/dotfiles) 这是一个适用于 Arch Linux 和基于 Arch 的发行版的完整 BSPWM 桌面环境。它包含主题、状态栏、启动器、终端设置、ZSH、Neovim、Rofi 小程序、壁纸，以及用于快速切换样式的辅助脚本。

<figure><img src="https://user-images.githubusercontent.com/67278339/221605474-21d65156-0cf7-485c-bd1a-40792c37817e.png" alt="gh0stzk BSPWM dotfiles desktop screenshot with terminal and Linux fetch output"><figcaption><p>项目 README 中的 BSPWM 桌面环境示例。</p></figcaption></figure>

{% hint style="warning" %}
仅在个人实验室机器或全新的 Linux 工作站上安装此项。Dotfiles 会替换许多用户配置文件，因此在运行前请先查看安装程序并备份当前设置。
{% endhint %}

## 适用场景

这属于 `实用资源` 因为它是工作站配置资源，而不是渗透测试工具。当你想要一个干净的基于 Arch 的 BSPWM 环境，用于日常笔记、实验室、CTF 工作、开发以及重度终端工作流时，可以使用它。

## 它能为你提供什么

| 组件         | 含义                                                 |
| ---------- | -------------------------------------------------- |
| BSPWM      | 用于快速、键盘驱动桌面的平铺窗口管理器。                               |
| 18 个主题     | 可随时切换的预制视觉样式。                                      |
| Polybar    | 包含工作区、模块、系统信息和主题颜色的桌面栏。                            |
| Rofi 小程序   | 用于应用、电源、截图、剪贴板、网络、蓝牙、壁纸等的菜单。                       |
| 终端         | 支持 Alacritty、Kitty、Ghostty、ST 和 Xfce Terminal 的主题。 |
| ZSH 配置     | 带有补全、历史搜索和 fzf-tab 预览的快速 shell 设置。                 |
| Neovim 配置  | 预先构建好的编辑器配置，包含 LSP、补全、格式化、文件浏览器、状态栏和仪表盘。           |
| RiceEditor | 用于调整视觉设置的辅助应用，无需手动编辑每个配置。                          |

## 视觉预览

这个项目非常注重视觉效果，所以安装前请先查看截图和演示。

<figure><img src="https://github.com/gh0stzk/dotfiles/assets/67278339/b11b5c58-b9ec-446b-8980-4f77bebb3432" alt="gh0stzk dotfiles theme selector screenshot"><figcaption><p>主题选择器。</p></figcaption></figure>

<figure><img src="https://github.com/user-attachments/assets/dbac8c47-f12c-4242-97d6-38ad1193f76b" alt="gh0stzk dotfiles wallpaper selector screenshot"><figcaption><p>壁纸选择器。</p></figcaption></figure>

<figure><img src="https://github.com/user-attachments/assets/2ac910c8-171f-47eb-8210-1469b6f75cc2" alt="gh0stzk dotfiles RiceEditor screenshot"><figcaption><p>用于主题自定义的 RiceEditor。</p></figcaption></figure>

### 项目演示

{% embed url="<https://github.com/user-attachments/assets/3eaae1e2-04dc-4a9b-8c91-139f85f5fb9e>" %}

### Arch 安装教程

如果你想在应用这些 dotfiles 之前先进行一次干净的 Arch 安装，这个作者视频会很有用。

{% embed url="<https://www.youtube.com/watch?v=mspY7Mpmcug>" %}

### 项目频道

作者的频道里有更多 BSPWM、Polybar、Eww、Rofi 和主题演示。

{% embed url="<https://www.youtube.com/@gh0stzk-dotfiles>" %}

## 安装前

官方安装程序适用于 Arch Linux 和基于 Arch 的发行版。README 指出，不支持 Artix 等非 systemd 发行版。

推荐起点：

| 要求                 | 备注                                 |
| ------------------ | ---------------------------------- |
| Arch 或基于 Arch 的发行版 | 全新安装最安全。                           |
| 普通用户账户             | 不要以 root 身份运行安装程序。                 |
| 可用网络               | 安装程序会下载软件包和仓库。                     |
| 登录管理器              | 项目推荐使用 LightDM。                    |
| NetworkManager     | Rofi 网络小程序需要它。                     |
| 备份                 | 保留现有文件的副本 `~/.config` 以及 shell 文件。 |

测试前有用的备份命令：

```bash
mkdir -p "$HOME/dotfiles-backup"
cp -a "$HOME/.config" "$HOME/dotfiles-backup/config-$(date +%F)" 2>/dev/null
cp -a "$HOME/.zshrc" "$HOME/.gtkrc-2.0" "$HOME/.icons" "$HOME/dotfiles-backup/" 2>/dev/null
```

## 快速 Arch 配置

当你从一台干净的 Arch 机器或虚拟机开始，并希望走最短的实用路径时，使用这个方案。

### 1. 启动 Arch ISO

从官方 Arch ISO 开始。如果你使用 Wi‑Fi，请先连接：

```bash
iwctl
```

在 `iwctl`:

```
device list
station wlan0 scan
station wlan0 get-networks
station wlan0 connect "SSID"
exit
```

检查网络：

```bash
ping -c 3 archlinux.org
```

同步时间：

```bash
timedatectl set-ntp true
```

### 2. 快速安装 Arch

快速路线是 `archinstall`:

```bash
archinstall
```

推荐选择：

| 选项    | 选择                                                                           |
| ----- | ---------------------------------------------------------------------------- |
| 磁盘布局  | 根据你的虚拟机/磁盘，使用默认或手动。                                                          |
| 引导加载器 | `systemd-boot` 适用于 UEFI；如果你更喜欢，也可以用 GRUB。                                    |
| 配置方案  | 最简即可；桌面环境可选。                                                                 |
| 网络    | NetworkManager。                                                              |
| 音频    | PipeWire。                                                                    |
| 用户    | 创建一个具有 sudo 权限的普通用户。                                                         |
| 额外软件包 | `git curl base-devel xorg-server lightdm lightdm-gtk-greeter networkmanager` |

安装后：

```bash
重启
```

### 3. 启用基础组件

以普通用户登录，然后确保基础服务已准备好：

```bash
sudo pacman -Syu
sudo pacman -S --needed git curl base-devel xorg-server lightdm lightdm-gtk-greeter networkmanager
sudo systemctl enable --now NetworkManager
sudo systemctl enable lightdm
```

如果你刚启用了 LightDM，请再重启一次：

```bash
sudo reboot
```

## Dotfiles 安装

从你的主目录打开终端：

```bash
cd "$HOME"
```

下载官方安装程序：

```bash
curl -LO http://gh0stzk.github.io/dotfiles/RiceInstaller
```

在执行前先检查安装程序：

```bash
less RiceInstaller
```

赋予其执行权限：

```bash
chmod +x RiceInstaller
```

以普通用户身份运行它：

```bash
./RiceInstaller
```

安装程序是交互式的。它可能会询问你是否要安装附带的 Neovim 和 Firefox 配置。请阅读每个提示，不要一路按回车。

### 一键安装

如果你已经有可用的 Arch 系统，想快速进行实验室安装：

```bash
cd "$HOME"
curl -LO http://gh0stzk.github.io/dotfiles/RiceInstaller
less RiceInstaller
chmod +x RiceInstaller
./RiceInstaller
```

## 安装程序会做什么

从高层来看，安装程序会：

1. 检查它是否不是以 root 身份运行。
2. 检查它是否正在从 `$HOME`.
3. 添加 `gh0stzk-dotfiles` 软件仓库。
4. 添加 Chaotic-AUR。
5. 下载 dotfiles。
6. 在需要时备份现有的用户配置。
7. 安装 BSPWM 环境。
8. 启用 MPD 音乐功能。
9. 将 shell 更改为 ZSH。

脚本还会在替换前把许多现有配置文件夹移动到备份目录中。不过，仍然请先保留你自己的备份。

## 首次登录

安装后：

1. 重启或注销。
2. 在登录管理器中选择 BSPWM 会话。
3. 正常登录。
4. 等待首次启动完成自动配置。
5. 测试终端、Rofi、Polybar、主题选择器和壁纸选择器。

如果你在虚拟机中，桌面感觉异常或缓慢，可以先把 Picom 从 `glx` 更改为 `xrender` 改掉，再判断是否是安装失败。

## 首次需要检查的内容

首次启动后，请核实与硬件相关的变量。打开：

```bash
~/.config/bspwm/config/system.ini
```

检查以下值：

| 值      | 重要原因        |
| ------ | ----------- |
| 网络接口   | 状态栏中的网络模块。  |
| 显卡     | 一些视觉和状态模块。  |
| 电池和适配器 | 笔记本电池和亮度模块。 |

如果你用的是台式机，通常主要需要关注网络接口。

## 有用命令

| 命令                                  | 使用               |
| ----------------------------------- | ---------------- |
| `RiceSelector`                      | 打开主题选择器。         |
| `RiceEditor`                        | 可视化编辑当前主题。       |
| `WallSelect`                        | 打开壁纸选择器。         |
| `Term --selecterm`                  | 选择终端应用。          |
| `OpenApps --menu`                   | 打开应用启动器。         |
| `OpenApps --KeyHelp`                | 打开按键速查表。         |
| `OpenApps --screenshot`             | 打开截图工具。          |
| `OpenApps --netmanager`             | 打开网络管理器小程序。      |
| `OpenApps --bluetooth`              | 打开蓝牙小程序。         |
| `OpenApps --clipboard`              | 打开剪贴板管理器。        |
| `OpenApps --powermenu`              | 打开电源菜单。          |
| `OpenApps --keyboard`               | 打开键盘布局小程序。       |
| `OpenApps --scratch`                | 打开临时草稿区。         |
| `HideBar -h`                        | 隐藏状态栏。           |
| `HideBar -u`                        | 显示状态栏。           |
| `SoftReload`                        | 软重载环境。           |
| `ScreenLocker`                      | 锁定屏幕。            |
| `bspc wm -r`                        | 重新加载 BSPWM。      |
| `pkill -USR1 -x sxhkd`              | 重新加载按键绑定。        |
| `~/.config/bspwm/config/system.ini` | 安装后需要验证的硬件/模块变量。 |
| `~/.config/bspwm/config/sxhkdrc`    | 主要按键绑定文件。        |

## 完整快捷键

项目通过以下方式显示可视化速查表： `Alt + F1`. `Super键` 在大多数键盘上表示 Windows 键。真实来源是已安装的 `~/.config/bspwm/config/sxhkdrc`；此表遵循当前上游文件，并将每个快捷键分组，以便更容易浏览。

### 帮助

| 按键         | 操作       |
| ---------- | -------- |
| `Alt + F1` | 显示按键速查表。 |

### 主应用

| 按键                     | 操作               |
| ---------------------- | ---------------- |
| `Super + Return`       | 打开普通终端。          |
| `Super + Alt + Return` | 打开浮动终端。          |
| `Super + Space`        | 打开应用启动器。         |
| `Alt + Space`          | 打开主题选择器。         |
| `Super + B`            | 打开浏览器。           |
| `Super + E`            | 打开编辑器。           |
| `Super + F`            | 打开文件管理器。         |
| `Super + Y`            | 打开 Yazi。         |
| `Super + V`            | 打开 Neovim。       |
| `Super + M`            | 打开音乐播放器/Ncmpcpp。 |
| `Super + P`            | 打开 Pavucontrol。  |
| `Super + T`            | 打开 Telegram。     |
| `Super + W`            | 打开 WhatsApp。     |
| `Super + R`            | 打开 RiceEditor。   |

### Rofi 小程序

| 按键                | 操作              |
| ----------------- | --------------- |
| `Super + Alt + T` | 终端选择器。          |
| `Super + Alt + W` | 壁纸选择器。          |
| `Super + Alt + A` | Android 挂载小程序。  |
| `Super + Alt + N` | 网络管理器。          |
| `Super + Alt + B` | 蓝牙管理器。          |
| `Super + Alt + C` | 剪贴板管理器。         |
| `Super + Alt + S` | 截图工具。           |
| `Super + Alt + P` | 电源菜单。           |
| `Super + Alt + L` | Rofi 启动器样式选择器。  |
| `Super + Alt + K` | 键盘布局小程序。        |
| `Super + Alt + X` | RofiPass/密码小程序。 |
| `在桌面上右键单击`        | 打开 Jgmenu。      |

### 系统与环境

| 按键                       | 操作            |
| ------------------------ | ------------- |
| `Super + Alt + O`        | 临时草稿区。        |
| `Ctrl + Super + Alt + P` | 关闭计算机电源。      |
| `Ctrl + Super + Alt + R` | 重启计算机。        |
| `Ctrl + Super + Alt + Q` | 注销。           |
| `Ctrl + Super + Alt + L` | 锁定屏幕。         |
| `Ctrl + Super + Alt + K` | 使用 `xkill`.   |
| `Ctrl + Super + Alt + S` | 软重载。          |
| `Super + Alt + H`        | 隐藏栏。          |
| `Super + Alt + U`        | 显示栏。          |
| `Ctrl + Alt + Plus`      | 增加当前聚焦窗口的透明度。 |
| `Ctrl + Alt + Minus`     | 降低当前聚焦窗口的透明度。 |
| `Ctrl + Alt + T`         | 重置当前聚焦窗口的透明度。 |
| `XF86MonBrightnessUp`    | 提高亮度。         |
| `XF86MonBrightnessDown`  | 降低亮度。         |
| `XF86AudioRaiseVolume`   | 提高音量。         |
| `XF86AudioLowerVolume`   | 降低音量。         |
| `XF86AudioMute`          | 切换静音。         |
| `XF86AudioNext`          | 下一首媒体。        |
| `XF86AudioPrev`          | 上一首媒体。        |
| `XF86AudioPlay`          | 播放/暂停媒体。      |
| `XF86AudioStop`          | 停止媒体播放。       |

### BSPWM 核心

| 按键                  | 操作               |
| ------------------- | ---------------- |
| `Super + Alt + R`   | 重新加载 BSPWM。      |
| `Super + X`         | 关闭当前聚焦节点。        |
| `Super + Shift + X` | 强制结束当前聚焦节点。      |
| `Super + Escape`    | 重新加载 sxhkd 键位绑定。 |

### 节点状态与标志

| 按键                | 操作             |
| ----------------- | -------------- |
| `Alt + T`         | 将节点设为平铺。       |
| `Alt + Shift + T` | 将节点设为伪平铺。      |
| `Alt + A`         | 将节点设为浮动。       |
| `Alt + F`         | 将节点设为全屏。       |
| `Alt + M`         | 切换标记标志。        |
| `Alt + X`         | 切换锁定标志。        |
| `Alt + S`         | 切换粘滞标志。        |
| `Alt + P`         | 切换私有标志。        |
| `Alt + H`         | 隐藏当前聚焦窗口。      |
| `Ctrl + Alt + H`  | 显示用于恢复隐藏窗口的菜单。 |

### 工作区与焦点

| 按键                                        | 操作                    |
| ----------------------------------------- | --------------------- |
| `Ctrl + Tab`                              | 旋转桌面。                 |
| `Super + Left`                            | 切换到上一个工作区。            |
| `Super + Right`                           | 切换到下一个工作区。            |
| `Super + 1` 更改为 `Super + 9`               | 聚焦工作区 1 到 9。          |
| `Super + 0`                               | 聚焦工作区 10。             |
| `Super + Ctrl + 1` 更改为 `Super + Ctrl + 9` | 将当前聚焦窗口发送到工作区 1 到 9。  |
| `Super + Ctrl + 0`                        | 将当前聚焦窗口发送到工作区 10。     |
| `Super + Ctrl + Left`                     | 将当前聚焦窗口发送到上一个工作区并跟随。  |
| `Super + Ctrl + Right`                    | 将当前聚焦窗口发送到下一个工作区并跟随。  |
| `Alt + Tab`                               | 窗口切换器。                |
| `Super + Alt + Left`                      | 将焦点切换到西侧窗口，失败则切换到前一个。 |
| `Super + Alt + Down`                      | 将焦点切换到南侧窗口。           |
| `Super + Alt + Up`                        | 将焦点切换到北侧窗口。           |
| `Super + Alt + Right`                     | 将焦点切换到东侧窗口，失败则切换到下一个。 |
| `Ctrl + Alt + Left`                       | 将当前聚焦窗口与西侧窗口交换。       |
| `Ctrl + Alt + Down`                       | 将当前聚焦窗口与南侧窗口交换。       |
| `Ctrl + Alt + Up`                         | 将当前聚焦窗口与北侧窗口交换。       |
| `Ctrl + Alt + Right`                      | 将当前聚焦窗口与东侧窗口交换。       |
| `Ctrl + Shift + Comma`                    | 聚焦上一个节点。              |
| `Ctrl + Shift + Period`                   | 聚焦上一个桌面。              |

### 预选择

| 按键                 | 操作           |
| ------------------ | ------------ |
| `Super + Ctrl + H` | 预先选择水平/向东分割。 |
| `Super + Ctrl + V` | 预先选择垂直/向南分割。 |
| `Super + Ctrl + Q` | 取消预选择。       |

### 移动与调整大小

| 按键                      | 操作         |
| ----------------------- | ---------- |
| `Super + Ctrl + B`      | 平衡桌面节点。    |
| `Super + Alt + Plus`    | 增大平铺节点大小。  |
| `Super + Alt + Minus`   | 减小平铺节点大小。  |
| `Super + Ctrl + Plus`   | 增大浮动节点大小。  |
| `Super + Ctrl + Minus`  | 减小浮动节点大小。  |
| `Super + Shift + Left`  | 将浮动窗口向左移动。 |
| `Super + Shift + Down`  | 将浮动窗口向下移动。 |
| `Super + Shift + Up`    | 将浮动窗口向上移动。 |
| `Super + Shift + Right` | 将浮动窗口向右移动。 |

### 多重操作

| 按键                         | 操作                |
| -------------------------- | ----------------- |
| `Super + Ctrl + X`         | 关闭当前桌面中的所有节点。     |
| `Super + N`，然后 `X`         | 关闭所有未聚焦的本地窗口。     |
| `Super + N`，然后 `K`         | 强制结束所有未聚焦的本地窗口。   |
| `Super + N`，然后 `M`         | 将所有标记的窗口移到当前聚焦桌面。 |
| `Super + N`，然后 `1` 更改为 `9` | 将该桌面的所有窗口移到当前桌面。  |

## 常用自定义

### 更改主题

使用：

```
Alt + Space
```

从选择器中挑选一个主题。环境会更新，无需重启整个会话。

### 更改壁纸

使用：

```
Super + Alt + W
```

该项目支持随机壁纸、自定义目录、固定壁纸、动态壁纸以及幻灯片轮播行为。

### 编辑当前主题

当你想调整视觉设置而无需手动编辑每个模块时，请使用 RiceEditor：

```
RiceEditor
```

常见修改包括边框、阴影、动画、透明度、壁纸行为以及主题特定的模块设置。

## 故障排除

| 问题          | 检查内容                                                 |
| ----------- | ---------------------------------------------------- |
| 登录后又返回显示管理器 | 确认已安装 BSPWM 会话并查看 `~/.xsession-errors`.              |
| 状态栏模块不正确    | 检查 `~/.config/bspwm/config/system.ini`.              |
| 网络小程序无法工作   | 确认 NetworkManager 已安装并正在运行。                          |
| 虚拟机图形显示异常   | 尝试 Picom `xrender` 后端，而不是 `glx`.                     |
| 键盘快捷键失效     | 检查 `sxhkd` 正在运行并查看 `~/.config/bspwm/config/sxhkdrc`. |
| 主题看起来错位     | 该项目是围绕 1600x900 和 96 DPI 设计的；请根据你的显示器进行调整。           |
| 现有配置消失了     | 检查安装程序创建的备份文件夹以及你自己的 `dotfiles-backup`.              |

## 全新重装说明

为了最安全地重新尝试：

1. 备份你当前的文件。
2. 删除或移动旧的 dotfiles 目录。
3. 重新下载最新的 `RiceInstaller`.
4. 再次检查脚本。
5. 从……运行 `$HOME` 以普通用户身份。

除非你已查看差异，否则不要运行来自第三方分支的随机修改版安装程序。

## 参考资料

* [gh0stzk/dotfiles 官方仓库](https://github.com/gh0stzk/dotfiles)
* [RiceInstaller](https://github.com/gh0stzk/dotfiles/blob/master/RiceInstaller)
* [安装后的第一步](https://github.com/gh0stzk/dotfiles/wiki/First-steps-after-installation)
* [键盘快捷键维基](https://github.com/gh0stzk/dotfiles/wiki/Keyboard-Shortcuts)
* [当前 sxhkdrc 键位绑定文件](https://github.com/gh0stzk/dotfiles/blob/master/config/bspwm/config/sxhkdrc)
* [壁纸配置维基](https://github.com/gh0stzk/dotfiles/wiki/Wallpapers-Configuration)
* [ArchWiki：bspwm](https://wiki.archlinux.org/title/Bspwm)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://hacking-notes.jord4n.pro/zh/useful-resources/gh0stzk-bspwm-dotfiles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.