阅读须知我的所有文章免费。若在阅读时遇到VIP限制无法显示可私信联系我在使用 Kivy 开发时代码逻辑完全正确但中文显示为「□□□」方块是新手最常遇到的“劝退”问题。其根本原因在于Kivy 默认内置的 Roboto 字体仅包含拉丁字符集当渲染引擎尝试绘制中文字符时因找不到对应字形而回退为空白占位符。解决思路非常统一显式指定一个包含中文字形的字体文件。本文优化了三种主流方案的实现细节修复了原稿中的路径兼容性与全局配置误区并补充了跨平台打包的关键注意事项。⚠️核心避坑前置提醒禁止硬编码 Windows 绝对路径用于移动端C:/Windows/Fonts/在安卓/iOS 上不存在直接打包必崩路径分隔符统一使用/Python 字符串中\是转义符Windows 路径必须写作C:/Windows/Fonts/msyh.ttc或使用原始字符串rC:\Windows\Fonts\msyh.ttcTTC 与 TTF 的区别.ttc是字体集合文件含多个字重Kivy 支持但部分旧版本可能解析异常跨平台推荐优先使用.ttf单字体文件Config.set 必须在所有 Kivy 模块导入之前执行否则全局默认字体设置无效。 方案一调用系统字体仅限本地开发调试适用场景Windows/macOS/Linux 本机运行验证快速测试中文渲染效果。局限性不可用于打包分发目标设备字体路径不一致会导致崩溃。from kivy.app import App from kivy.uix.label import Label from kivy.core.text import LabelBase import platform # 根据操作系统动态获取系统中文字体路径避免跨系统报错 system platform.system() if system Windows: font_path C:/Windows/Fonts/msyh.ttc elif system Darwin: # macOS font_path /System/Library/Fonts/PingFang.ttc else: # Linux font_path /usr/share/fonts/truetype/wqy/wqy-microhei.ttc LabelBase.register(nameSysChinese, fn_regularfont_path) class MyApp(App): def build(self): return Label( text本机调试中文显示正常, font_nameSysChinese, font_size24 ) if __name__ __main__: MyApp().run()提示此方案仅作为开发阶段的临时手段任何需要分发的应用都应使用方案二。 方案二嵌入项目字体跨平台打包唯一推荐适用场景EXE、APK、IPA 打包分发确保所有设备中文显示一致。核心原则字体文件随项目一起打包使用相对路径加载。1. 项目结构规范MyKivyApp/ ├── main.py ├── assets/ │ └── SimHei.ttf # 将字体放入项目资源目录 └── buildozer.spec # 安卓打包配置2. 代码实现使用相对路径import os from kivy.app import App from kivy.uix.label import Label from kivy.core.text import LabelBase # 基于当前脚本位置动态拼接字体路径兼容任意运行环境 BASE_DIR os.path.dirname(os.path.abspath(__file__)) font_path os.path.join(BASE_DIR, assets, SimHei.ttf) LabelBase.register(nameAppChinese, fn_regularfont_path) class MyApp(App): def build(self): return Label( text跨平台中文显示正常, font_nameAppChinese, font_size24 ) if __name__ __main__: MyApp().run()3. Buildozer 打包关键配置在buildozer.spec的[app]节点下必须将字体扩展名加入打包白名单# 原始配置通常不包含 ttf/ttc需手动补充 source.include_exts py,png,jpg,kv,atlas,ttf,ttc,json # 同时确认 assets 目录被包含 source.include_patterns assets/*⚠️字体版权警告微软雅黑msyh.ttc、SimHei 等系统字体仅限本机使用嵌入 APK/IPA 分发存在法律风险。推荐使用开源免费商用字体思源黑体Source Han Sans、文泉驿微米黑、阿里巴巴普惠体。⚙️ 方案三全局默认中文字体复杂项目必备适用场景多页面、多控件项目避免逐个设置font_name。关键修正Config.set()必须在from kivy.app import App之前执行否则配置不生效。# ✅ 第一步在所有 Kivy 模块导入之前设置全局默认字体 from kivy.config import Config Config.set(kivy, default_font, AppChinese) Config.write() # ✅ 第二步再导入其他 Kivy 模块并注册字体 import os from kivy.app import App from kivy.uix.label import Label from kivy.uix.button import Button from kivy.core.text import LabelBase BASE_DIR os.path.dirname(os.path.abspath(__file__)) font_path os.path.join(BASE_DIR, assets, SimHei.ttf) LabelBase.register(nameAppChinese, fn_regularfont_path) class MyApp(App): def build(self): # 无需指定 font_name自动继承全局默认中文字体 return Label(text全局默认中文无需逐个设置, font_size24) if __name__ __main__: MyApp().run()注意Config.write()会将配置写入用户目录下的~/.kivy/config.ini属于持久化设置。若仅需运行时生效可省略Config.write()避免污染开发环境全局配置。 实战修复后的猜数字小游戏跨平台安全版以下代码已移除硬编码路径采用方案二方案三组合可直接打包为 APK/EXE# 全局配置必须在最顶部 from kivy.config import Config Config.set(kivy, default_font, GameFont) import os, random from kivy.app import App from kivy.uix.boxlayout import BoxLayout from kivy.uix.label import Label from kivy.uix.textinput import TextInput from kivy.uix.button import Button from kivy.core.text import LabelBase # 动态路径兼容 PC 与手机 BASE_DIR os.path.dirname(os.path.abspath(__file__)) font_path os.path.join(BASE_DIR, assets, SourceHanSansCN-Regular.ttf) LabelBase.register(nameGameFont, fn_regularfont_path) class GuessNumberGame(App): def build(self): self.target random.randint(1, 100) self.count 0 layout BoxLayout(orientationvertical, padding30, spacing20) self.title_lbl Label(text 猜数字小游戏, font_size26, boldTrue) self.hint_lbl Label(text请输入 1-100 的数字开始猜测, font_size18, color(0.2, 0.6, 0.8, 1)) self.input TextInput(hint_text输入数字, font_size18, input_typenumber, multilineFalse) guess_btn Button(text提交猜测, font_size18, background_color(0.3, 0.7, 0.3, 1)) guess_btn.bind(on_pressself.check_guess) reset_btn Button(text重新开始, font_size18, background_color(0.8, 0.4, 0.4, 1)) reset_btn.bind(on_pressself.reset_game) for w in [self.title_lbl, self.hint_lbl, self.input, guess_btn, reset_btn]: layout.add_widget(w) return layout def check_guess(self, _): try: val int(self.input.text.strip()) self.count 1 if not (1 val 100): self.hint_lbl.text f⚠️ 请输入 1-100已猜 {self.count} 次 elif val self.target: self.hint_lbl.text f 太小了再大一点 已猜 {self.count} 次 elif val self.target: self.hint_lbl.text f 太大了再小一点 已猜 {self.count} 次 else: self.hint_lbl.text f 恭喜猜中共 {self.count} 次点重新开始继续 except ValueError: self.hint_lbl.text ❌ 请输入有效数字 finally: self.input.text def reset_game(self, _): self.target random.randint(1, 100) self.count 0 self.hint_lbl.text 游戏已重置请输入 1-100 开始猜测 self.input.text if __name__ __main__: GuessNumberGame().run()