故障排除
从下面对应的症状开始。进行任何手动存储更改前，请先保留项目文件。
Locus 缺失或无法加载
Section titled “Locus 缺失或无法加载”- 确认插件位于
<Project>/Plugins/Locus/，并已在 Edit > Plugins 中启用。 - 确认软件包与项目使用的 Unreal Engine 次版本完全匹配。
- 启用或替换插件后重新启动 Unreal Editor。
- 尝试 Window > Locus 或 Ctrl+Shift+L。
- 在 Unreal Output Log 中查看
LogLocus类别和插件加载错误。
如果二进制软件包针对其他 Engine 次版本，请替换为正确的软件包；不要在不同软件包之间复制单个二进制文件。
打开版本控制，检查文件是否受控、被其他用户或客户端签出、已过时，或因提供程序断开而不可用。干净的受控文件也会在明确签出前保持只读。
当其他客户端拥有文件、工作区落后于仓库，或提供程序无法报告安全状态时，签出可能不可用。使用项目的常规版本控制工作流解决所有权或修订版本状态。重新连接提供程序后，刷新 Unreal Source Control 或 Locus；签出成功前受控内容仍为只读。不要通过修改文件系统权限绕过保护。
私有笔记和标记点不应依赖提供程序。如果它们不可用，请确认项目 Saved/Locus 存储存在且可写。
在未配置提供程序的情况下，缺少源代码控制状态、工具提示、指导、签出 或 标记为添加 UI 是正常的本地模式。已配置但不可用的提供程序则不同，它会保护已知的受控内容。
签出或标记为添加失败
Section titled “签出或标记为添加失败”确认 Unreal 的提供程序已配置、连接并且可以报告文件。失败的创建后 标记为添加 请求会在磁盘上留下新的共享 笔记。新的共享 标记点 和 文档 保留为 Untracked，直到明确添加；共享 标记点 快照具有单独的源代码控制状态。
文档无法重命名或移动
Section titled “文档无法重命名或移动”请使用 Locus 文档工作区执行重命名和移动；内容浏览器项目只是投影，并不是权威的重命名界面。符合条件的未跟踪文档可以使用重命名或 F2，并使用移动或拖放到有效的现有文件夹中。由于无法安全执行与提供程序无关的版本控制移动，Locus 会有意阻止标记为添加和受控文档的重命名与移动。不要通过禁用版本控制或修改文件系统权限绕过限制，而应在标记为添加前整理文档。
笔记、标记点或文档不刷新
Section titled “笔记、标记点或文档不刷新”使用活动工作区的重建或刷新操作。对于在外部编辑器中更改的文档，请将有效的 UTF-8 .md 文件保存到 ProjectDocuments 下。对于标记点，请确认当前世界已保存，且标记点与解析出的地图关联。
有可用的恢复数据
Section titled “有可用的恢复数据”执行操作前，先检查磁盘上的主文件和恢复副本。恢复会用恢复内容替换主文件；恢复为新项目会同时保留两者；丢弃会删除恢复副本。不确定时，优先恢复为新项目。
外部冲突表示 Locus 保留未保存编辑时磁盘文件发生了变化。不要强制覆盖。使用提供的操作重新加载磁盘、将本地工作保存为新项目、复制本地文本，或在可用时比较版本。
数据格式错误或不受支持
Section titled “数据格式错误或不受支持”保留原始文件并检查 LogLocus 消息。除非有经过验证的备份并理解格式，否则不要手动编辑标识符或所有权字段。无效的 UTF-8 Markdown 文件会在导入时被拒绝。不受支持的 Markdown 即使无法在阅读模式中完整呈现，也应保留为源文本。
参考文献丢失或过时
Section titled “参考文献丢失或过时”Refresh the relevant workspace and verify that the Asset, 标记点, 笔记, 文档, or Actor still exists. A moved or deleted target may remain readable but unresolved so you can repair it deliberately.
Author an Actor reference only by dragging exactly one eligible loaded Actor from the World Outliner into an editable 笔记 or 文档. 插入引用和@中没有； Level Instances and unsupported transient or preview worlds are not supported.
标记点不可用
Section titled “标记点不可用”持久标记点需要保存的顶层 Editor 世界。保存地图，返回当前地图，然后重试放置。用于浏览所有地图时，标记点文件不会仅为此加载或修改地图。
快照捕获和更新还需要可用的透视 Level Editor 视口，并且在 PIE 期间不可用。
确认 .md 文件位于 <Project>/ProjectDocuments/ 下并使用有效的 UTF-8。保留的 Content/ 子树之外的路径会出现在Locus 文档下，不会投影到 Unreal 内容浏览器。ProjectDocuments/Content/ 下的路径会出现在稀疏的内容浏览器根下，并投影到对应的 /Game 上下文。外部更改后刷新文档。无关的 /Game 文件夹有意不显示，因为树来自已建立索引的文档，而不是 Asset Registry 文件夹。请记住，文档是外部投影项目，不是 UAsset。
Markdown 的呈现不符合预期
Section titled “Markdown 的呈现不符合预期”有关受支持构造，请查看文档。原始 HTML 和不安全 URL 保持不活动，远程内容不会获取，也不保证浏览器等效的 Markdown 呈现。切换到编辑模式，确认权威源文本保持完整。
MCP 客户端无法连接或被拒绝
Section titled “MCP 客户端无法连接或被拒绝”保持 Unreal Editor 打开，使用 Editor Preferences > Plugins > Locus > MCP Integration 确认 启用 MCP 已开启且状态为运行中。如果本地端点或客户端配置不可用，请在更改本地端口或重新生成凭据后复制新的配置。
复制前选择匹配的 客户端格式。Claude Code 和 Gemini CLI 注册命令应在普通终端中运行，而不是在交互式提示符中运行。Gemini 使用用户范围，因此较旧的全局 locus 条目可能仍指向其他项目的端点；请使用当前打开项目的新配置替换它。不要将复制的命令或凭据粘贴到支持请求中。
同一时间只能有一个客户端拥有活动 Locus 会话。关闭或断开之前的客户端，稍等片刻再重试；仅当该客户端不再使用时才使用重置活动客户端。更改内容需要允许更改，私有笔记或标记点还需要单独启用允许私有笔记和标记点。MCP 标记点工作仅限于受支持的已保存项目所有 /Game/... 世界基线。
有关完整的连接、权限、支持工具和标记点上下文指导，请参阅MCP 集成。
文档或反馈无法打开
Section titled “文档或反馈无法打开”外部链接使用操作系统的默认浏览器。检查是否配置了默认 HTTP/HTTPS 浏览器，以及操作系统是否允许启动 URL。失败不会更改项目数据。MCP 集成包含文档按钮，Locus 还提供提供反馈。