gdscript扩展需装官方godot tools并重启vscode，确保project.godot存在且语言模式设为gdscript；调试须godot带--remote-debug启动、launch.json端口一致、编辑器启用网络调试；断点需路径大小写与映射准确；补全异常时重启语言服务器。
GDScript扩展没装对，代码提示直接失效
VSCode 默认不识别 GDScript，必须手动安装官方扩展。很多人搜“Godot VSCode 插件”点进非官方的旧版或已弃用扩展（比如过时的 godot-tools），结果语法高亮有、但跳转和补全全挂掉。
- 只认准官方扩展：
Godot Tools（作者是godotengine，图标带紫色 G） - 安装后必须重启 VSCode，否则语言服务器不启动
- 确认项目根目录下存在
project.godot文件——没有它，Godot Tools会静默降级为纯文本模式，提示全无 - 如果已打开文件夹但提示仍不工作，右下角点击语言模式（如“Plain Text”），手动切换为
GDScript
调试器连不上：Godot 启动参数和 VSCode 配置要咬合
VSCode 调试 GDScript 不是“装完插件就自动好”，本质是靠 Godot 启动时开启调试服务，再由 VSCode 的 launch.json 主动连接。常见现象是断点灰色、控制台显示 Could not connect to Godot。
- Godot 必须以调试模式启动：命令行加
--remote-debug 127.0.0.1:6007（端口默认 6007，可改但需同步） -
.vscode/launch.json中的port和host必须与 Godot 启动参数完全一致 - Godot 4.x 要求启用
Debug → Settings → Network → Enable Debugging（编辑器设置里开，不是项目设置） - 如果用 Godot 编辑器内置运行（F5），VSCode 调试器无法介入——必须用外部启动方式（终端或任务）
断点不命中：GDScript 文件路径映射错位
VSCode 断点打在 res://scripts/player.gd，但 Godot 实际加载的是 res://Scripts/Player.gd（大小写或路径分隔符差异），调试器就找不到对应源码。Windows 上尤其容易因大小写不敏感掩盖问题，Linux/macOS 直接失败。
- 确保 VSCode 工作区路径就是 Godot 项目的根目录（含
project.godot），不要嵌套在子文件夹里 - 检查
launch.json中的pathMappings：默认配置通常够用，但如果项目用了符号链接或自定义资源路径，需显式映射，例如："pathMappings": [ ["res://", "${workspaceFolder}/res/"] ] - Godot 4.2+ 对
res://解析更严格，避免在脚本中用OS.get_executable_path()拼路径替代res://
自动补全卡顿或漏成员：GDScript 语言服务器未热重载
改完 class_name 或新增 export 变量后，VSCode 补全不更新，甚至报 Cannot find name 'MyNode'。这不是缓存问题，而是 Godot Tools 的语言服务器没感知到项目结构变化。
- 保存
project.godot或任意.gd文件后，状态栏左下角应出现GDScript: Ready；若一直显示Starting...，说明语言服务器卡住 - 强制重启语言服务器：按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Godot: Restart Language Server - 禁用其他 GDScript 相关扩展（如
GDScript Syntax），它们会和官方扩展冲突 - 大型项目首次索引可能耗时 1–2 分钟，期间补全不可用，别急着重装
路径映射、语言服务器状态、Godot 启动参数这三处一旦错一个，调试和提示就断链。不是配置越复杂越好，而是每个环节都得严丝合缝。
