常见问题 (FAQ)¶
本文整理 EmbeddedGUI 开发中最常见的环境、构建和运行问题。
环境搭建¶
Q: setup.bat / setup.sh 执行失败，提示找不到 Python¶
问题描述： 脚本启动后立即失败，提示未找到 Python。
解决方案：
安装 Python 3.8+
Windows 确保
py或python可执行Linux / macOS 确保
python3或python可执行重新运行脚本
Q: Python 依赖安装失败¶
问题描述： setup_env.py 在安装 requirements.txt 时失败。
原因分析：
网络不稳定
镜像源不可用
某些包需要手动重试
解决方案：
直接按脚本打印出的手动命令执行
先升级
pip必要时分步安装
示例：
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Q: 还想使用 UI Designer 桌面端，当前仓库为什么没有启动入口¶
说明： UI Designer 桌面端和设计稿转换链路已经迁移到 EmbeddedGUI_Designer 仓库，当前仓库不再提供 scripts/ui_designer/main.py 或桌面端依赖安装。
处理方式：
继续在当前仓库开发 SDK、运行时、示例和资源
需要 Designer 桌面端时，切换到
EmbeddedGUI_Designer入口见
doc/source/ui_designer/index.rst
Q: Windows 下自动下载 w64devkit 失败¶
问题描述： 脚本提示下载 w64devkit 失败，可能是网络或 SSL 错误。
解决方案：
手动下载
w64devkit解压到项目根目录下的
tools/w64devkit/重新运行
setup.bat
下载地址：
https://github.com/skeeto/w64devkit/releases
Q: ffmpeg 未找到，或者自动下载失败¶
问题描述： 运行 setup.bat / setup.sh 时，脚本提示 ffmpeg 不存在，或者 Windows 下自动下载失败。
解决方案：
Windows 重新运行
setup.bat，脚本会优先尝试自动安装到tools/ffmpeg/如果自动下载失败，手动下载并解压，使下面这个文件存在：
tools/ffmpeg/bin/ffmpeg.exeLinux / macOS 通过系统包管理器安装
ffmpeg如果当前不需要 MP4 转序列帧或 GIF 录制流程，可使用
--skip-ffmpeg
常见安装命令：
sudo apt install ffmpeg
sudo dnf install ffmpeg
sudo pacman -S ffmpeg
brew install ffmpeg
构建问题¶
Q: 找不到 make 命令¶
问题描述： 执行 make all 时提示 make 不存在。
解决方案：
Windows 重新运行
setup.batLinux / macOS 安装系统编译工具链
确认
make --version能输出版本号
Q: 找不到 gcc¶
问题描述： 构建时报 gcc: No such file or directory。
解决方案：
Windows 重新运行
setup.bat，让脚本检查或安装w64devkitLinux / macOS 通过系统包管理器安装
gcc确认
gcc --version正常
Q: libwinpthread-1.dll 找不到¶
问题描述： 之前某些 Windows 环境会在构建或运行时提示 libwinpthread-1.dll 缺失。
说明：
当前构建系统已经调整为：
仅当该 DLL 实际存在时才复制
对项目内
w64devkit场景不再强制依赖这个文件
如果你仍然遇到这个问题：
先删除
output/下旧的 DLL 残留重新编译一次
若你使用自己的 MinGW 工具链，再检查对应运行时 DLL 是否在 PATH 中
Q: SDL2.h: No such file or directory¶
问题描述： 编译 PC 模拟器时找不到 SDL2 头文件。
解决方案：
Windows：确认仓库内
porting/pc/sdl2/目录完整Linux：安装
libsdl2-devmacOS：安装
sdl2
运行问题¶
Q: 程序编译成功，但窗口不显示¶
解决方案：
先执行
make run检查
app_egui_config.h中的屏幕尺寸是否合理检查
egui_polling_work(&core)是否在主循环中被调用用运行时检查脚本验证
python scripts/code_runtime_check.py --app HelloSimple --timeout 10
Q: 程序卡死或无响应¶
解决方案：
检查定时器回调里是否做了阻塞操作
检查是否存在死循环
先在 PC 模拟器下复现
再用调试器定位
资源问题¶
Q: 字体或图片显示不正确¶
解决方案：
重新生成资源
make resource_refresh APP=<APP>
检查资源配置文件
确认字体字符集是否覆盖所需文本
其他¶
Q: 想完全跳过 Python 安装，只检查工具链¶
可以执行：
python scripts/setup_env.py --python-mode none
或：
setup.bat --python-mode none
Q: 想只安装基础 Python 依赖¶
可以执行：
python scripts/setup_env.py --python-mode basic
或：
setup.bat --python-mode basic