Python+PySide2+QML项目Ubuntu运行报错，Windows无异常

一、ReferenceError: model is not defined 等数据上下文类错误 #

原因 #

Windows与Linux下PySide2的QML上下文初始化顺序、Python对象暴露机制存在细微差异：

• 可能是Python侧向QML注册模型/对象的时机晚于QML组件加载，Windows下因IO或线程调度差异刚好避开，但Linux下QML解析更快，导致组件初始化时找不到绑定的model。
• 跨平台下Python对象的属性暴露规则有差异，比如Windows下允许隐式暴露某些动态属性，Linux下要求显式注册。

修复方案 #

1. 调整初始化顺序：确保所有需要暴露给QML的模型、对象在加载QML文件之前完成注册和数据填充。示例：

# 先初始化并填充model
model = MyCustomModel()
model.load_data()

# 再将model暴露给QML上下文
engine = QQmlApplicationEngine()
context = engine.rootContext()
context.setContextProperty("model", model)

# 最后加载QML文件
engine.load(QUrl.fromLocalFile("main.qml"))

2. 显式声明Python对象属性：对需要在QML中访问的Python类属性，用PySide2.QtCore.Property装饰器显式定义，避免隐式属性跨平台兼容问题。

二、Context2D: The font families specified are invalid: Arial 字体错误 #

原因 #

Ubuntu默认没有Arial字体（微软专有字体），QML中指定的字体在Linux下找不到，导致渲染异常。

修复方案 #

1. 安装Arial字体：执行以下命令安装微软核心字体包：

sudo apt update && sudo apt install ttf-mscorefonts-installer

安装完成后执行fc-cache -fv刷新字体缓存。
2. 替换为跨平台兼容字体：修改QML中的字体设置，优先使用Linux原生支持的字体，比如：

Text {
    font.family: "Arial, Ubuntu, sans-serif" // 优先Arial，找不到则用Ubuntu或系统默认无衬线字体
}

三、QSSG.trace_info: OpenGL extensions: 日志信息 #

说明 #

这不是错误，是Qt的QML Scene Graph（QSSG）输出的OpenGL扩展信息，属于调试级日志。如果觉得日志冗余，可以通过设置Qt日志级别屏蔽：

import os
os.environ["QT_LOGGING_RULES"] = "qt.scenegraph.info=false"

四、潜在的依赖缺失问题 #

原因 #

虽然已经解决了xcb插件问题，但Ubuntu下PySide2运行还依赖一些系统级Qt库组件，virtualenv中的PySide2可能无法完全覆盖。

补充检查 #

1. 安装Qt相关系统依赖：

sudo apt install libqt5qml5 libqt5quick5 libqt5quickcontrols2-5 qml-module-qtquick-controls2 qml-module-qtquick-layouts

2. 验证PySide2版本一致性：确保Windows和Ubuntu下安装的PySide2版本完全相同（比如都用PySide2==5.15.2），不同版本的跨平台兼容性差异较大。

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