VS Code 中 C# 项目无法识别 .NET SDK 或提示“OmniSharp server failed”

Question

在 VS Code 中打开 C# 项目时，OmniSharp 频繁报错“OmniSharp server failed”或提示“Failed to load project file: Could not resolve SDK 'Microsoft.NET.Sdk'”，即使已安装 .NET SDK 并能通过终端执行 `dotnet --version` 正常输出。常见诱因包括：VS Code 的 C# 扩展未正确识别全局 .NET SDK 路径（尤其在多版本共存、非默认安装路径或 macOS/Linux 的 shell 初始化差异场景下）；工作区启用了不兼容的 OmniSharp 版本（如旧版扩展与 .NET 8+ SDK 冲突）；项目文件（`.csproj`）引用了不存在或拼写错误的 SDK（如 `Microsoft.NET.Sdk.Web` 但未安装 ASP.NET Core 工作负载）；或用户级 `omnisharp.json` 配置强制指定了错误的 SDK 路径。该问题直接导致代码补全、跳转、诊断等核心功能失效，却无明确错误日志指向根本原因，排查耗时且易被误判为环境损坏。

Answer 1

```html

一、现象层：识别 OmniSharp 失败的典型表征

VS Code 中 C# 扩展右下角持续显示 OmniSharp: Starting... 后转为 OmniSharp server failed；状态栏出现红色警告图标；输出面板切换至 OmniSharp Log 时首行即见 Failed to load project file: Could not resolve SDK 'Microsoft.NET.Sdk'；dotnet --version 和 dotnet --list-sdks 在终端中返回正常，但 OmniSharp 日志中无任何 SDK 路径解析记录。

二、环境层：Shell 上下文与 SDK 可见性断层

• macOS/Linux 下 VS Code 常以 GUI 方式启动（绕过 ~/.zshrc/~/.bash_profile），导致 $PATH 缺失 dotnet 二进制路径；
• Windows WSL2 与宿主机混用时，VS Code 运行于 Windows 但打开 WSL 路径，OmniSharp 默认调用 Windows 版 dotnet，而非 WSL 内的 SDK；
• 多版本共存（如 6.0/7.0/8.0）且未设全局默认（dotnet --global-version 为空），OmniSharp 无法自动选择兼容版本。

三、配置层：omnisharp.json 与扩展策略冲突

用户级 ~/.omnisharp/omnisharp.json 或工作区级 .vscode/omnisharp.json 若存在如下配置，将强制覆盖自动探测逻辑：

{
  "sdk": {
    "useGlobalSDK": false,
    "path": "/opt/dotnet/sdk/7.0.400"  // 实际该路径已删除或权限不足
  }
}

四、项目层：.csproj SDK 引用与工作负载错配

.csproj 中的 <Sdk>	必需的工作负载	验证命令
Microsoft.NET.Sdk.Web	aspnetcore	dotnet workload list | grep aspnetcore
Microsoft.NET.Sdk.BlazorWebAssembly	webassembly-tools	dotnet workload install webassembly-tools

五、扩展层：C# 扩展版本与 .NET SDK 的语义化兼容矩阵

OmniSharp 已于 2023 年起逐步迁移至基于 dotnet tool 的独立运行时模型。关键兼容规则：

• .NET 8+ SDK 要求 C# 扩展 ≥ v1.26.0（含内置 OmniSharp 1.39+）；
• v1.25.x 及更早版本仍依赖 Mono 运行时，在 macOS ARM64 或 Linux glibc 2.38+ 环境下必然崩溃；
• 禁用 “Use Modern .NET” 实验性选项（csharp.omnisharpUseModernNet）将回退至不兼容的旧协议栈。

六、诊断层：精准定位根因的三阶日志法

1. 第一阶（进程层）：在 VS Code 输出面板启用 Developer Tools → Console，搜索 OmniSharpLauncher 启动参数，确认是否传入了 --sdk-path；
2. 第二阶（协议层）：设置 "omnisharp.loggingLevel": "debug"，观察日志中 Found MSBuild at: 与 Resolved SDKs: 是否为空；
3. 第三阶（系统层）：执行 ps aux | grep omnisharp（Linux/macOS）或任务管理器查看子进程完整命令行，比对实际加载的 dotnet runtime 路径。

七、修复层：跨平台标准化处置流程

graph TD A[启动 VS Code] --> B{检查 dotnet 是否在 GUI 环境 PATH 中} B -->|否| C[macOS: 创建 ~/.zprofile 并 export PATH; Linux: 修改 /etc/environment] B -->|是| D[检查 C# 扩展版本 ≥1.26.0] D --> E[验证 .csproj SDK 是否对应已安装工作负载] E --> F[清除 omni* 缓存目录：
~/.omnisharp/ /tmp/omnisharp-*] F --> G[重启 VS Code 并按 Ctrl+Shift+P → “OmniSharp: Restart OmniSharp”]

八、预防层：企业级工程化基线建议

在团队级 devcontainer.json 或 .vscode/settings.json 中固化以下配置，消除个体环境差异：

{
  "csharp.omnisharpUseModernNet": true,
  "csharp.dotnetPath": "/usr/share/dotnet/dotnet",
  "dotnet.dotnetPath": "/usr/share/dotnet/dotnet",
  "omnisharp.enableMsBuildLoadProjectsOnDemand": true
}

九、演进层：.NET Aspire 与 Roslyn LSP 的架构替代路径

对于新项目，建议评估微软官方推荐的演进路线：弃用 OmniSharp，改用原生 Roslyn Language Server（需 VS Code v1.88+ + C# Dev Kit 扩展）。其优势包括：

• 零配置自动匹配 SDK 版本（基于 .csproj 的 <TargetFramework>）；
• 支持 dotnet watch 热重载联动调试；
• 内置对 .NET Aspire 拓扑图、分布式日志等云原生能力的语义感知。

十、验证层：闭环验证清单（5项必检）

1. 终端执行 dotnet --list-sdks 与 OmniSharp 日志中 Resolved SDKs: 行完全一致；
2. 打开任意 .cs 文件后，状态栏显示 C# (Roslyn) 或 C# (OmniSharp) 且无红色感叹号；
3. Ctrl+Click 可跳转至 Console.WriteLine 等基础 API 定义；
4. 修改 .csproj 中 <TargetFramework> 后，OmniSharp 自动重载并报告新 SDK 版本；
5. 执行 dotnet build 成功，且 VS Code 内无红色波浪线提示“无法解析类型”。

```