在 VSCode 上如何修改 json 配置文件，从而构建调试 C/C++ 项目

本文介绍如何通过更改配置文件，从而在 VSCode 上构建调试 C/C++ 项目。

能够解决的一些问题：头文件未包含而导致的未定义；头文件未能被识别而显示的提示错误等问题。

一、基本设置

• vscode 上调试构建 c/cpp 项目都是基于这个拓展包，首先在拓展中搜索下载。

• ctrl + shift + p 搜索 C/C++: Edit Configurations，选择 UI 界面，这里可以修改基本配置，比如编译器位置，智能提示相关设置，包含路径等等。也可以选择 C/C++: Edit Configurations (JSON) 修改。

• 特别要注意的是智能提示的 c/c++ 标准，如果用到的新特性提示报错，可以在这里修改。

c/cpp 构建调试 主要 是通过以下的几个文件配置，一般位于 .vscode/ 文件夹中。

可选中ctrl + shift + p 搜索 C/C++:Add Debug Configuration 生成一个简单的基本框架，后续再修改关键项。

二、配置文件

文件名	主要功能
c_cpp_properties.json	配置C/C++编译环境，提供智能提示（IntelliSense）所需的头文件路径、编译器信息等。
launch.json	配置调试器参数，如程序入口、断点设置、环境变量等，用于启动调试会话。
settings.json	定制项目级的编辑器行为（如缩进、文件编码），覆盖全局设置。
tasks.json	定义自动化任务（如编译、测试），将复杂命令封装为可执行的任务。

由于可设置项太多，这里用 * + 数字 (如 ** 1.) 标注了需要着重注意的部分，修改这些就能完成大多数简单项目的配置。*

1. tasks.json（自动化任务）

• 作用：控制项目的构建，替代了手动输入命令。
• 快捷键 Ctrl+Shift+B 。
• 修改点：
  • 1. “-I”, “${workspaceFolder}”, -I包含的头文件的目录（.h）
    2. -l链接的目录，如有需要链接第三方的库，需要在这里链接
    3. -o 输出可执行文件名

{
    "tasks": [
        {
            "type": "cppbuild",
            "label": "C/C++: g++ build active file",
            "command": "/usr/bin/g++",
            "args": [
                "-fdiagnostics-color=always",
                "-g",
                "*.cpp",
                "*.cc",
                "-I", "${workspaceFolder}",			// **1. -I包含的头文件的目录（.h）
               	"-I", "${workspaceFolder}/include",	// {workspaceFolder}为当前工作目录，一般为项目根目录
                "-std=c++20", // 编译标准，可指定
                //"-labsl",
                "-lprotobuf",						// **2. -l链接的目录，如有需要链接第三方的库，需要在这里链接
                "-lpthread",
                "-lssl",
                "-lcrypto",
                "-o", "${workspaceFolder}/test"		// **3. -o 输出可执行文件名
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "detail": "Task generated by Debugger."
        }
    ],
    "version": "2.0.0"
}

2. launch.json（调试配置）

• 作用：控制项目的启动（调试）
• 快捷键 F5，一般启动前要执行任务 "preLaunchTask"这一项 都默认设置为 上面提到的 tasks.json 中的 "label" （一般名为"C/C++: g++ build active file" ），故启动调试前都会先通过 tasks.json 构建项目。
• 修改点：
  • 1. “program”, 调试的目标可执行文件
    2. “args”，传递参数

{
    "configurations": [
        {
            "name": "C/C++: g++ build and debug active file",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/test",		// **1.调试的目标可执行文件			
            "args": [],									// **2.传递参数，如果有则是 [arg1", "arg2"] 形式
            "stopAtEntry": false,						
            "cwd": "${fileDirname}", // 程序运行时的工作目录
            			// ${fileDirname} 为当前文件所在目录 区别于工作目录，一般是${fileDirname}/.vscode/
            "environment": [],// 环境变量配置
            "externalConsole": false,
            "MIMode": "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
                }
            ],
            "preLaunchTask": "C/C++: g++ build active file",
            "miDebuggerPath": "/usr/bin/gdb" // gdb 可执行文件路径			
        }
    ],
    "version": "2.0.0"
}

3. c_cpp_properties.json（C/C++ 环境配置）

• 作用：这个文件是为了为了让 VSCode 理解项目结构，提供准确的错误检查和代码补全。
• 有时候项目会用到第三方库，VSCode 有时会找不到头文件包含的 include 目录，会报未定义的错误。这时候只需更改这个文件即可
• 修改点：
  • 1. "includePath"，智能提示的头文件包含路径

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**", // **1. 头文件包含路径，/** 有递归的效果，这里就设置成当前工作目录下（包括子目录）
                "/usr/local/include/google/protobuf/" // 可以指定所用库更具体的位置
                // "/usr/include/**", 		// Linux 常用位置
                // "/usr/local/include/**", // Linux 常用位置
            ],
            "defines": [],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c23",
            "cppStandard": "gnu++23",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

4. settings.json（项目设置）

• 作用：确保项目使用统一的代码风格，一般自动生成不用修改。

{
    "editor.tabSize": 2, // 缩进空格数
    "files.encoding": "utf8", // 文件编码
    "editor.formatOnSave": true, // 保存时自动格式化
    
    "files.associations": { // 文件关联，用于告诉编辑器如何识别特殊文件类型
        // C++ 标准库头文件关联,自动生成
        "cctype": "cpp",
        "clocale": "cpp",
        "cmath": "cpp",
        // ... 
        // 自定义文件扩展名关联
        "*.hpp": "cpp",   
        "*.cc": "cpp",    
        "*.inc": "cpp"   
    }
}

配置好这些文件，就可以按 F5 构建调试你的项目了。

通过以上配置，你可以在 VSCode 中高效地构建和调试 C/C++ 项目，解决标识符未定义、头文件找不到、智能提示错误等常见问题。