VS Code 配置 C# 开发环境教程

VS Code 开发 C# 需同时安装 C# 扩展、.NET SDK（非 Runtime）、并正确配置 launch.json；缺一不可，且需验证 dotnet --version、OmniSharp 就绪状态及 program 路径真实性。

VS Code 本身不内置 C# 支持，必须手动装扩展 + 运行时 + SDK 才能真正编译调试，缺一不可。只装 C# 扩展是没用的。

装对 .NET SDK 而不是 .NET Runtime

很多人卡在这一步：下载了 .NET Runtime（仅运行），但开发需要的是 .NET SDK（含编译器、dotnet 命令、项目模板）。Windows/macOS/Linux 都要去 https://dotnet.microsoft.com/download 下载最新 SDK（带 “SDK” 字样，如 .NET 8.0 SDK）。

• 装完后终端执行 dotnet --version 应返回版本号，不是 “command not found”
• 别用 Visual Studio 自带的 SDK 路径——VS Code 默认不识别它，除非你手动配置 dotnet.path
• macOS 用户注意：若用 Homebrew 装过旧版，先 brew uninstall dotnet-sdk 再装官网包，避免冲突

必须启用 C# 扩展并等待 OmniSharp 启动完成

C# 扩展（由 OmniSharp 提供后端）不是装完就立刻可用。打开一个 .csproj 文件或 Program.cs 后，右下角会显示 “OmniSharp: Starting…”，需等状态变成 “OmniSharp: Ready”。此时才会有代码补全、跳转、错误检查。

• 如果一直卡在 “Starting”，检查终端里是否能跑通 dotnet --info；不能则 OmniSharp 找不到 SDK
• 禁用其他可能干扰的扩展（比如某些 LSP 客户端、旧版 C# Extensions）
• 首次打开项目时，VS Code 可能提示 “Required assets to build and debug are missing…”，点 Yes 自动生成 .vscode/launch.json 和 tasks.json

调试前要确认 launch.json 的 program 路径正确

自动生成的 launch.json 里 program 字段默认指向 ${workspaceFolder}/bin/Debug//.dll。但如果项目是 net8.0-windows 或用了 WinExe，路径中会多出 win-x64 这类 RID 子目录，导致调试失败报错：Could not find file … .dll。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch (console)",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/bin/Debug/net8.0/MyApp.dll",
      "args": [],
      "cwd": "${workspaceFolder}",
      "console": "internalConsole",
      "stopAtEntry": false
    }
  ]
}

• 手动构建一次项目：dotnet build，然后去 bin/Debug/ 下看实际生成的路径结构
• 把 launch.json 中 program 改成真实路径，不要依赖自动补全的默认值
• 如果项目含多个 TargetFramework（如 net6.0;net8.0），program 必须对应你当前想调试的那个框架输出目录

常见报错直接对应原因

遇到这些提示，基本不用猜：

• Could not resolve CoreCLR path → dotnet 命令不可用，或 DOTNET_ROOT 环境变量未设（Linux/macOS 尤其要注意）
• The type or namespace name 'System' could not be found → OmniSharp 没加载成功，或项目文件（.csproj）有语法错误
• 断点灰了、不命中 → launch.json 的 program 路径错，或没生成调试符号（确保 portable 在 .csproj 里）
• 按 F5 没反应 → 没选中正确的 launch 配置，或 tasks.json 里 dotnet build 任务被删了

最常被忽略的是：以为装了扩展就等于环境好了，其实 dotnet CLI 是否就绪、OmniSharp 是否真正连上、launch.json 是否指向真实输出路径——这三个环节任何一个断掉，C# 开发就停在“写不了、编不了、调不了”的状态。