常见问题
使用 Jundot Engine 过程中可能遇到的问题及解决方案
安装问题
无法启动，缺少 DLL
症状：Windows 下启动时提示缺少 DLL 文件
原因：缺少 Visual C++ 运行库
解决：
- 下载 VC_redist.x64.exe
- 安装后重启 Jundot
macOS 提示「无法打开，无法验证开发者」
解决：
- 方法一：右键点击 Jundot → 打开 → 点击「打开」
- 方法二：系统设置 → 隐私与安全性 → 点击「仍要打开」
- 方法三（命令行）：
sudo xattr -rd com.apple.quarantine /Applications/Jundot.app
Linux 下无法启动
检查依赖：
# Ubuntu/Debian
sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libglu1-mesa libx11-xcb1
# Fedora
sudo dnf install webkit2gtk4.1 gtk3 mesa-libGLU libX11-xcb
# Arch Linux
sudo pacman -S webkit2gtk-4.1 glu libx11权限问题：
chmod +x Jundot.AppImage
# 或
chmod +x Jundot运行问题
编辑器卡顿/响应慢
可能原因及解决：
- 项目太大 → 关闭不需要的场景和文件
- 插件太多 → 在项目设置中禁用不必要的插件
- AI 助手持续运行 → 关闭不需要的 AI 对话
- 硬件加速问题 → 尝试用命令行启动：
Jundot --disable-gpu
项目运行报错
排查步骤：
- 查看底部输出面板的错误信息
- 检查脚本是否有语法错误
- 确认所有引用的资源文件存在
- 使用 AI 助手分析错误（选中错误文本 → 右键 → AI 修复）
场景显示异常/元素消失
常见原因：
- 节点被隐藏（检查
visible属性） - 位置不在视口内（按 F 键聚焦）
- 层级问题（检查 Z index / Layer）
- 纹理丢失（检查资源路径）
脚本问题
GDScript 语法错误
常见错误：
| 错误 | 原因 | 解决 |
|---|---|---|
| Indentation error | 缩进不正确 | GDScript 用缩进而非大括号，确保空格统一 |
| Expected colon | 缺少冒号 | if/for/while/func 后需要加冒号 |
| Identifier not found | 变量未定义 | 检查拼写，或先用 var 声明 |
| Nonexistent function | 函数不存在 | 检查函数名拼写和节点类型 |
C# 脚本编译失败
解决：
- 确认安装了 .NET SDK
- 菜单：项目 → 工具 → C# → 创建 C# 解决方案
- 清理并重新生成：
dotnet clean && dotnet build - 检查 .csproj 文件是否正确
信号连接不工作
检查清单：
- 信号名称是否正确（大小写敏感）
- 接收节点的函数是否存在
- 函数参数数量是否匹配
- 是否在正确的时机连接（节点已加入场景树后）
AI 助手相关
AI 助手无法连接
排查：
- 检查网络连接
- 确认 API Key 正确（编辑 → 编辑器设置 → AI）
- 测试 API Key 是否有效
- 如果是公司网络，检查是否需要代理
AI 生成的代码有问题
这是正常现象，建议：
- 让 AI 解释它生成的代码
- 逐步测试，不要一次让 AI 做太复杂的功能
- 提供更详细的需求描述
- 把错误信息反馈给 AI，让它修复
💡 提示
AI 生成的代码一定要自己验证。使用版本控制（Git），在 AI 修改前提交代码，方便回滚。
MCP 服务启动失败
常见原因：
- 命令路径错误（需要完整路径）
- 缺少依赖（如 Node.js、Python）
- 环境变量未设置
- 权限不足
调试方法：
- 在终端中手动运行命令，看是否有报错
- 检查 MCP 服务的日志
- 确认使用的是最新版本的 MCP 服务包
性能问题
游戏帧率低
分析步骤：
- 按
F3打开调试监视器 - 看是 CPU 瓶颈还是 GPU 瓶颈
- 使用性能分析器（Debug → Show Profiler）
- 定位问题后让 AI 优化
内存占用高
常见原因：
- 纹理太大 → 使用压缩纹理、降低分辨率
- 节点太多 → 使用对象池
- 内存泄漏 → 检查是否忘记
QueueFree() - 资源未释放 → 调用
ResourceLoader.Load的资源要手动释放
更新问题
检查更新失败
解决：
- 检查网络连接
- 确认 GitHub 是否可访问
- 可以手动下载更新包安装
更新后启动不了
解决：
- 尝试回滚到上一个版本（版本管理 → 回滚）
- 如果连版本管理都打不开，手动删除安装目录重新安装
- 项目文件不会丢失（它们在项目目录，不在安装目录）
数据安全
项目文件会丢吗？
不会。Jundot 引擎和项目文件是分开的：
- 引擎安装在应用程序目录
- 项目文件在你选择的保存位置
- 卸载/重装引擎不影响项目
怎么备份项目？
强烈建议使用版本控制：
# 使用 Git
cd 你的项目目录
git init
git add .
git commit -m "初始提交"或者直接复制整个项目文件夹作为备份。
获取更多帮助
如果以上方法都不能解决问题：
- 在编辑器内 — 直接问 AI 助手（
Ctrl+Shift+A） - GitHub Issues — 提交 Bug 报告
- 社区论坛 — 和其他开发者交流
- 联系页面 — 通过 联系我们 提交问题