企业官网建设流程全解析

Buildroot 开发板安装字体并统一 Qt 显示效果教程

1. 问题背景

在 OK3506 Buildroot 开发板上运行 Qt 程序时，虽然已经通过下面方式解决了横屏显示问题：

exportQT_QPA_FB_DRM=1exportQT_QPA_PLATFORM=linuxfb:rotation=90./New_Jydl

但是仍然可能出现一个新问题：

开发板 Qt 程序的显示效果和 Ubuntu 虚拟机 Qt 程序显示效果不一致。

常见表现包括：

字体大小不一致 字体粗细不一致 中文显示效果不一致 按钮中文字位置不一致 表格行高不一致 界面控件间距不一致

造成这个问题的重要原因之一就是：

Ubuntu 虚拟机和 Buildroot 开发板使用的字体不一致。

因此，需要把 Ubuntu 上用于 Qt 程序显示的字体复制到 Buildroot 开发板，并让 Qt 程序使用同一套字体。

2. 当前开发板字体包

开发板/root目录下已有两个字体相关压缩包：

program_fonts.tar.gz program_fonts_2.tar.gz

查看文件：

ls

可以看到类似：

FaultReport New_Jydl lib lib_json.tgz libhiredis.a libhiredis.so libhiredis.so.1.3.0 program_fonts.tar.gz program_fonts_2.tar.gz start.sh ui_source

3. 查看字体包内容

3.1 查看program_fonts.tar.gz

执行：

tar-tzfprogram_fonts.tar.gz

输出：

ui_source/program_fonts/ ui_source/program_fonts/NotoMono-Regular.ttf ui_source/program_fonts/Ubuntu-M.ttf ui_source/program_fonts/Ubuntu-C.ttf ui_source/program_fonts/Ubuntu-R.ttf ui_source/program_fonts/NotoSansCJK-Bold.ttc ui_source/program_fonts/DejaVuSans-Bold.ttf ui_source/program_fonts/NotoSansCJK-Regular.ttc ui_source/program_fonts/FreeSerif.ttf ui_source/program_fonts/FONT_MANIFEST.txt ui_source/program_fonts/ukai.ttc ui_source/program_fonts/wqy-zenhei.ttc ui_source/program_fonts/DejaVuSans.ttf

说明这个包里主要是字体文件，包括：

NotoSansCJK-Regular.ttc NotoSansCJK-Bold.ttc Ubuntu-R.ttf Ubuntu-M.ttf Ubuntu-C.ttf DejaVuSans.ttf DejaVuSans-Bold.ttf wqy-zenhei.ttc ukai.ttc

这些字体里，比较推荐 Qt 中文界面使用：

NotoSansCJK-Regular.ttc NotoSansCJK-Bold.ttc

3.2 查看program_fonts_2.tar.gz

执行：

tar-tzfprogram_fonts_2.tar.gz

输出：

69-jypmc11-cn-font-alias.conf

说明这个包里是 fontconfig 字体别名配置文件。

它的作用一般是给中文字体设置别名，让系统或 Qt 更容易匹配到合适的中文字体。

4. BusyBox tar 注意事项

在 Buildroot 开发板上，tar通常是 BusyBox 版本。

执行错误命令：

tar-rzfprogram_fonts.tar.gz-C/home/forlinx/.config/fontconfig/conf.d69-jypmc11-cn-font-alias.conf

可能会报错：

tar: invalid option -- 'r' BusyBox v1.36.1 ...

原因是：

1. BusyBox tar 不支持 -r 追加参数 2. .tar.gz 是 gzip 压缩包，本来也不适合直接追加文件

所以在开发板上不要使用：

tar-rzfxxx.tar.gz...

正确思路是：

解压压缩包 复制字体文件到 /usr/share/fonts/ 复制 .conf 配置文件到 /etc/fonts/conf.d/

5. 推荐安装目录

建议把项目字体单独放到：

/usr/share/fonts/jypmc11

fontconfig 配置文件放到：

/etc/fonts/conf.d

这样目录清晰，方便后续维护。

6. 一键安装字体命令

在开发板上执行下面命令：

rm-rf/tmp/program_fontsmkdir-p/tmp/program_fontstar-xzf/root/program_fonts.tar.gz-C/tmp/program_fontstar-xzf/root/program_fonts_2.tar.gz-C/tmp/program_fontsmkdir-p/usr/share/fonts/jypmc11mkdir-p/etc/fonts/conf.dfind/tmp/program_fonts-typef|grep-E'\.ttf$|\.ttc$|\.otf$'|whilereadfdocp"$f"/usr/share/fonts/jypmc11/donefind/tmp/program_fonts-typef|grep'\.conf$'|whilereadfdocp"$f"/etc/fonts/conf.d/donesync

这组命令完成的事情是：

1. 创建临时目录 /tmp/program_fonts 2. 解压两个字体包 3. 创建开发板字体目录 /usr/share/fonts/jypmc11 4. 创建 fontconfig 配置目录 /etc/fonts/conf.d 5. 复制 .ttf / .ttc / .otf 字体文件 6. 复制 .conf 字体配置文件 7. sync 保存到存储设备

7. 检查字体是否安装成功

执行：

ls-l/usr/share/fonts/jypmc11

应该能看到类似：

DejaVuSans-Bold.ttf DejaVuSans.ttf FreeSerif.ttf NotoMono-Regular.ttf NotoSansCJK-Bold.ttc NotoSansCJK-Regular.ttc Ubuntu-C.ttf Ubuntu-M.ttf Ubuntu-R.ttf ukai.ttc wqy-zenhei.ttc

检查 fontconfig 配置：

ls-l/etc/fonts/conf.d/|grepjypmc

应该看到：

69-jypmc11-cn-font-alias.conf

8. 刷新字体缓存

如果开发板系统带有fontconfig，可以执行：

whichfc-cachewhichfc-match

如果能找到命令，例如：

/usr/bin/fc-cache /usr/bin/fc-match

则刷新字体缓存：

fc-cache-fv

测试字体匹配：

fc-match fc-match"Noto Sans CJK SC"fc-match"Ubuntu"fc-match"WenQuanYi Zen Hei"

如果开发板没有fc-cache和fc-match，也不是致命问题。

因为 Qt 的嵌入式平台插件仍然可以通过下面环境变量查找字体：

exportQT_QPA_FONTDIR=/usr/share/fonts

9. Qt 启动脚本中指定字体目录

开发板启动 Qt 程序时，建议加入字体相关环境变量：

exportQT_QPA_FONTDIR=/usr/share/fontsexportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1

完整启动示例：

unsetQT_DEBUG_PLUGINSunsetQT_QPA_EGLFS_ROTATIONunsetQT_QPA_EGLFS_INTEGRATIONexportQT_QPA_FB_DRM=1exportQT_QPA_PLATFORM=linuxfb:rotation=90exportQT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt/pluginsexportQT_QPA_FONTDIR=/usr/share/fontsexportQT_IM_MODULE=qtvirtualkeyboardexportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1cd/root ./New_Jydl

关键环境变量说明：

10. 开机自启脚本示例

可以修改或创建：

vi/etc/init.d/S99New_Jydl

写入：

#!/bin/shcase"$1"instart)echo"Starting New_Jydl..."unsetQT_DEBUG_PLUGINSunsetQT_QPA_EGLFS_ROTATIONunsetQT_QPA_EGLFS_INTEGRATIONexportQT_QPA_FB_DRM=1exportQT_QPA_PLATFORM=linuxfb:rotation=90exportQT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt/pluginsexportQT_QPA_FONTDIR=/usr/share/fontsexportQT_IM_MODULE=qtvirtualkeyboardexportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1cd/root ./New_Jydl&;;stop)echo"Stopping New_Jydl..."killallNew_Jydl;;restart)$0stopsleep1$0start;;*)echo"Usage:$0{start|stop|restart}"exit1;;esacexit0

添加执行权限：

chmod+x /etc/init.d/S99New_Jydlsyncreboot

11. Qt 代码中固定字体

只把字体复制到开发板还不够，因为 Qt 可能仍然使用默认字体。

建议在main.cpp中强制指定字体、样式和 DPI。

参考代码：

#include<QApplication>#include<QStyleFactory>#include<QFont>#include"mainwindow.h"intmain(intargc,char*argv[]){/* * 注意： * 这两个属性必须在 QApplication 创建之前设置。 */QApplication::setAttribute(Qt::AA_DisableHighDpiScaling);QApplication::setAttribute(Qt::AA_Use96Dpi);QApplicationapp(argc,argv);/* * 统一 Qt 控件样式，减少 Ubuntu 和开发板显示差异。 */app.setStyle(QStyleFactory::create("Fusion"));/* * 统一中文字体。 * 推荐使用 Noto Sans CJK SC。 */QFontfont("Noto Sans CJK SC");font.setPixelSize(18);app.setFont(font);MainWindow w;w.resize(1280,720);w.showFullScreen();returnapp.exec();}

如果想使用 Ubuntu 字体，也可以改成：

QFontfont("Ubuntu");font.setPixelSize(18);app.setFont(font);

但是中文界面更推荐：

QFontfont("Noto Sans CJK SC");

因为字体包里已经包含：

NotoSansCJK-Regular.ttc NotoSansCJK-Bold.ttc

12. 为什么建议使用 setPixelSize

Qt 字体有两种常见设置方式：

font.setPointSize(12);

和：

font.setPixelSize(18);

对于嵌入式 HMI 固定分辨率界面，建议优先使用：

font.setPixelSize(18);

原因是：

pointSize 会受 DPI 影响 pixelSize 更适合固定 1280x720 这类工业屏界面 pixelSize 在 Ubuntu 和开发板之间更容易保持一致

如果程序要适配多种分辨率，可以再设计一套统一缩放策略。

13. Ubuntu 端也要统一设置

Ubuntu 虚拟机运行 Qt 程序时，也建议指定：

exportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1./New_Jydl

如果 Ubuntu 使用 xcb，可以明确：

exportQT_QPA_PLATFORM=xcbexportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1./New_Jydl

这样可以避免 Ubuntu 桌面缩放影响 Qt 程序显示效果。

14. 常用排查命令

14.1 开发板查看 Qt 环境变量

env|grepQT

重点检查：

QT_QPA_FB_DRM QT_QPA_PLATFORM QT_QPA_FONTDIR QT_FONT_DPI QT_SCALE_FACTOR

14.2 查看 Qt 插件

find/usr/lib/qt/plugins-maxdepth3-typef

开发板当前主要平台插件：

libqlinuxfb.so libqminimal.so libqoffscreen.so libqvnc.so

14.3 查看字体文件

find/usr/share/fonts-typef

或者只看项目字体目录：

ls-l/usr/share/fonts/jypmc11

14.4 查看 fontconfig 配置

ls-l/etc/fonts/conf.d/

如果有fc-match：

fc-match"Noto Sans CJK SC"

14.5 打开 Qt 插件调试

临时调试：

exportQT_DEBUG_PLUGINS=1./New_Jydl2>&1|tee/tmp/qt_debug.log

看是否加载了：

/usr/lib/qt/plugins/platforms/libqlinuxfb.so

调试完建议关闭：

unsetQT_DEBUG_PLUGINS

15. 字体安装后的最终运行方式

推荐最终运行方式：

unsetQT_DEBUG_PLUGINSunsetQT_QPA_EGLFS_ROTATIONunsetQT_QPA_EGLFS_INTEGRATIONexportQT_QPA_FB_DRM=1exportQT_QPA_PLATFORM=linuxfb:rotation=90exportQT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt/pluginsexportQT_QPA_FONTDIR=/usr/share/fontsexportQT_IM_MODULE=qtvirtualkeyboardexportQT_FONT_DPI=96exportQT_SCALE_FACTOR=1cd/root ./New_Jydl

16. 总结

本次字体安装的核心流程是：

1. program_fonts.tar.gz 中保存字体文件 2. program_fonts_2.tar.gz 中保存 fontconfig 配置文件 3. 字体文件复制到 /usr/share/fonts/jypmc11 4. 配置文件复制到 /etc/fonts/conf.d 5. 如果有 fontconfig，执行 fc-cache -fv 6. Qt 启动时指定 QT_QPA_FONTDIR=/usr/share/fonts 7. Qt 启动时固定 QT_FONT_DPI=96 和 QT_SCALE_FACTOR=1 8. Qt 代码中固定 Fusion 样式和 Noto Sans CJK SC 字体

一句话总结：

要让 Ubuntu 虚拟机和 Buildroot 开发板上的 Qt 程序显示效果尽量一致，必须让两边使用同一套字体、同一个 DPI、同一个缩放比例和同一个 Qt 样式。

推荐最终组合：

字体：Noto Sans CJK SC 样式：Fusion 字号：setPixelSize DPI：96 缩放：1 开发板字体目录：/usr/share/fonts/jypmc11 Qt 字体搜索目录：QT_QPA_FONTDIR=/usr/share/fonts