Qt 應用從 Ubuntu 桌面移植到 ARM 開發板時，常因缺少中文字體與編碼設定導致顯示方塊/亂碼。解決核心在於兩點：部署中文字體檔、設定 UTF-8 編碼與字體回退。本文提供完整操作流程與 main.cpp 範例碼。

一、 字體檔部署

1. 來源：Ubuntu 系統字體目錄 /usr/share/fonts/truetype/wqy/（文泉驛微米黑/正黑）。
2. 目標：開發板 Qt 字體目錄（如 /opt/qt-4.8.4/lib/fonts/）。
3. 複製：

   scp -r /usr/share/fonts/truetype/wqy root@devboard:/opt/qt-4.8.4/lib/fonts/
       

4. 環境變數指定字體路徑（啟動腳本/.profile/系統服務）：

   export QT_QWS_FONTDIR=/opt/qt-4.8.4/lib/fonts
       

二、 程式碼層面配置

#include "widget.h"
#include 
#include 
#include 

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);

    // 1. 設定 UTF-8 編碼 (Qt 4 必須，Qt 5 預設 UTF-8 可省略)
    QTextCodec *codec = QTextCodec::codecForName("UTF-8");
    QTextCodec::setCodecForLocale(codec);
    QTextCodec::setCodecForCStrings(codec);
    QTextCodec::setCodecForTr(codec);

    // 2. 設定全域預設字體（支援中文回退）
    QFont font;
    font.setFamily("WenQuanYi Micro Hei");  // 或 "WenQuanYi Zen Hei"
    font.setPointSize(10);
    a.setFont(font);

    Widget w;
    w.setWindowFlags(Qt::FramelessWindowHint);  // 嵌入式常用無框
    w.show();

    return a.exec();
}

三、 介面中使用 tr() 包裹中文字串

ui->stateLabel->setText(tr("攝像頭已經運行！"));

tr() 配合 QTextCodec::setCodecForTr 確保原始碼中文正確解碼。

四、 進階：字體回退機制與免安裝方案

• Qt 4.8+ 支援 QFont::insertSubstitution、QFont::insertSubstitutions 設定字體替代表。
• 若開發板儲存空間極小，可將字體檔編譯進 Qt 資源系統 .qrc，運行時以 QFontDatabase::addApplicationFont(":/fonts/wqy-microhei.ttc") 動態載入，無需檔案系統路徑。
• Qt 5.7+ 建議使用 QFontDatabase::addApplicationFont 載入 TTF/TTC，配合 QGuiApplication::setFont。

五、 常見問題排查

現象	可能原因	解決
顯示方框 □	字體檔未部署/路徑錯誤	確認 QT_QWS_FONTDIR、ls 目標目錄、fc-list | grep -i wen
顯示亂碼	編碼設定缺失/不一致	檢查原始碼儲存編碼、設定 UTF-8 codec、使用 tr()
字體極小/極大	DPI 計算錯誤	設定 QT_QWS_DPI 或 font.setPixelSize
部分字缺筆畫	字體檔不完整/版本舊	換用完整版文泉驛或思源黑體