> 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 BSPWM dotfiles 的 Arch Linux 黑客配置指南，涵盖快速安装、主题、Polybar、Rofi、ZSH、Neovim、命令和键盘快捷键。

[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"
退出
```

检查网络：

```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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.