whale-town-front/docs/AI_docs/quick_reference/troubleshooting.md

🔧 故障排除指南

AI编程助手专用：常见问题的快速解决方案

🚨 常见错误及解决方案

1. UID无效警告

错误信息:

WARNING: scene/resources/resource_format_text.cpp:444 - res://path/to/file.tscn:X - ext_resource, invalid UID: uid://xxxxx - using text path instead: res://path/to/script.gd

原因: 文件移动后，Godot的UID缓存没有更新，导致UID引用失效。

解决方案:

# 方法1: 移除无效的UID，使用文本路径
# 将这行：
[ext_resource type="Script" uid="uid://invalid_uid" path="res://path/to/script.gd" id="1_script"]

# 改为：
[ext_resource type="Script" path="res://path/to/script.gd" id="1_script"]

预防措施:

• 移动文件时使用Godot编辑器的文件系统面板
• 避免直接在文件系统中移动.gd和.tscn文件
• 移动文件后重新导入项目

2. 脚本路径错误

错误信息:

ERROR: Failed to load script "res://old/path/Script.gd" with error "File not found".

解决方案:

# 检查并更新所有.tscn文件中的脚本路径
# 使用搜索替换功能批量更新：

# 旧路径 → 新路径
"res://UI/Windows/" → "res://scenes/ui/"
"res://Utils/" → "res://_Core/utils/"
"res://Scenes/Maps/" → "res://scenes/maps/"

3. AutoLoad路径错误

错误信息:

ERROR: Cannot load autoload: res://old/path/Manager.gd

解决方案:

# 在 project.godot 中更新 AutoLoad 路径
[autoload]
GameManager="*res://_Core/managers/GameManager.gd"
SceneManager="*res://_Core/managers/SceneManager.gd"
EventSystem="*res://_Core/systems/EventSystem.gd"

4. 资源加载失败

错误信息:

ERROR: Failed to load resource "res://old/path/resource.png".

解决方案:

# 检查资源路径是否正确
# 使用 ResourceLoader.exists() 验证路径
func load_resource_safely(path: String):
    if not ResourceLoader.exists(path):
        push_error("Resource not found: %s" % path)
        return null
    
    return load(path)

🔍 调试技巧

1. 路径验证

# 验证文件是否存在
func verify_file_exists(file_path: String) -> bool:
    return FileAccess.file_exists(file_path)

# 验证资源是否存在
func verify_resource_exists(resource_path: String) -> bool:
    return ResourceLoader.exists(resource_path)

# 打印当前工作目录
func print_current_directory():
    print("Current directory: ", OS.get_executable_path().get_base_dir())

2. 场景加载调试

# 安全的场景加载
func load_scene_safely(scene_path: String) -> PackedScene:
    if not ResourceLoader.exists(scene_path):
        push_error("Scene file not found: %s" % scene_path)
        return null
    
    var scene = load(scene_path) as PackedScene
    if scene == null:
        push_error("Failed to load scene: %s" % scene_path)
        return null
    
    return scene

3. 节点引用调试

# 安全的节点获取
func get_node_safely(node_path: String) -> Node:
    var node = get_node_or_null(node_path)
    if node == null:
        push_warning("Node not found: %s" % node_path)
    return node

# 检查@onready变量是否正确初始化
func _ready():
    # 验证所有@onready节点
    if not some_button:
        push_error("some_button not found - check node path")
    if not some_label:
        push_error("some_label not found - check node path")

🛠️ 项目结构问题

1. 文件移动后的检查清单

• 更新.tscn文件中的脚本路径
• 更新project.godot中的AutoLoad路径
• 更新代码中的硬编码路径
• 清理Godot缓存文件
• 重新导入项目

2. 缓存清理命令

# Windows PowerShell
Remove-Item -Recurse -Force ".godot\uid_cache.bin"
Remove-Item -Recurse -Force ".godot\global_script_class_cache.cfg"

# Linux/macOS
rm -rf .godot/uid_cache.bin
rm -rf .godot/global_script_class_cache.cfg

3. 路径常量管理

# 在 _Core/ProjectPaths.gd 中定义所有路径
class_name ProjectPaths

# 核心路径
const CORE_ROOT = "res://_Core/"
const MANAGERS_PATH = CORE_ROOT + "managers/"
const SYSTEMS_PATH = CORE_ROOT + "systems/"
const UTILS_PATH = CORE_ROOT + "utils/"

# 场景路径
const SCENES_ROOT = "res://scenes/"
const UI_PATH = SCENES_ROOT + "ui/"
const MAPS_PATH = SCENES_ROOT + "maps/"

# 使用示例
var scene_path = ProjectPaths.UI_PATH + "LoginWindow.tscn"

🎯 性能问题

1. 内存泄漏检测

# 监控节点数量
func _ready():
    print("Initial node count: ", get_tree().get_node_count())

func _exit_tree():
    print("Final node count: ", get_tree().get_node_count())

# 检查未释放的资源
func check_resource_leaks():
    print("Resource count: ", ResourceLoader.get_resource_list().size())

2. 帧率监控

# 在 _Core/managers/PerformanceManager.gd
extends Node

var frame_count: int = 0
var fps_timer: float = 0.0

func _process(delta: float):
    frame_count += 1
    fps_timer += delta
    
    if fps_timer >= 1.0:
        var fps = frame_count / fps_timer
        if fps < 30:
            push_warning("Low FPS detected: %.1f" % fps)
        
        frame_count = 0
        fps_timer = 0.0

🔧 开发工具问题

1. Godot编辑器崩溃

解决方案:

1. 备份项目文件
2. 删除.godot文件夹
3. 重新打开项目
4. 重新导入所有资源

2. 脚本编辑器问题

解决方案:

# 检查脚本语法
# 使用 Godot 内置的语法检查器
# 或者在命令行中运行：
# godot --check-only script.gd

3. 场景编辑器问题

解决方案:

• 检查场景文件是否损坏
• 重新创建有问题的场景
• 使用版本控制恢复到工作版本

---

💡 提示: 遇到问题时，首先检查Godot的输出面板和调试器，它们通常会提供详细的错误信息和解决建议。