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引用失效。

**解决方案**:
```gdscript
# 方法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".
```

**解决方案**:
```gdscript
# 检查并更新所有.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
```

**解决方案**:
```ini
# 在 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".
```

**解决方案**:
```gdscript
# 检查资源路径是否正确
# 使用 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. 路径验证
```gdscript
# 验证文件是否存在
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. 场景加载调试
```gdscript
# 安全的场景加载
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. 节点引用调试
```gdscript
# 安全的节点获取
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. 缓存清理命令
```bash
# 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. 路径常量管理
```gdscript
# 在 _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. 内存泄漏检测
```gdscript
# 监控节点数量
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. 帧率监控
```gdscript
# 在 _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. 脚本编辑器问题
**解决方案**:
```gdscript
# 检查脚本语法
# 使用 Godot 内置的语法检查器
# 或者在命令行中运行：
# godot --check-only script.gd
```

### 3. 场景编辑器问题
**解决方案**:
- 检查场景文件是否损坏
- 重新创建有问题的场景
- 使用版本控制恢复到工作版本

---

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