​
Windsurf 开发环境搭建指南

​
概览

Windsurf 工作区在编译、代码规范检查和调试方面仅依赖开源工具链。由于 Microsoft 的专有 Visual Studio 组件无法再分发，我们改为集成由社区维护的语言服务器、调试器和编译器。 本指南涵盖两套技术栈：
  1. .NET / C# —— 同时支持 .NET Core 和 .NET Framework（通过 Mono）
  2. C / C++ —— 使用基于 clang 的工具链
你可以在同一工作区中安装其中任意一种，或两者同时安装。
⚠️ 重要：以下示例为模板，需根据你的具体项目进行定制。请修改文件路径、项目名称和构建命令以匹配你的代码库。

​
1. .NET / C# 开发

请选择与您的代码库相匹配的变体。

​
.NET Core / .NET 6+

扩展：
  • C# (muhammad-sammy.csharp) – 集成 OmniSharp LS 和 NetCoreDbg，可直接按 F5 运行
  • .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime) – 自动安装缺失的运行时/SDK
  • Solution Explorer (fernandoescolar.vscode-solution-explorer) – 浏览和管理 .NET 解决方案与项目
调试器： 无需其他组件——该扩展已内置语言服务器和适用于 .NET Core 的开源调试器。 构建： dotnet build

​
通过 Mono 使用 .NET Framework

扩展：
  • Mono Debug (chrisatwindsurf.mono-debug) – Mono 的调试适配器（Open VSX）
  • C# (muhammad-sammy.csharp) 提供语言功能
调试器： 还必须在工作区内安装 Mono 工具链。 请按照 Mono 仓库中的安装指南进行安装。调试器扩展会在调试时连接到该运行时。
⚠️ .NET Framework 配置：安装 Mono 后，如需在 .NET Framework 项目中使用 C# 扩展，需要在 IDE 设置中切换一项特定设置。前往 Settings（C# Extension 部分），关闭 “Omnisharp: Use Modern Net”。该设置使用针对 .NET 6 的 OmniSharp 构建，可为 SDK 风格的 Framework、.NET Core 和 .NET 5+ 项目带来显著性能提升。请注意，该版本不支持非 SDK 风格的 .NET Framework 项目（包括 Unity）。
构建： mcs Program.cs

​
为你的项目配置 tasks.json

你必须在工作区根目录创建或编辑 .vscode/tasks.json，并自定义以下模板： 
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-dotnet",
      "type": "shell",
      "command": "dotnet",
      "args": ["build", "YourProject.csproj"], // ← 编辑这里
      "group": "build",
      "problemMatcher": "$msCompile"
    },
    {
      "label": "build-mono",
      "type": "shell",
      "command": "mcs",
      "args": ["YourProgram.cs"], // ← 编辑这里
      "group": "build"
    }
  ]
}

​
配置用于调试的 launch.json

你必须在工作区根目录创建或编辑 .vscode/launch.json，并更新其中的路径： 
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build-dotnet",
      "program": "${workspaceFolder}/bin/Debug/net6.0/YourApp.dll", // ← 编辑此路径
      "cwd": "${workspaceFolder}",
      "args": [] // 如需要，请添加命令行参数
    },
    {
      "name": "Mono Launch",
      "type": "mono",
      "request": "launch",
      "preLaunchTask": "build-mono",
      "program": "${workspaceFolder}/YourProgram.exe", // ← 编辑此路径
      "cwd": "${workspaceFolder}"
    }
  ]
}

​
CLI 等效项

# .NET Core
$ dotnet build
$ dotnet run

# Mono / .NET Framework
$ mcs Program.cs
$ mono Program.exe

​
.NET Framework 限制

⚠️ 重要：含有混合程序集（C++/CLI）或对 Visual Studio 有复杂依赖的 .NET Framework 代码库在 Windsurf 中存在较大局限。这类代码库通常依赖 Visual Studio 的专有构建系统，并因依赖 Microsoft 特定工具链及程序集引用解析，无法在 Windsurf 中实现完整的编译或调试。 针对 .NET Framework 项目的推荐方案：
  • 将 Windsurf 与 Visual Studio 搭配使用，用于代码生成与编辑
  • 在可行情况下，将可兼容的部分迁移到 .NET Core

​
2. C / C++ 开发

必备扩展：
扩展目的
Windsurf C++ Tools (Codeium.windsurf-cpptools)我们推荐的入门三件套扩展合集。包含 C/C++ 的 LSP 支持、调试支持和 CMake 支持。
**注意：**安装 Windsurf C++ Tools 合集会自动安装下方列出的各个扩展，因此你只需安装该合集即可。
扩展目的
clangd (llvm-vs-code-extensions.vscode-clangd)clangd 语言服务器集成。如果未安装 clangd，它会提示为你的平台下载正确的二进制文件。
CodeLLDB (vadimcn.vscode-lldb)基于 LLDB 的原生调试器，适用于 C/C++ 和 Rust 代码。
CMake Tools (ms-vscode.cmake-tools)为基于 CMake 的项目提供项目配置、构建、测试与调试集成。
对于非 CMake 的工作流，你仍然可以通过自定义的 tasks.json 任务调用 make、ninja 等。

​
配置 C/C++ 构建任务

为你的 C/C++ 项目创建或编辑 .vscode/tasks.json： 
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-cpp",
      "type": "shell",
      "command": "clang++",
      "args": ["-g", "main.cpp", "-o", "main"], // ← 请根据您的文件修改
      "group": "build",
      "problemMatcher": "$gcc"
    }
  ]
}

​
3. 注意与提示

  • 仅限开源——拒绝任何安装微软专有工具的提示；Windsurf 容器无法随附/分发此类组件。
  • 容器 vs 主机——SDK/编译器必须安装在 Windsurf 工作区的容器内。
  • 键盘快捷键
    • Ctrl/⌘ + Shift + B → 使用当前活动的构建任务进行编译
    • F5 → 使用所选 launch.json 配置进行调试

​
4. 设置清单

  • 为你的语言栈安装所需扩展
  • 创建并自定义 .vscode/tasks.json，添加项目的构建命令
  • 创建并自定义 .vscode/launch.json，配置可执行文件的正确路径
  • 对于 Mono：安装运行时并通过 mono --version 验证
  • 更新文件路径、项目名称和构建参数，使其与代码库一致
  • 测试你的设置：按 Ctrl/⌘ + Shift + B 进行构建，然后按 F5 进行调试
💡 提示：这些配置文件是按项目划分的。你需要为每个工作区调整上述示例。