WSL下Qt6 C++应用的盲文字符渲染异常问题

核心原因 #

不同启动方式下环境变量差异导致Qt无法正确加载指定的DejaVu Sans Mono字体，触发字体 fallback机制，使用了不支持盲文字符的替代字体，最终出现空心方块渲染错误，同时字体度量值（tileWidth）异常。

直接运行或简单脚本启动时，Shell环境继承了完整的系统环境变量（如XDG_DATA_DIRS、QT_QPA_FONTDIR），Qt能正常定位到DejaVu字体；而带路径解析的脚本或nvim-dap启动时，环境变量被截断或未正确传递，导致Qt找不到目标字体。

验证步骤 #

先在代码中添加日志，确认实际加载的字体是否符合预期：

void BrailleCanvas::updateGrid(){
    brailleFont = QFont("DejaVu Sans Mono", fontSize);
    QFontInfo fontInfo(brailleFont);
    qDebug() << "实际使用字体:" << fontInfo.family();
    QFontMetrics fm(brailleFont);
    tileWidth = fm.horizontalAdvance("⣿");
}

运行后如果输出不是DejaVu Sans Mono，则证明字体 fallback是问题根源。

解决方案 #

1. 确保启动时传递完整环境变量 #

在启动脚本中显式继承系统环境，或手动设置字体相关变量：

#!/bin/bash
SCRIPT_DIR="$(dirname "$(realpath "$0")")"
PROGRAM_PATH="$SCRIPT_DIR/braille-drawer"
# 显式设置Qt字体目录（根据实际字体路径调整）
export QT_QPA_FONTDIR=/usr/share/fonts/truetype/dejavu/
# 确保XDG_DATA_DIRS包含系统字体路径
export XDG_DATA_DIRS="/usr/share:/usr/local/share:$XDG_DATA_DIRS"
"$PROGRAM_PATH" &

2. 将字体打包到应用资源（推荐） #

把DejaVu Sans Mono字体文件添加到Qt资源系统，避免依赖系统环境：

1. 在项目中创建resources.qrc文件，添加字体资源：

<RCC>
    <qresource prefix="/fonts">
        <file>DejaVuSansMono.ttf</file>
    </qresource>
</RCC>

2. 在代码中加载资源内的字体：

void BrailleCanvas::updateGrid(){
    // 先加载资源中的字体
    int fontId = QFontDatabase::addApplicationFont(":/fonts/DejaVuSansMono.ttf");
    if (fontId != -1) {
        QStringList fontFamilies = QFontDatabase::applicationFontFamilies(fontId);
        if (!fontFamilies.isEmpty()) {
            brailleFont = QFont(fontFamilies.first(), fontSize);
        }
    } else {
        // 加载失败时的 fallback 逻辑
        brailleFont = QFont("DejaVu Sans Mono", fontSize);
    }
    QFontMetrics fm(brailleFont);
    tileWidth = fm.horizontalAdvance("⣿");
}

3. 配置nvim-dap传递正确环境 #

在nvim的dap配置文件（如.config/nvim/launch.json）中添加环境变量：

{
  "configurations": [
    {
      "name": "启动braille-drawer",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/braille-drawer",
      "args": [],
      "cwd": "${workspaceFolder}",
      "environment": [
        {"name": "QT_QPA_FONTDIR", "value": "/usr/share/fonts/truetype/dejavu/"},
        {"name": "XDG_DATA_DIRS", "value": "/usr/share:/usr/local/share"}
      ],
      "MIMode": "gdb"
    }
  ]
}

内容的提问来源于stack exchange，提问作者Leo Boeri