本指南介绍如何在 VSCode/Cursor 中通过 Remote SSH 连接 Linux 服务器（或嵌入式开发板）进行 C/C++ 代码调试，远程代码内联，包括普通调试和需要 root 权限的调试场景。

---

第一部分：VSCode Remote SSH 远程调试

1.1 安装 Remote - SSH 扩展

1. 在 VSCode/Cursor 中打开扩展市场（Ctrl+Shift+X）
2. 搜索 Remote - SSH
3. 点击安装（由 Microsoft 发布）

1.2 配置 SSH 连接

方式 A: 使用 SSH 配置文件（推荐）

在 Windows 上创建或编辑 SSH 配置文件：C:\Users\YourName\.ssh\config

密码登录配置：

Host my-server
    HostName 2409:8a55:3346:a390:ccb1:f61:6c3:2782
    User your-username
    Port 22
    PreferredAuthentications password
    PubkeyAuthentication no
    ServerAliveInterval 60
    ServerAliveCountMax 3

SSH 密钥登录配置（推荐，更安全）：

Host my-server
    HostName 2409:8a55:3346:a390:ccb1:f61:6c3:2782
    User your-username
    Port 22
    IdentityFile ~/.ssh/id_rsa
    ServerAliveInterval 60
    ServerAliveCountMax 3

方式 B: 直接输入地址

在连接时直接输入：user@2409:8a55:3346:a390:ccb1:f61:6c3:2782

1.3 连接到远程服务器

1. 按 Ctrl+Shift+P 打开命令面板
2. 输入 Remote-SSH: Connect to Host
3. 选择 my-server（如果配置了）或输入服务器地址
4. 输入密码（如果使用密码登录）
5. 等待连接完成（首次连接会自动安装 VSCode Server）

注意： VSCode Server 会在首次连接时自动下载和安装，无需手动操作。

1.4 打开项目文件夹

连接成功后，在新窗口中：

1. File → Open Folder...
2. 选择服务器上的项目路径，例如：/home/user/project/04_udp_tcp_api
3. 点击 “OK”

1.5 远程服务器准备工作

确保远程服务器上已安装必要工具：

# 安装 GDB（调试器）
sudo apt-get update
sudo apt-get install gdb

# 安装编译工具
sudo apt-get install build-essential

# 验证
which gdb
gdb --version

1.6 基本调试配置

编辑 .vscode/launch.json：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch",
            "type": "cppdbg",
            "preLaunchTask": "Build with Project Name",
            "request": "launch",
            "program": "${workspaceFolder}/build/${workspaceFolderBasename}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "MIMode": "gdb",
            "miDebuggerPath": "/usr/bin/gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

1.7 开始调试

1. 设置断点：在代码中点击行号左侧，设置断点（红色圆点）
2. 开始调试：按 F5 或点击左侧"运行和调试"图标
3. 调试操作：
   • F5 - 继续执行
   • F10 - 单步执行（Step Over）
   • F11 - 进入函数（Step Into）
   • Shift+F11 - 跳出函数（Step Out）
   • Shift+F5 - 停止调试

调试功能：

• ✅ 断点：普通断点、条件断点、日志断点
• ✅ 变量查看：自动显示局部变量，可展开结构体和数组
• ✅ 调用栈：查看函数调用链
• ✅ 监视表达式：实时查看表达式值
• ✅ 多线程调试：查看和切换线程

---

第二部分：需要 root 权限的调试（如 DPDK 应用）

某些程序（如 DPDK 应用）需要 root 权限才能运行。需要通过 gdb 包装脚本使用 sudo 启动 gdb。

2.1 配置 sudoers 免密执行 gdb

编辑 sudoers 文件，允许当前用户免密执行 gdb：

sudo visudo

在文件末尾添加（将 your-username 替换为你的实际用户名）：

基本配置（推荐）：

your-username ALL=(ALL) NOPASSWD: /usr/bin/gdb

如果需要保留环境变量（可选）：

your-username ALL=(ALL) NOPASSWD:SETENV: /usr/bin/gdb

或者：

Defaults env_keep += "PATH HOME"
your-username ALL=(ALL) NOPASSWD: /usr/bin/gdb

重要：

• 使用 visudo 而不是直接编辑 /etc/sudoers，因为 visudo 会检查语法错误
• 如果看到 “抱歉，您无权保留环境” 错误，gdb 脚本会自动回退，通常也能正常工作

2.2 创建 gdb 包装脚本

在项目根目录创建 gdb 文件：

cd /path/to/your/project
touch gdb
chmod +x gdb

编辑 gdb 文件，添加以下内容：

#!/bin/bash
# GDB wrapper script for sudo debugging
# This script ensures GDB MI interface works correctly with sudo
# 
# Usage: This script is used by VSCode launch.json to run gdb with sudo
# Make sure /usr/bin/gdb is configured for passwordless sudo:
#   sudo visudo
#   Add: username ALL=(ALL) NOPASSWD: /usr/bin/gdb

# Try to preserve environment variables if allowed, otherwise use basic sudo
# "$@": pass all arguments correctly to gdb (VSCode will add -interpreter=mi automatically)
# Redirect stderr to stdout to ensure MI interface works correctly
if sudo -E /usr/bin/gdb "$@" 2>&1; then
    exit 0
else
    # Fallback: use sudo without -E if environment preservation is not allowed
    exec sudo /usr/bin/gdb "$@" 2>&1
fi

设置执行权限：

chmod 755 gdb

说明：

• 脚本首先尝试使用 sudo -E 保留环境变量
• 如果失败（遇到 “无权保留环境” 错误），自动回退到普通 sudo
• 两种方式都能正常工作，MI 接口不依赖特定的环境变量

2.3 修改 launch.json 配置

编辑 .vscode/launch.json，将 miDebuggerPath 指向包装脚本：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch",
            "type": "cppdbg",
            "preLaunchTask": "Build with Project Name",
            "request": "launch",
            "program": "${workspaceFolder}/build/${workspaceFolderBasename}",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "MIMode": "gdb",
            "miDebuggerPath": "${workspaceFolder}/gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
                {
                    "description": "Set Disassembly Flavor to Intel",
                    "text": "-gdb-set disassembly-flavor intel",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

关键配置说明：

• miDebuggerPath: 指向项目根目录的 gdb 包装脚本
• MIMode: 设置为 "gdb"，VSCode 会自动添加 -interpreter=mi 参数

2.4 验证配置

测试 sudo 配置：

# 应该不需要输入密码
sudo /usr/bin/gdb --version

测试 gdb 脚本：

# 在项目根目录
./gdb --version

应该显示 gdb 版本信息，且不需要输入密码。

测试 MI 接口：
在 VSCode 中：

1. 设置断点
2. 按 F5 开始调试
3. 程序应该在断点处停止
4. 关键测试：
   • ✅ 运行时添加新断点应该有效
   • ✅ 点击"暂停"按钮应该能够暂停程序
   • ✅ 可以查看变量、调用栈等

---

第三部分：Cursor 中调试 C/C++

由于 Microsoft 的 C/C++ 扩展在 Cursor 中不被支持（许可限制），需要手动安装特定版本的扩展来启用内联提示功能。

3.1 下载 C/C++ 扩展

访问 GitHub 发布页面：
https://github.com/microsoft/vscode-cpptools/releases/tag/v1.23.5

在 “Assets” 部分下载：

• Windows 客户端：cpptools-win32-x64-1.23.5.vsix
• Linux 服务器：cpptools-linux-x64-1.23.5.vsix

注意： 根据你的系统架构选择对应的版本（x64 或 arm64）

3.2 客户端安装（Windows）

1. 在 Cursor 中按 Ctrl+Shift+P 打开命令面板
2. 输入 Extensions: Install from VSIX...
3. 选择下载的 cpptools-win32-x64-1.23.5.vsix 文件
4. 等待安装完成
5. 重启 Cursor

禁用自动更新：

1. 打开扩展面板（Ctrl+Shift+X）
2. 找到 “C/C++” 扩展
3. 点击扩展右侧的齿轮图标
4. 选择 “Disable Auto Update”

重要： 必须禁用自动更新，否则扩展会自动更新到不兼容的版本。

3.3 服务器端安装（Linux）

上传 VSIX 文件到服务器：

# 使用 scp 上传（在 Windows PowerShell 中）
scp cpptools-linux-x64-1.23.5.vsix user@server:/home/user/

在 Cursor 中安装：

1. 使用 Remote SSH 连接到服务器
2. 在远程 Cursor 中按 Ctrl+Shift+P 打开命令面板
3. 输入 Extensions: Install from VSIX...
4. 选择上传的 cpptools-linux-x64-1.23.5.vsix 文件
5. 等待安装完成
6. 重启 Cursor

禁用自动更新：

1. 打开扩展面板（Ctrl+Shift+X）
2. 找到 “C/C++” 扩展
3. 点击扩展右侧的齿轮图标
4. 选择 “Disable Auto Update”

3.4 配置设置

确保 .vscode/settings.json 中包含以下配置：

{
    "editor.inlineHints.enabled": true,
    "editor.inlineSuggest.enabled": true,
    "editor.parameterHints.enabled": true,
    "C_Cpp.intelliSenseEngine": "default",
    "C_Cpp.autocomplete": "default",
    "C_Cpp.suggestSnippets": true
}

3.5 验证安装

检查扩展版本：

1. 打开扩展面板（Ctrl+Shift+X）
2. 搜索 “C/C++”
3. 查看版本号，应该是 1.23.5

测试内联提示：

1. 打开一个 C/C++ 文件
2. 调用函数时，应该能看到参数名称提示
3. 悬停在变量上，应该能看到类型信息

---

注意事项

安全注意事项

1. 最小权限原则：sudoers 配置只允许执行 /usr/bin/gdb，不要使用 ALL=(ALL) NOPASSWD: ALL
2. 文件权限：gdb 脚本使用 755 权限即可，不要使用 777
3. 脚本内容：确保 gdb 脚本内容正确，不要被恶意修改

Cursor 扩展注意事项

1. 不要更新扩展：v1.23.5 之后的版本在 Cursor 中不被支持
2. 禁用自动更新：必须禁用，否则会自动更新到不兼容版本
3. 版本匹配：服务器端和客户端都必须是 v1.23.5
4. 架构匹配：确保下载的版本与系统架构匹配（x64 或 arm64）

---

完成

配置完成后，你就可以：

• ✅ 在 VSCode/Cursor 中通过 Remote SSH 连接 Linux 服务器
• ✅ 像在本地一样调试代码（设置断点、查看变量、单步调试等）
• ✅ 调试需要 root 权限的程序（如 DPDK 应用）
• ✅ 在 Cursor 中享受完整的 C/C++ 内联提示功能

所有调试功能都正常工作，包括运行时添加断点、暂停程序、查看变量和调用栈等。