Ubuntu 20.04环境下Django后端执行music21代码时XDG_RUNTIME_DIR与propagateSizeHints()错误排查求助

看起来你遇到的核心问题是直接终端运行脚本时的环境和Django/gunicorn服务环境的差异，导致Qt和Musescore相关的环境变量、权限没有正确匹配。下面我会拆解原因并给出具体的修复步骤：

可能的根本原因 #

1. 环境变量不继承：你在终端手动运行脚本时，会话会自动设置XDG_RUNTIME_DIR等用户环境变量，同时QT_QPA_PLATFORM的设置也能被子进程（比如Musescore3）正确继承。但gunicorn作为系统服务运行时，是在一个极简的环境下启动的，默认不会携带这些用户会话级的环境变量——哪怕你在启动脚本里加了export，也可能因为服务启动的机制（比如systemd）没传递给子进程。
2. 权限与目录访问问题：XDG_RUNTIME_DIR默认指向的/tmp/runtime-myusername目录，可能只有你手动登录的用户有读写权限，而运行gunicorn的用户（比如www-data或者自定义用户）没有权限访问，导致Qt无法创建必要的临时文件。
3. Qt插件的环境依赖：虽然你设置了QT_QPA_PLATFORM=offscreen，但在服务环境下，Qt可能缺少加载offscreen插件的依赖，或者环境变量的设置方式不对（比如用os.putenv而不是os.environ，后者的修改更易被子进程继承）。

具体修复步骤 #

方案1：在gunicorn服务配置中显式设置环境变量（推荐） #

如果你的gunicorn是用systemd管理的（Ubuntu 20.04常见的方式），直接在service文件里设置环境变量是最可靠的：

1. 编辑你的gunicorn服务文件（通常路径是/etc/systemd/system/gunicorn.service），在[Service]段添加以下内容：

Environment="QT_QPA_PLATFORM=offscreen"
Environment="XDG_RUNTIME_DIR=/tmp/runtime-gunicorn"

2. 创建指定的运行目录并设置正确的权限（替换your_gunicorn_user为实际运行gunicorn的用户，比如www-data）：

mkdir -p /tmp/runtime-gunicorn
chown your_gunicorn_user:your_gunicorn_group /tmp/runtime-gunicorn
chmod 700 /tmp/runtime-gunicorn

3. 重新加载systemd配置并重启gunicorn：

sudo systemctl daemon-reload
sudo systemctl restart gunicorn

方案2：在Python代码中强制设置环境变量与目录 #

如果服务层的配置没生效，可以在代码里直接设置，确保环境变量被后续的Musescore调用继承：
修改你的脚本代码如下：

import music21
import os
import pathlib

# 用os.environ设置环境变量，比os.putenv更易被子进程继承
os.environ["QT_QPA_PLATFORM"] = "offscreen"
# 指定一个gunicorn用户可写的运行目录
runtime_dir = "/tmp/music21_runtime"
os.environ["XDG_RUNTIME_DIR"] = runtime_dir
# 确保目录存在并设置权限
pathlib.Path(runtime_dir).mkdir(exist_ok=True, mode=0o700)

us = music21.environment.UserSettings()
us['musescoreDirectPNGPath'] = '/usr/bin/musescore3'
score = music21.converter.parse("myfile.musicxml")
# 注意：确保生成pdf的路径（这里是song.pdf）所在目录对gunicorn用户可写
score.write('musicxml.pdf', fp='song.pdf')

方案3：检查Musescore3的依赖与权限 #

确保服务器上安装了Musescore3的所有Qt依赖，避免插件加载失败：

sudo apt-get install musescore3 libqt5gui5 libqt5core5a libqt5widgets5

同时，确认运行gunicorn的用户有以下权限：

• 执行/usr/bin/musescore3的权限
• 读写myfile.musicxml所在目录和生成song.pdf目录的权限

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