> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/di-20-zhang-linux-jian-rong-ceng/di-20.8-jie-qq-linux-ban.md).

# 20.8 QQ（Linux 版）

QQ 尚无原生 FreeBSD 版本，须通过 Linux 兼容层安装运行。本节分别给出基于 Rocky Linux（FreeBSD Port）和基于 Ubuntu（debootstrap）两种兼容层方案的安装步骤。

## 基于 Rocky Linux（FreeBSD Port）

> **注意**
>
> 请先参照本书其他章节安装 Rocky Linux 兼容层（FreeBSD Port）。

### 安装 RPM 工具

参考本书其他相关章节安装 RPM 工具（`pkg install rpm4`）。

### 下载安装 QQ

* 下载 QQ，官方链接：[QQ Linux 版 - 轻松做自己](https://im.qq.com/linuxqq/index.shtml)。

```sh
# fetch https://dldir1.qq.com/qqfile/qq/QQNT/Linux/QQ_3.2.17_250521_x86_64_01.rpm # 本节撰写时的链接，实际使用时请获取最新版本
```

* 安装 QQ：

```sh
root@ykla:/ # cd /compat/linux/	# 切换到兼容层路径
root@ykla:/compat/linux # rpm2cpio < /home/ykla/QQ_3.2.17_250521_x86_64_01.rpm | cpio -id # 安装 QQ，请将文件路径替换为本地实际路径
./usr/share/icons/hicolor/512x512/apps/qq.png: Cannot extract through symlink usr/share/icons/hicolor/512x512/apps/qq.png
1055863 blocks
```

> **技巧**
>
> 本节示例中出现的用户名 `ykla`、主机名 `ykla` 及路径 **/home/ykla** 均为示例，请根据自身环境替换为实际值。

相关文件结构：

```sh
/compat/linux/
├── opt/
│   └── QQ/
│       └── qq # QQ 可执行文件
└── usr/
    └── share/
        └── icons/
            └── hicolor/
                └── 512x512/
                    └── apps/
                        └── qq.png # QQ 图标
```

### 依赖库

查看依赖项：

```sh
# /compat/linux/usr/bin/bash # 切换到兼容层的 Shell
bash-5.1# ldd /opt/QQ/qq # 查看 QQ 可执行文件的动态库依赖
	linux-vdso.so.1 (0x00007fffffffe000)
	libffmpeg.so => /opt/QQ/libffmpeg.so (0x000000080c000000)
	.......此处省略部分输出......
```

可看到 `ldd` 输出正常，无需解决依赖问题。

### 解决 Fcitx 中文输入法在 QQ 中无法使用的问题

在兼容层中安装 `ibus-gtk3` 和 `ibus-libs`，下载安装包后执行：

```sh
# fetch https://dl.rockylinux.org/pub/rocky/9/AppStream/x86_64/os/Packages/i/ibus-gtk3-1.5.25-6.el9.x86_64.rpm   # 下载 ibus-gtk3 RPM 包
# fetch https://dl.rockylinux.org/pub/rocky/9/AppStream/x86_64/os/Packages/i/ibus-libs-1.5.25-6.el9.x86_64.rpm   # 下载 ibus-libs RPM 包
# cd /compat/linux   # 切换到 Linux 兼容目录
# rpm2cpio < /home/ykla/ibus-gtk3-1.5.25-6.el9.x86_64.rpm | cpio -id   # 解压 ibus-gtk3 RPM 包
# rpm2cpio < /home/ykla/ibus-libs-1.5.25-6.el9.x86_64.rpm | cpio -id   # 解压 ibus-libs RPM 包
```

* 刷新输入法模块缓存：

```sh
# /compat/linux/usr/bin/bash # 切换到 Rocky Linux 的 bash
bash-5.1# gtk-query-immodules-3.0-64 --update-cache   # 刷新缓存
```

### 启动 QQ

在 Linux 兼容环境中启动 QQ，禁用沙盒并启用进程内 GPU：

```sh
$ /compat/linux/opt/QQ/qq --no-sandbox --in-process-gpu
```

> **注意**
>
> 此处务必以普通用户权限运行 QQ，否则无法使用输入法。

> **技巧**
>
> `--no-sandbox` 选项用于关闭沙盒，否则无法运行 QQ。
>
> `--in-process-gpu` 选项也是必要的，否则退出后无法重新打开 QQ，须重启系统方可使用。

![FreeBSD QQ](/files/Fta1TUed13PQ7P3T6tjs)

Fcitx5 输入法正常：

![FreeBSD QQ](/files/7Hx9URNvHES8InIm9IH6)

## 基于 Arch Linux 的兼容层

请参阅本书中“Arch Linux 兼容层”部分。

```sh
# chroot /compat/arch/ /bin/bash # 进入 Arch 兼容层
# passwd # 为 Arch 的 root 设置密码
# passwd test # 为 test 用户设置密码（上述脚本已创建），否则可能无法正常使用 AUR

```

请新开一个终端，输入 `reboot` 重启 FreeBSD，否则新设置的密码无法生效。

```sh
# chroot /compat/arch/ /bin/bash # 进入 Arch 兼容层
# su test # 切换到普通用户才能使用 AUR，此时位于 Arch 兼容层
$ yay -S linuxqq # 当前用户为 test，位于 Arch 兼容层
$ exit # 切换回 root
# # 已切换回 root，位于 Arch 兼容层
```

启动 QQ 客户端，禁用沙盒并启用进程内 GPU：

```sh
# /opt/QQ/qq --no-sandbox --in-process-gpu # 此时位于 Arch 兼容层！
```

> **注意**
>
> 如以普通用户运行 QQ 时提示找不到 X11 的错误，请检查 `DISPLAY` 环境变量是否正确设置，并确保 X11 套接字（**/tmp/.X11-unix/**）对普通用户可访问。可尝试运行 `xhost +local:` 命令放宽权限。

![FreeBSD QQ](/files/ldKnwUeAU4yJ1HPCfZKF)

![FreeBSD QQ](/files/VDVTTtyhyEs4LgtkS2cD)

## 基于 Ubuntu 兼容层

请先构建 Ubuntu 兼容层环境。

```sh
# chroot /compat/ubuntu/ /bin/bash # 进入 Ubuntu 兼容层
# wget https://dldir1v6.qq.com/qqfile/qq/QQNT/Linux/QQ_3.2.18_250626_amd64_01.deb # 下载 QQ，此时位于 Ubuntu 兼容层
```

在 Ubuntu 兼容层安装 QQ：

```bash
# apt install ./QQ*.deb
```

安装依赖文件：

```sh
# apt install libgbm-dev libasound2-dev # 在 Ubuntu 兼容层安装依赖
# ldconfig # 刷新动态链接库，此时位于 Ubuntu 兼容层
```

启动 QQ：

```sh
# /bin/qq --no-sandbox --in-process-gpu # 此时位于 Ubuntu 兼容层
```

> **注意**
>
> 此处必须以 root 用户运行 QQ，并确保按照 Ubuntu 兼容层构建教程设置中文字符集（使用脚本时，该过程会自动完成，无需手动操作）。

![FreeBSD QQ](/files/eHz1fT7OxcGN7Nsm4dae)

## 故障排除

### 网络错误

如系统中有多块网卡，例如一块有线网卡和一块无线网卡，打开 QQ 后出现网络错误提示，此时须为未使用的网卡分配一个 IP 地址。

参见其他相关章节。

### 中文输入法

> **注意**
>
> 在兼容层内部安装输入法是无效的。

如自行构建兼容层，启动 QQ 前须在兼容层内部设定以下中文环境变量（完全按照本书教程操作则无需此步骤，过程中已指定这些变量）：

```sh
# export LANG=zh_CN.UTF-8   # 设置系统语言为中文
# export LC_ALL=zh_CN.UTF-8 # 设置所有本地化环境变量为中文
```

设置完成后可使用 `locale` 命令检查。对于兼容层的软件，Fcitx 输入法仅当上述两个变量设为中文环境时方可生效。

如设置失败，请重启 FreeBSD 系统。

### QQ 闪退

在兼容层中执行以下操作：

```sh
$ rm ~/.config/QQ/crash_files/*                 # 删除 QQ 崩溃文件目录下的所有文件
$ chmod a-wx ~/.config/QQ/crash_files/          # 将 QQ 崩溃文件目录设为不可写不可执行，防止生成更多崩溃日志导致闪退
```

相关文件结构：

```sh
~/
└── .config/
    └── QQ/
        └── crash_files/ # QQ 崩溃文件目录
```

#### 参考文献

* 微恙. Linux 下新 QQ Bug\&Fix 一记（闪退相关）\[EB/OL]. \[2026-03-25]. <https://zhuanlan.zhihu.com/p/645895811>. 该文章提供了 Linux 版 QQ 闪退问题的解决方案。
* X.Org Foundation. xhost(1)\[EB/OL]. \[2026-04-17]. <https://man.openbsd.org/xhost.1>. 说明了 X11 访问控制机制及 `xhost` 命令的使用方法。


---

# 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://book.bsdcn.org/di-20-zhang-linux-jian-rong-ceng/di-20.8-jie-qq-linux-ban.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.