最常忽略的依赖项是.NET SDK（非Runtime）、xcode-select（macOS）和libicu/libssl（Linux）；C#扩展需.csproj/.sln文件激活；调试失败主因是缺失.pdb符号文件或launch.json中program路径错误。
安装.NET SDK和C#扩展时最常忽略的依赖项
VSCode本身不带.NET运行时，必须单独安装.NET SDK（不是仅装Runtime）。Windows用户容易误装“ASP.NET Core Runtime”，它不能编译代码；macOS用户常跳过xcode-select --install，导致dotnet build报MSB4236: The SDK 'Microsoft.NET.Sdk' could not be found；Linux用户则可能漏装libicu或libssl，表现为Failed to initialize CoreCLR。
确认安装成功只需终端执行：dotnet --list-sdks，输出应含类似8.0.100 [/usr/share/dotnet/sdk]的行。若无输出，重装SDK并重启终端——VSCode不会自动继承新环境变量。
- Windows：从 dotnet.microsoft.com/download 下载「.NET SDK」（带"x64"或"ARM64"标识），**不要选"Runtime"**
- macOS：用
brew install --cask dotnet-sdk，再运行xcode-select --install - Linux（Ubuntu/Debian）：按官方repo步骤添加源后，
sudo apt install dotnet-sdk-8.0，再sudo apt install libicu72 libssl3（版本号依发行版调整）
VSCode中C#扩展的启用条件与常见失效场景
C#扩展（由OmniSharp提供支持）不会在任意文件夹下自动激活。它只在包含.csproj、.sln或global.json的目录中启动语言服务。如果打开单个.cs文件，编辑器会显示“C# features are disabled”提示，此时F5调试必然失败。
解决方法是确保工作区根目录有项目文件。新建项目推荐用命令行：dotnet new console -n MyApp，然后在VSCode中用File > Open Folder...打开MyApp文件夹（不是MyApp.cs文件）。
- 已打开错误路径？关闭窗口，重新用文件夹方式打开
- 扩展显示“Installing…”卡住？检查
Output面板中OmniSharp Log，常见原因是.NET SDK路径未被识别，需在设置中手动指定omnisharp.dotnetPath - Mac上首次启动慢？OmniSharp需下载约100MB的.NET tool，耐心等待，勿强制退出
launch.json中关键配置项的实际作用
.vscode/launch.json里program字段不是指向.cs源码，而是编译后的.dll路径。VSCode默认生成的模板中"program": "${workspaceFolder}/bin/Debug/net8.0/MyApp.dll"是正确的，但很多人手动改成MyApp.cs导致Cannot launch program; setting 'program' must be an absolute path to the executable。
console属性决定调试时终端行为：integratedTerminal复用VSCode底部终端（适合看日志），externalTerminal弹独立窗口（适合需要交互输入的Console App）。
-
cwd必须设为"${workspaceFolder}"，否则File.OpenRead("data.txt")会找不到相对路径文件 - 调试Web项目（如ASP.NET Core）需用
coreclr类型+env配置ASPNETCORE_ENVIRONMENT，而非直接改program - 修改
launch.json后无需重启VSCode，但需确保当前活动文件是.cs（比如Program.cs），否则F5按钮灰显
调试时断点不命中或变量无法查看的根本原因
断点灰色空心圆，提示“断点未绑定”，90%是因为没生成调试符号（.pdb文件）。这通常发生在：项目属性中DebugType被设为none或pdbonly（后者仅Release可用），或者dotnet build时加了--no-restore但依赖未更新导致构建跳过。
验证方法：检查bin/Debug/net8.0/下是否存在同名.pdb文件。没有？删掉bin和obj文件夹，执行dotnet build -c Debug。
- Unity项目用户注意：Unity自带的.NET版本与SDK不兼容，必须禁用C#扩展，改用Unity Debugger插件
- WPF或WinForms项目需额外安装
Microsoft.NET.Sdk.WindowsDesktop并在.csproj中声明<UseWPF>true</UseWPF>，否则断点能命中但UI线程调试异常 - 修改代码后F5仍运行旧版本？先
dotnet clean，再F5——VSCode的自动构建有时会跳过未改动的中间文件
真正卡住人的往往不是配置步骤，而是.NET SDK版本、项目文件存在性、调试符号生成这三个环节之间的隐式依赖。每次出问题，优先查dotnet --list-sdks、ls bin/Debug/**/*.{dll,pdb}、cat .vscode/launch.json | grep program 这三行命令的输出。
