VSCode配置C#环境：.NET SDK安装与运行

VSCode 运行 C# 代码环境配置指南：.NET SDK 安装与执行详解

先说一个很多开发者都曾掉进去的坑：VSCode 本身并不直接执行 C# 代码，它本质上只是一个编辑器加上调试前端。真正承担编译与运行工作的是你本地安装的 dotnet 命令行工具以及 .NET SDK 所提供的完整工具链。如果装错了组件——比如只安装了 Runtime 而非 SDK，或者环境路径没有正确配置，又或者项目打开方式不对——那么结果就是 dotnet run 报错、按下 F5 后黑屏、IntelliSense 灯不亮。别急着把问题归咎于 VSCode，根源在于底层环境没有就绪。

下面我们一步步拆解，把 C# 开发环境真正搭建好。

必须安装 .NET SDK，而不是 Runtime

Runtime 只能运行别人已经编译好的 .dll 文件，它既不能编译 .cs 源文件，也无法生成项目或支持调试器。VSCode 的 C# 扩展（尤其是 C# Dev Kit）依赖于 SDK 中的 Roslyn 编译器、dotnet build 和 dotnet new 等核心命令。只要装错一个组件，整个开发流程就会瘫痪。

• Windows：请前往 dotnet.microsoft.com/download 下载带有“SDK”字样的安装包（例如 .NET SDK 8.0.400），千万不要误选“ASP.NET Core Runtime”或“Desktop Runtime”。
• macOS：使用 brew install --cask dotnet-sdk 命令安装，然后务必再执行 xcode-select --install，否则 dotnet build 会抛出错误 MSB4236。
• Ubuntu/Debian：按照官方步骤添加软件源后，运行 sudo apt install dotnet-sdk-8.0 libicu72 libssl3；默认安装路径为 /usr/share/dotnet。
• 验证命令必须全部通过：dotnet --version（应输出版本号）、dotnet --list-sdks（应列出 SDK 路径列表）。两个命令均正确执行，才算安装成功。

VSCode 必须以文件夹方式打开项目

C# 扩展（无论是 OmniSharp 还是 C# Dev Kit）只有在包含 .csproj、.sln 或 global.json 的目录下才会正常激活。如果你直接打开单个 Program.cs 文件，状态栏会显示“C# features are disabled”，此时按下 F5 必定失败。

• 正确操作：先执行 dotnet new console -n MyApp 创建项目，然后 cd MyApp 进入目录，再运行 code . 打开。在 VSCode 中通过 File > Open Folder 选择 MyApp 文件夹。
• 如果不小心打开了单个文件：请关闭整个 VSCode 窗口，重新以文件夹方式打开即可。
• 打开后观察右下角状态栏，应显示 C# (.NET) 或 OmniSharp: Running；如果卡在“Installing…”，请打开 Output 面板，切换到 OmniSharp Log 查看具体错误信息。

调试前先确保 dotnet run 能正常运行

F5 调试失败，十有八九是项目本身没有编译成功。launch.json 中的 program 字段指向的是 bin/Debug/net8.0/MyApp.dll 这类编译产物，而不是源码。跳过编译直接进行调试，自然会报 Cannot launch program 的错误。

• 在终端中进入项目根目录（即包含 .csproj 的那一层），手动执行 dotnet run。确认成功运行后再按 F5。
• 如果报错 error NETSDK1045: The current .NET SDK does not support targeting .NET 8.0，说明 .csproj 文件中设置的 net8.0 与你本地安装的 SDK 版本不匹配。可以用 dotnet --list-sdks 查看已安装的版本，然后修改 .csproj 中的目标框架或升级 SDK。
• launch.json 中的 program 值建议写成："${workspaceFolder}/bin/Debug/net8.0/${fileBasenameNoExtension}.dll"（注意 net8.0 必须与项目中的 一致）。

C# Dev Kit 是当前调试的必需组件

旧版 C# 扩展（仅含 OmniSharp）已经无法自动配置调试器、生成 launch.json、或支持 .NET 8+ 的热重载功能。C# Dev Kit 并非“锦上添花”，而是当下在 VSCode 中调试 C# 的事实标准。

• 安装后必须重启 VSCode（不是重载窗口，需要彻底关闭再打开），否则 OmniSharp 后端不会加载、.csproj 无法解析、状态栏图标也不会出现。
• macOS/Homebrew 用户常遇到 Dev Kit 找不到 SDK 的问题：重启后按 Cmd+Shift+P 输入 C#: Select .NET SDK，手动指定路径（例如 /opt/homebrew/share/dotnet）。
• Windows 上通过 WinGet 安装的 SDK，路径通常为 C:Program Filesdotnet，同样需要确认是否被 VSCode 正确识别。

最后提醒一个容易被忽略的细节：环境变量继承问题。VSCode 内置终端可能缓存了旧版的 PATH，导致 dotnet --list-sdks 在系统终端能正常运行，但在 VSCode 终端里却显示为空。这时不必折腾复杂配置，关掉 VSCode 全局重新打开，或者新建一个 Terminal 标签页试试。