VSCode 搭建远程 Linux 开发环境

前言

本文将介绍 VSCode 如何搭建远程 Linux 开发环境（远程开发），实现的效果相当于在远程 Linux 服务器上直接开发 C/C++ 项目，适用于 Windows 系统。

搭建步骤

VSCode 搭建远程 Linux 开发环境的步骤：

• (1) 在远程 Linux 系统中安装并运行 SSH 服务
• (2) 在本地 Windows 系统的 VSCode 中安装 C/C++ 相关插件，比如：
  • Remote Development：远程开发插件，支持连接远程 Linux 服务器、Docker 容器、WSL。
  • C/C++：C/C++ 核心插件，提供 C/C++ 智能感知、调试、导航、语法提示等核心功能。
  • C/C++ Extension Pack：C/C++ 插件组合包，用于一键安装多个与 C/C++ 开发相关的扩展，方便快速配置。
  • Code Runner：代码快速运行插件（可选安装），仅支持运行单个源文件，支持多种语言，包括 C/C++、Java、JS、PHP、Python、、Go、Lua 等。
• (3) 在本地 Windows 系统的 VSCode 中配置远程 Linux 服务器的信息。
• (4) 在本地 Windows 系统的 VSCode 中连接远程的 Linux 服务器进行开发（即远程开发）。

特别注意

• VSCode 远程开发环境的详细搭建教程，可以参考文末给出的 参考资料，这里不再累述。
• VSCode 安装 C/C++ 相关插件后的插件列表如下图所示。

特别注意

这里注意不要安装 C/C++ Runner 这款插件（支持直接运行单个或多个 C/C++ 源文件），因为 C/C++ Runner 插件不会自动安装到远程环境中，也不支持在远程环境中运行，因为它的设计是为了在本地运行 C/C++ 程序。

常见问题

直接运行程序找不到头文件

问题描述

• 当 C/C++ 源文件中引入了自定义的头文件，执行 VSCode 右上角的 运行 C/C++ 文件 按钮运行程序后（如下图所示），会出现找不到头文件的错误。

• 这是因为 VSCode 是使用 g++ 命令直接编译当前打开的 .cpp 文件，仅执行 g++ file.cpp -o file && ./file 这种快速编译运行命令，而没有加上自定义头文件所在的目录路径（-I 参数）所导致的。

解决方案一

• 创建或编辑当前项目的 .vscode/c_cpp_properties.json 文件，或者使用 cmd + shift + p 快捷键打开命令面板并输入 C/C++ Edit Configurations (JSON)），然后更改对应的配置内容

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**"       // 用于 VSCode 的 IntelliSense 引擎（代码提示、跳转、补全等），帮助它找到头文件的位置，不是用于编译代码。编译用的头文件路径是在 ./vscode/tasks.json 或 CMakeLists.txt 中通过 `-I` 参数来指定
            ],
            "defines": [],
            "compilerPath": "/usr/bin/g++",   // 指定使用的编译器
            "cStandard": "c11",               // 指定 C 版本
            "cppStandard": "gnu++11",         // 指定 C++ 版本
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

• 创建或编辑当前项目的 .vscode/tasks.json 文件，然后添加 Task

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "cppbuild",
            "label": "C/C++: g++ build active file",
            "command": "/usr/bin/g++",
            "args": [
                "-fdiagnostics-color=always",
                "-g",
                "${file}",
                "-o",
                "${fileDirname}/${fileBasenameNoExtension}", // 指定输出的可执行文件名
                "-Iinclude", // 指定项目的头文件目录，可选配置项
                "-lpthread" // 指定链接的静态库或者动态链接库（必须注意顺序，从上到下链接），可选配置项
            ],
            "options": {
                "cwd": "${workspaceFolder}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

• 然后执行 VSCode 右上角的 运行 C/C++ 文件 按钮运行程序后（如下图所示），就可以正常运行 C/C++ 程序

解决方案二

• 创建或编辑当前项目的 .vscode/tasks.json 文件，然后添加 Task

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Main with include",
      "type": "shell",
      "command": "g++",
      "args": [
        "-Iinclude",       // 指定头文件路径
        "main.cpp",        // 指定目标源文件名
        "-o",
        "main"             // 指定输出的可执行文件名
      ],
      "group": "build",
      "problemMatcher": [],
      "detail": "Compile with header path"
    }
  ]
}

• 创建或编辑当前项目的 .vscode/launch.json 文件，然后指定 Task

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch main",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/main",     // 指定可执行文件
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "Run Main with include",      // 指定 Task
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb"
    }
  ]
}

• 按下快捷键 Ctrl + Shift + D，调出 VSCode 的 运行和调试 面板，然后在顶部选择自定义的配置 Launch main，最后点击左边的 绿色 按钮就可以正常运行程序。

• 在第一次运行程序后，VSCode 的底部工具栏会新增 Launch main 相关的操作按钮，以后可以直接在底部工具栏运行或调试 C/C++ 程序，还可以使用快捷键 F5 直接运行。

注意事项

VSCode 中 运行 C/C++ 文件 按钮的行为非常简单（如下表所示），因此更推荐使用 CMake 管理 C/C++ 项目，并使用 launch.json + task.json 来调用它。

特性	说明
默认使用 g++ 编译当前文件	忽略项目结构和依赖关系
不支持多源文件编译	如果有 main.cpp 和 other.cpp，它不会编译全部源文件
不自动添加 -I、-L 参数	所以无法识别头文件或链接库
不识别 CMake 项目	所以不适合正式工程

CMake 项目无法直接运行

问题描述

• C/C++ 源文件中引入了自定义的头文件，并且已经在 CMake 配置文件中指定了对应的头文件目录路径；但点击 VSCode 右上角的 运行 C/C++ 文件 按钮时，CMake 项目无法正常运行（如下图所示）。

• 这是因为点击 运行 C/C++ 文件 按钮后，其实触发的是 C/C++: Run 快捷命令，这个命令不会走 CMake，而是仅对当前打开的 .cpp 文件执行 g++ file.cpp -o file && ./file 这种快速编译运行命令，也就是说编译参数中并没有加上自定义头文件所在的目录路径（-I 参数）。

解决方案一

• 创建或编辑当前项目的 .vscode/tasks.json 文件，然后添加 Task

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "CMake Build",
      "type": "shell",
      "command": "cmake -S . -B build && cmake --build build",
      "problemMatcher": []
    }
  ]
}

• 创建或编辑当前项目的 .vscode/launch.json 文件，然后指定 Task

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run CMake Executable",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/main",   // 指定 CMake 输出的可执行文件名
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "CMake Build",   // 指定 Task
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb"
    }
  ]
}

• 按下快捷键 Ctrl + Shift + D，调出 VSCode 的 运行和调试 面板，然后在顶部选择自定义的配置 Run CMake Executable，最后点击左边的 绿色 按钮就可以正常运行 CMake 项目。

• 在第一次运行程序后，VSCode 的底部工具栏会新增 Launch main 相关的操作按钮，以后可以直接在底部工具栏运行或调试 CMake 项目，还可以使用快捷键 F5 直接运行。

解决方案二

在 VSCode 中安装 CMake Tools 插件，打开 CMake 项目后，点击左下角状态栏中的 工具图标，确认 CMake Tools 插件已经识别 CMake 项目，然后就可以选择生成、调试、运行 CMake 项目了。

注意事项

当使用 CMake 管理 C/C++ 项目时，CMake 会自动搜索 Linux 操作系统中的头文件和库（静态库与动态链接库），默认的搜索路径如下：

• 头文件搜索

  • /usr/include
  • /usr/local/include

• 库（静态库与动态链接库）搜索

  • /usr/lib
  • /usr/local/lib

因此，在 CMake 项目中，通常不需要手动指定上述这些头文件路径和库路径。

免密码连接远程 Linux 服务器

问题描述

VSCode 安装完 Remote Development 插件后，每次连接远程的 Linux 服务器都会提示输入密码，非常不方便。

问题解决

• (1) 在本地的 Windows 系统中，安装 Git Bash 工具；然后在 Git Bash 中执行以下命令生成 SSH 公钥，默认保存位置是：~/.ssh/id_rsa（私钥）和 ~/.ssh/id_rsa.pub（公钥）

# 生成 SSH 秘钥对，一路回车即可（通常无需设置密码）
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

• (2) 在本地的 Git Bash 中，执行以下命令将公钥拷贝到远程 Linux 服务器中

# 拷贝公钥到远程 Linux 服务器（第一次拷贝会要求输入远程服务器的密码，之后设置完成即可免密）
ssh-copy-id root@192.168.1.100

• (3) 在本地的 Git Bash 中，测试 SSH 登录是否免密成功

ssh root@192.168.1.100

• (4) 重新运行 VSCode，选择需要连接的 Linux 服务器，观察是否可以成功免密建立远程连接

C/C++ 代码实现格式化

问题描述

VSCode 默认的 C/C++ 代码格式化风格不太习惯，比如每个大括号都是换行显示的，希望更改为自己所需的代码风格。

问题解决

• (1) 在远程 Linux 服务器上安装 clang-format 代码格式化工具

sudo apt-get install -y clang-format

• (2) 在本地的 VSCode 中安装 Clang-Format 插件

• (3) 创建或编辑当前项目的 .vscode/settings.json 文件，添加以下配置内容：

{
    // C 代码格式化配置
    "[c]": {
        "editor.defaultFormatter": "xaver.clang-format", // 指定格式化器，远程服务器必须先安装 clang-format 工具
        "editor.formatOnSave": false // 可选，保存文件时自动格式化
    },
    // C++ 代码格式化配置
    "[cpp]": {
        "editor.defaultFormatter": "xaver.clang-format", // 指定格式化器，远程服务器必须先安装 clang-format 工具
        "editor.formatOnSave": false // 可选，保存文件时自动格式化
    },
    // 代码格式化规则
    "clang-format.style": "{ BasedOnStyle: Google, IndentWidth: 4, TabWidth: 4, AccessModifierOffset: -4, UseTab: Never, ColumnLimit: 120, AllowShortFunctionsOnASingleLine: None }"
}

提示：推荐将代码格式化规则配置在项目根目录下的 .clang-format 文件中（如下），然后在当前项目的 .vscode/settings.json 文件中添加配置内容 "clang-format.style": "file"，让代码格式化插件去自动读取项目中的 .clang-format 文件。

{
    // C 代码格式化配置
    "[c]": {
        "editor.defaultFormatter": "xaver.clang-format", // 指定格式化器，远程服务器必须先安装 clang-format 工具
        "editor.formatOnSave": false // 可选，保存文件时自动格式化
    },
    // C++ 代码格式化配置
    "[cpp]": {
        "editor.defaultFormatter": "xaver.clang-format", // 指定格式化器，远程服务器必须先安装 clang-format 工具
        "editor.formatOnSave": false // 可选，保存文件时自动格式化
    },
    // 从 .clang-format 文件读取代码格式化规则
    "clang-format.style": "file"
}

# 基于哪种代码风格，可选：LLVM、Google、Chromium、Mozilla、WebKit 等
BasedOnStyle: Google

# 每一层缩进使用的空格数（默认 Google 是 2，这里改为 4）
IndentWidth: 4

# 设置一个制表符（Tab）等价于多少个空格（影响对齐）
TabWidth: 4

# 使访问修饰符（如 private:）顶格，不缩进
AccessModifierOffset: -4

# 是否使用 Tab 缩进：
#   - Never: 一律使用空格
#   - Always: 总是使用 Tab
#   - ForIndentation: 缩进用 Tab，对齐用空格
UseTab: Never

# 每行的最大字符数限制
ColumnLimit: 120

# 强制所有函数体换行，即使只有一行
AllowShortFunctionsOnASingleLine: None

• (4) 配置 VSCode 的 C/C++ 代码格式化快捷键
  • 按 Ctrl + Shift + P 组合建打开命令面板
  • 输入 Preferences: Open Keyboard Shortcuts (JSON) 并回车
  • 在打开的 keybindings.json 文件里，添加以下配置内容：

    [
        // 格式化选中的 C/C++ 代码块
        {
            "key": "ctrl+l",
            "command": "editor.action.formatSelection",
            "when": "editorTextFocus && (editorLangId == 'cpp' || editorLangId == 'c') && editorHasSelection"
        },
        // 格式化整个 C/C++ 源文件
        {
            "key": "ctrl+l",
            "command": "editor.action.formatDocument",
            "when": "editorTextFocus && (editorLangId == 'cpp' || editorLangId == 'c') && !editorHasSelection"
        }
    ]

参考资料

• VSCode 使用 SSH 进行远程开发
• VSCode 远程开发 - SSH 入门保姆级教程
• Windows 平台下 VSCode 配置远程 Linux 开发环境
• Windows 平台使用 VSCode 远程连接 Linux 进行 C++ 开发配置教程