故障排除

本页面提供常见问题的详细诊断步骤。如果你遇到的问题比较简单，建议先查看 常见问题。

无法连接 UE 编辑器

症状：NexusFlow 状态栏始终显示 🔴 红色未连接状态，即使 UE 编辑器已启动。

可能原因：

• NexusFlow 桌面应用与 UE 插件版本不匹配
• UE 项目中未启用 NexusFlow 插件
• 防火墙或安全软件阻止通信
• 另一个 NexusFlow 实例占用了通信管道

诊断步骤：

1. 检查版本匹配：确保 NexusFlow 桌面应用和 UE 插件都更新到最新版本，版本不匹配是最常见的连接失败原因
2. 检查插件状态：在 UE 中打开 编辑 > 插件管理器，搜索 "NexusFlow"，确认插件已启用
3. 排除防火墙干扰：暂时关闭防火墙或安全软件，测试连接
4. 检查多实例：确保只有一个 NexusFlow 在运行（查看任务管理器）
5. 查看日志：
   • NexusFlow 日志：%APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log
   • UE 日志：<项目目录>/Saved/Logs/ 目录下，搜索关键字 LogNexusFlow
6. 重启两端：关闭 UE 和 NexusFlow，然后重新启动（启动顺序不限）

快速检查

打开 NexusFlow 的 设置 > 关于 页面，查看「插件状态」部分是否检测到 UE 安装。

AI 无响应或报错

症状：发送消息后 AI 没有回复，或对话区域显示错误信息。

可能原因：

• AI 模型未配置或验证失败
• API Key 无效或余额不足
• 网络无法访问 AI 服务端点
• Custom Provider 配置错误

诊断步骤：

1. 检查模型配置：进入 设置 > AI 模型，确认已添加至少一个模型并设为默认
2. 测试模型连接：点击模型卡片上的「验证」按钮
3. 如果验证失败：
   • 检查 API Key 是否正确复制（注意首尾空格）
   • 检查服务商账户余额是否充足
   • 测试网络连通性：
     • OpenAI：能否访问 api.openai.com
     • Anthropic：能否访问 api.anthropic.com
     • DeepSeek：能否访问 api.deepseek.com
     • 智谱 GLM：能否访问 open.bigmodel.cn
     • MiniMax：能否访问 api.minimaxi.com
     • 通义千问：能否访问 dashscope.aliyuncs.com
     • Kimi：能否访问 api.moonshot.cn
4. 如果使用 Custom Provider：确认 API 地址和通讯协议选择正确
5. 查看日志：打开 %APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log，搜索 error 或 failed

Anthropic 用户注意

Anthropic (Claude) 模型必须设置 Max Tokens，否则 API 调用会失败。进入模型配置检查此项。

侧边栏对话功能长时间不可用

症状：打开侧边栏后，对话输入框长时间处于不可用状态或加载中。

可能原因：

• AI 服务内部初始化延迟
• 端口被其他 NexusFlow 实例或程序占用

诊断步骤：

1. 等待初始化：首次打开时，AI 服务需要约 10 秒完成初始化，期间会自动重试
2. 检查多实例：在任务管理器中搜索 "NexusFlow"，关闭多余的实例
3. 检查端口冲突：是否有其他程序占用了随机端口
4. 重启应用：完全关闭 NexusFlow 后重新启动

蓝图操作后出现异常

症状：AI 操作蓝图后，蓝图出现编译错误、连线断开或行为异常。

可能原因：

• AI 生成的操作不一定总是完美的
• 可能产生无效连线或缺少必要节点
• 复杂蓝图的操作可能不够精确

诊断步骤：

1. 立即撤销：在 UE 中按 Ctrl+Z 撤销最近的操作
2. 检查错误信息：查看蓝图编译器给出的具体错误提示
3. 多次撤销：如果一次撤销不够，多按几次 Ctrl+Z 回退更多步骤
4. 版本控制恢复：如果撤销无效，从 Git 或其他版本控制系统恢复文件

重要提醒

在让 AI 执行重要的蓝图修改前，建议先保存蓝图（Ctrl+S）。这样即使出现问题，也可以通过撤销回到保存点。

预防措施：

• 对重要蓝图操作前先保存
• 使用版本控制系统（如 Git）管理蓝图文件
• 分步操作，避免一次性执行过多修改
• 在对话中描述需求时尽量具体

全局快捷键不工作

症状：设置了全局快捷键（如切换侧边栏）但按下后没有反应。

可能原因：

• 快捷键与其他应用冲突
• 快捷键注册到操作系统失败
• 修改后未重启应用

诊断步骤：

1. 检查冲突：确认没有其他应用（如截图工具、输入法等）占用相同的快捷键
2. 更换组合键：进入 设置 > 快捷键，尝试换一个不常用的组合
3. 恢复默认：点击「恢复默认」按钮重置所有快捷键
4. 重启应用：修改快捷键后重启 NexusFlow 使其生效

日志文件位置

排查问题时，日志文件是最重要的诊断信息来源。

NexusFlow 日志

日志	路径
主程序日志	%APPDATA%/cn.nexusflow.desktop/logs/tauri_debug.log

打开 AppData 目录

在 Windows 文件资源管理器的地址栏输入 %APPDATA%/cn.nexusflow.desktop/ 按回车即可快速打开。

UE 插件日志

日志	路径
UE 编辑器日志	<UE 项目目录>/Saved/Logs/*.log
Bridge 调试日志（Debug 构建）	<UE 项目目录>/Saved/Logs/nexusflow_bridge_debug.log

• 在 UE 日志中搜索关键字 LogNexusFlow 可以过滤出 NexusFlow 插件相关的日志
• Bridge 调试日志仅在 Debug 构建中生成；Release 构建的 Bridge 日志合并在 UE 标准日志中，搜索 [Bridge] 关键字

UE 中弹出 NexusFlow Setup 对话框

现象：每次启动 UE 编辑器时，都会弹出 "NexusFlow Setup" 对话框。

说明：当 NexusFlow 插件检测到桌面应用未安装或 Embedding 模型未就绪时，会弹出此对话框。这是首次运行帮助，不是报错。

处理方式：

你想…	操作
现在配置	点击 Download Model 或 Open Settings，按提示操作
稍后配置	点击 Later，下次启动仍会提示
永不再显示	点击 Don't Show Again，对话框将不再出现

关闭后想重新启用：

1. 打开 %LOCALAPPDATA%/NexusFlow/config.json
2. 将 "showSetupWizard" 改为 true
3. 重启 UE 编辑器

仍然无法解决？

如果以上步骤都没有解决你的问题：

1. 收集相关日志文件（NexusFlow 日志 + UE 日志）
2. 记录问题的复现步骤
3. 在 GitHub Issues 提交问题，附上以上信息