根本原因是unity未生成或更新.csproj文件；需在unity中手动执行assets→open c# project，确保omnisharp能正确加载unity api引用、.net sdk版本匹配，并开启debug mode以支持断点调试。
VSCode 识别不了 Unity API？先检查项目文件生成是否完整
VSCode 显示 UnityEngine 报红、Debug.Log 无提示、跳转定义失败——根本原因不是扩展没装，而是 Unity 没生成或没更新 .csproj 文件。C# Dev Kit 和 Omnisharp 都依赖这些文件定位 Unity 版本、API 程序集和引用路径。
- 在 Unity 编辑器中，必须手动触发
Assets → Open C# Project（不是双击脚本打开），否则 VSCode 启动时加载的是空壳工程 - 确保 Unity 的
Player Settings → Other Settings → Scripting Runtime Version与本地安装的 .NET SDK 匹配：选.NET 6.0就得装.NET SDK 6.0+（非运行时），选.NET Standard 2.1则需SDK 5.0+ - 若仍报
Unable to load project，关闭 VSCode，删掉项目根目录下的.vscode/、.sln、.csproj、obj/、bin/，再回 Unity 重新Open C# Project
断点不命中？Unity 编辑器必须处于 Debug Mode
VSCode 设置了断点，点击 Play 后毫无反应——大概率是 Unity 编辑器右下角状态栏的 Debug 按钮处于关闭状态。Release Mode 下 Unity 会剥离调试符号，VSCode 无法注入调试信息。
- 点击 Unity 状态栏右下角的
Debug按钮，切换为高亮状态（图标变蓝）；弹出窗口中确认显示Debug Mode - 该模式仅影响编辑器内播放（Play Mode），不影响构建包性能；但若追求极致编辑器运行速度，可临时切回 Release Mode，调试时再切回来
- 不要依赖 Unity Preferences 里的 “Editor Attaching” 选项——它在较新版本中已弃用，实际开关就是状态栏这个按钮
launch.json 怎么配？用 Unity Tools 扩展自动生成最稳
手写 launch.json 容易错在 pipeCommand 路径、processId 或 sourceFileMap 映射，尤其跨平台时 Windows/Mac/Linux 路径格式不同。Unity Tools 扩展内置的调试配置器能自动适配当前环境。
- 确保已安装
Unity Tools扩展（由 Unity Technologies 官方发布，非第三方“Debugger for Unity”） - 按
Ctrl+Shift+P（Win）或Cmd+Shift+P（Mac），输入Unity: Attach to Editor，回车执行 - VSCode 会自动创建
.vscode/launch.json并填入正确配置，包括动态识别 Unity Editor 进程、设置type: "unity"而非过时的"coreclr" - 若提示 “No Unity Editor found”，检查 Unity 是否已在运行且处于 Play Mode —— 必须先点 Unity 的 Play 按钮，再在 VSCode 中启动 Attach
Android 真机调试连不上？重点看端口绑定和网络可达性
VSCode 提示 Connection refused 或一直 pending，不是 VSCode 配置问题，而是 Unity 在设备上监听的地址不可达。默认 127.0.0.1:56000 只允许设备本地连接，PC 无法直连。
- 构建时务必勾选
Development Build+Script Debugging（Build Settings → Android） - 用
adb logcat | grep -i "Listening for debugger"查日志，确认输出的是设备局域网 IP（如192.168.1.100:56789），而不是127.0.0.1 - 若只看到
127.0.0.1，说明 Unity 默认绑定了 loopback 接口，此时必须用 ADB 转发：adb forward tcp:56000 tcp:56000，然后在launch.json中 endpoint 设为"localhost:56000" - Wi-Fi 调试需确保 PC 和手机在同一子网，且路由器未开启 AP 隔离（常见于公共热点）
Unity 的调试链路比表面看起来更依赖状态同步：Unity 编辑器进程、Debug Mode 开关、项目文件时间戳、VSCode 扩展版本，四个环节任一滞后都会导致断点失效。最容易被忽略的是 Open C# Project 这个动作——它不是一次性设置，每次修改 Assembly Definition 或升级 Unity 版本后都得重做。
