写在前头

上一篇讲了怎么用 GCC/Makefile/OpenOCD 在命令行编译、烧录 STM32。跑起来了，但 VS Code 打开依然满屏红线，#include 找不到文件，HAL_GPIO_WritePin 点不进去。这篇把 IntelliSense 配好，把编辑体验拉回来。

用 STM32CubeMX 生成的 Makefile 工程，第一次用 VS Code 打开，满屏红线。#include "stm32f1xx_hal.h" 报找不到，HAL_GPIO_WritePin 点不进去，写完代码全靠猜，写了也不知道对错。

本文从零开始，教你给这类工程配好 C/C++ IntelliSense，让 VS Code 真正看懂你的嵌入式 C 代码。

---

一、安装 C/C++ 扩展

打开 VS Code，按 Ctrl+Shift+X 进入扩展商店，搜索 C/C++，安装微软官方的 C/C++ extension pack（发布者 ms-vscode）。

这个扩展提供了 IntelliSense（代码补全、跳转、语法检查）、调试、代码浏览三大功能。本文只讲 IntelliSense 部分。

---

二、了解你的 Makefile

IntelliSense 要正常工作，需要知道三样信息：

1. 头文件在哪里搜索    → Makefile 的 C_INCLUDES
2. 预定义了哪些宏      → Makefile 的 C_DEFS
3. 用的是什么编译器    → Makefile 的 CC

打开项目根目录的 Makefile，找到下面几行（以 STM32F103 + uGUI 工程为例）：

C_INCLUDES =  \
    -ICore/Inc \
    -IDrivers/STM32F1xx_HAL_Driver/Inc \
    -IDrivers/STM32F1xx_HAL_Driver/Inc/Legacy \
    -IDrivers/CMSIS/Device/ST/STM32F1xx/Include \
    -IDrivers/CMSIS/Include \
    -IBSP \
    -IMiddlewares/ugui/inc

C_DEFS =  \
    -DUSE_HAL_DRIVER \
    -DSTM32F103xB

CC = arm-none-eabi-gcc

记下这些值，后面配置全部用这里的信息，不需要猜。

你的 Makefile 里的路径和宏定义可能不同，原理一样：-I 后面是头文件路径，-D 后面是宏定义。

---

三、创建配置文件

在项目根目录创建 .vscode 文件夹，在里面新建三个文件。

3.1 c_cpp_properties.json（核心配置）

这是最关键的文件，告诉 C/C++ Intellisense 你的项目怎么编译。

{
    "configurations": [
        {
            "name": "STM32",
            "includePath": [
                "${workspaceFolder}/Core/Inc",
                "${workspaceFolder}/Drivers/STM32F1xx_HAL_Driver/Inc",
                "${workspaceFolder}/Drivers/STM32F1xx_HAL_Driver/Inc/Legacy",
                "${workspaceFolder}/Drivers/CMSIS/Device/ST/STM32F1xx/Include",
                "${workspaceFolder}/Drivers/CMSIS/Include",
                "${workspaceFolder}/BSP",
                "${workspaceFolder}/Middlewares/ugui/inc"
            ],
            "defines": [
                "USE_HAL_DRIVER",
                "STM32F103xB"
            ],
            "compilerPath": "arm-none-eabi-gcc",
            "cStandard": "c11",
            "intelliSenseMode": "gcc-arm"
        }
    ],
    "version": 4
}

逐字段说明：

includePath
对应 Makefile 的 C_INCLUDES。把所有 -I 后面的路径抄进来，去掉 -I 前缀，前面加上 ${workspaceFolder}/。${workspaceFolder} 是 VS Code 内置变量，会自动替换成你项目的绝对路径。

一定不要漏。漏一个路径，那个目录下的头文件就找不到，依赖它的所有代码都会报红。最稳妥的做法：把 Makefile 里 C_INCLUDES 的每个 -I 路径都抄进来，不做删减。

defines
对应 Makefile 的 C_DEFS。把所有 -D 后面的宏定义抄进来，去掉 -D 前缀，用双引号包裹。

这些宏决定了 HAL 库和 CMSIS 里的条件编译。比如 USE_HAL_DRIVER 没定义，大段 HAL 库代码对 IntelliSense 就是不可见的，结果就是跳转失败、补全为空。务必全部抄完整。

compilerPath
编译器路径。如果工具链在系统 PATH 中，直接写 arm-none-eabi-gcc。如果没加 PATH，写完整路径：

"compilerPath": "D:/arm-gnu-toolchain/bin/arm-none-eabi-gcc.exe"

不需要用斜杠还是反斜杠纠结，VS Code 两种都支持。建议加 PATH，这样配置文件里只写 arm-none-eabi-gcc，换电脑不需要改配置。

这个字段的作用：IntelliSense 会调用这个编译器来解析代码中的内置宏和特性检测，从而正确理解 __attribute__、__packed 这类嵌入式 C 特有语法。

cStandard
C 语言标准。STM32 工程通常用 c11。如果拿不准，去 Makefile 里找有没有 -std=c11 或 -std=gnu11 之类的编译选项，保持一致即可。

intelliSenseMode
选 gcc-arm。这个选项告诉 IntelliSense 引擎适配 ARM 交叉编译器的语法特性。选错了可能导致某些嵌入式特有语法被标红。

3.2 settings.json（引擎选择）

{
    "C_Cpp.intelliSenseEngine": "default",
    "C_Cpp.errorSquiggles": "enabled",
    "C_Cpp.autocomplete": "default"
}

三个字段各管各的：

C_Cpp.intelliSenseEngine
选 default 还是 "Tag Parser" 取决于你的需求。

• default：基于语义分析。能正确解析 typedef、宏展开、模板。跳转准确率高，支持 Find All References。内存占用稍高，但在现代电脑上感觉不到差别。
• "Tag Parser"：基于关键词匹配。把符号当成字符串索引，遇到 typedef struct { ... } UGUI; 再用 UGUI 做类型声明，可能认不出。不推荐，除非你的项目在老旧电脑上 default 引擎太卡。

C_Cpp.errorSquiggles
控制红色波浪线。enabled 全开，disabled 全关，inactive 只在你当前编辑的文件显示。

C_Cpp.autocomplete
补全方式。default 用语义分析补全，推荐。"Tag Parser" 用关键词匹配补全。

3.3 extensions.json（可选）

{
    "recommendations": [
        "ms-vscode.cpptools"
    ]
}

这个文件不是必须的。作用是别人打开你的项目时，VS Code 会弹窗提醒他安装推荐的扩展。如果你要把项目分享出去，加上这个文件可以省去队友配置环境的时间。

---

四、验证结果

配好之后，在 VS Code 里随便打开一个源文件（比如 Core/Src/main.c），检查以下四点：

1. #include 行不再有红色波浪线
2. 鼠标悬停在 HAL_GPIO_WritePin 上，能看到函数签名和参数说明
3. 按住 Ctrl 点击函数名，能跳转到定义
4. 输入 HAL_ 会自动弹出补全列表，列出所有以 HAL 开头的函数和宏

第一条是最直观的验证。如果 #include 不报红了，说明 includePath 和 defines 配对了。

---

五、配置常见问题

所有 #include 都报错，怎么回事？

includePath 写错了。检查你是不是漏了 Makefile 里的某个 -I 路径，或者路径前缀写成了 ${workspaceFolder} 以外的值。

HAL 函数能跳转，但自己写的函数不能？

IntelliSense 需要先索引你的源文件。确保源文件在 c_cpp_properties.json 的 browse.path 范围内。如果不加 browse.path，默认搜索整个 workspace，一般够用。

宏定义相关的代码变灰或报红

defines 里漏了某个宏。常见遗漏：USE_HAL_DRIVER（HAL 库开关）、STM32F103xB（芯片型号，决定寄存器地址和中断号）。打开 Makefile 逐行检查。

改了配置文件没生效？

Ctrl+Shift+P → Developer: Reload Window。VS Code 可能没有自动检测 c_cpp_properties.json 的改动，需要重载窗口。

还是搞不定？

Ctrl+Shift+P → C/C++: Log Diagnostics。输出面板会显示 IntelliSense 当前的编译器路径、include 搜索路径、预定义宏。检查里面的值跟你 Makefile 是不是一致，缺什么补什么。

---

结语

配置 IntelliSense 这件事，说大不大——三个文件，十几行配置，做完就完了。说小也不小——没有这十几行，VS Code 就是个带高亮的文本编辑器，写代码全靠脑补。

回过头看，问题的根源在于：Makefile 这个构建系统太"原始"了，它不会主动把编译信息告诉编辑器。不像 CMake 会生成 compile_commands.json，CubeMX 只管扔给你一个 Makefile，剩下的你自己搞定。理解了这一点，你就能举一反三——任何 Makefile 工程，不管用什么芯片、什么外设库，配 IntelliSense 的方法都是一样的：从 Makefile 里找到 C_INCLUDES 和 C_DEFS，抄到 c_cpp_properties.json 里。

上一篇讲的是脱离 IDE 来编译和烧录，这篇讲的是把编辑器的体验拉回来。两个结合起来，你得到了一个既有命令行的高效，又不牺牲代码导航和补全的开发环境。值得花这十分钟。