HangChen.com

前言#

本文基于香港科技大学ENTERPRIZE战队的电控开发环境《Environment Setup WinOS》。

MSYS2：Windows 平台下的类 Unix 环境，提供 make 与 Shell 终端
GCC ARM-None-Eabi：ARM 官方交叉编译器，编译裸机固件
SEGGER Ozone + J-Link：烧录与在线调试工具

整套方案适用于所有 ARM Cortex-M 内核的 STM32 项目（F0/F1/F3/F4/F7/H7/L 等全系列），尤其适合 Makefile 构建的工程，支持高度定制化编译与调试。

一、工具链总览#

组件	作用
Visual Studio Code	代码编辑、终端集成、插件扩展
MSYS2	提供 Bash 终端、`make` 构建工具、包管理器
mingw-w64-arm-none-eabi-toolchain	ARM 裸机交叉编译器，将 C/C++ 编译为 STM32 可执行固件
J-Link Driver	J-Link 调试器 Windows 驱动
Ozone	SEGGER 官方调试软件，负责固件烧录、断点调试、寄存器查看
STM32CubeMX（可选）	STM32 引脚与外设图形化配置，生成初始化代码

二、基础环境安装#

1. 安装 VS Code#

前往 VS Code 官网下载安装包并安装；
可选：在插件市场搜索 Chinese (Simplified) 安装中文语言包；
推荐安装插件：C/C++ Extension Pack、Material Icon Theme。

已安装则跳过，确保能正常打开工程目录即可。

2. 安装 MSYS2 与 ARM 编译工具链#

MSYS2 是 Windows 下的类 Linux 环境，我们通过它安装 make 和 ARM 交叉编译器。

前往 MSYS2 官网下载安装包
打开 MSYS2 MSYS 终端，先更新包管理器：

1
pacman -Suy

安装构建工具与 ARM 裸机编译工具链：

1
pacman -S make mingw-w64-x86_64-toolchain mingw-w64-x86_64-arm-none-eabi-toolchain

安装过程中提示选择包时，直接回车默认全部安装即可。

3. 配置系统环境变量#

将 MSYS2 的可执行文件路径加入系统 Path，让 Windows 全局可识别 make、arm-none-eabi-gcc 等命令。

Windows 搜索「编辑系统环境变量」并打开；
点击「环境变量」，在系统变量中找到 Path，点击「编辑」；
新建两条路径（根据你的 MSYS2 实际安装目录修改）：

1
C:\msys64\mingw64\bin
2
C:\msys64\usr\bin

全部确定保存，重启终端生效。

验证：打开 cmd 输入 make -v 和 arm-none-eabi-gcc -v，输出版本信息即配置成功。

三、调试烧录工具安装#

1. 安装 J-Link 驱动#

前往 SEGGER 官网下载 J-Link Software and Documentation Pack；
安装完成后，将 J-Link 连接电脑，打开「设备管理器」；
正常情况下会出现 SEGGER J-Link 设备，若显示黄色感叹号或未知设备，需重新安装驱动。

2. 安装 Ozone 调试软件#

Ozone 是 SEGGER 推出的专门用于嵌入式调试的软件，界面简洁、调试功能强大，完美支持 J-Link。

同样在 SEGGER 官网下载 Ozone 安装包并安装；
首次打开可选择界面主题，后续新建工程即可使用。

3. STM32CubeMX（可选）#

用于图形化配置 STM32 引脚、时钟、外设，生成 HAL 库初始化代码。可直接从 ST 官网下载，本文不赘述安装步骤。

四、VS Code 集成 MSYS2 终端#

默认 VS Code 终端是 PowerShell/cmd，我们需要把 MSYS2 Bash 终端集成进来，直接在 VS Code 里编译工程。

在 VS Code 中按 Ctrl + Shift + P，输入并选择：

1
Preferences: Open Settings (JSON)

在配置中加入以下终端配置（注意 path 路径替换为你本机 MSYS2 的 bash.exe 实际路径）：

1
{
2
    "terminal.integrated.profiles.windows": {
3
        "MSYS2 MINGW64": {
4
            "path": "C:/msys64/usr/bin/bash.exe",
5
            "args": [
6
                "-login"
7
            ],
8
            "env": {
9
                "MSYSTEM": "MINGW64",
10
                "CHERE_INVOKING": "1",
11
                "MSYS2_PATH_TYPE": "inherit"
12
            },
13
            "icon": "terminal-bash"
14
        }
15
    },
16
    "terminal.integrated.defaultProfile.windows": "MSYS2 MINGW64"
17
}

保存后，按 Ctrl + Shift + P 执行 Developer: Reload Window 重启 VS Code；
按下 Ctrl + \`` 打开终端，下拉列表中出现 MSYS2 MINGW64` 即配置成功。

五、Makefile 工程编译配置（核心）#

STM32 属于无操作系统的裸机环境，直接使用标准 C++ 库会报错（freestanding mode 错误），需要在 Makefile 中配置裸机编译参数。

关键编译参数说明#

在你的 Makefile 中，找到 CPPFLAGS（C++ 编译选项）部分，

添加或修改为以下内容：

1
# C++ 编译选项（裸机环境配置）
2
CPPFLAGS = $(C_DEFS) $(C_INCLUDES) $(CPPSTD) $(COMPILERFLAGS)
3
CPPFLAGS += -fno-exceptions             # 禁用 C++ 异常（裸机无操作系统支持）
4
CPPFLAGS += -fno-rtti                    # 禁用运行时类型信息（减少固件体积）
5
CPPFLAGS += -fno-threadsafe-statics     # 禁用线程安全静态变量初始化
6
CPPFLAGS += -nostdinc++                  # 不包含 C++ 标准库头文件
7
CPPFLAGS += -nostdlib++                  # 不链接 C++ 标准库
8
CPPFLAGS += -D_GLIBCXX_HOSTED            # GCC 13+ 兼容：允许 freestanding 模式使用部分头文件

为什么要这么配置？#

嵌入式裸机没有操作系统，无法支持完整 C++ 标准库（依赖系统调用）；
异常、RTTI 会大幅增加固件体积和运行开销，嵌入式开发通常禁用；
-nostdinc++ + -D_GLIBCXX_HOSTED 组合是 GCC 高版本解决 freestanding mode 头文件报错的标准方案。

六、工程编译与构建#

1. 打开工程#

在 VS Code 中打开你的 STM32 工程根目录（Makefile 所在目录）。

2. 切换终端目录#

打开 MSYS2 终端，使用 cd 命令进入 Makefile 所在目录，例如：

1
cd /c/Projects/STM32_Project

3. 执行编译#

直接输入 make 开始编译：

1
make

若工程需要传入自定义宏（如硬件版本、型号选择），可通过参数传入：

1
make -j HARDWARE_VERSION=V102

-j：开启多线程编译，提升速度
HARDWARE_VERSION=V102：向代码传入自定义宏，根据你的项目需求修改

4. 编译产物#

编译成功后，会在工程 build 目录下生成 .elf、.hex、.bin 固件文件，其中 .elf 用于后续 Ozone 调试烧录。

七、Ozone 烧录与在线调试#

1. 硬件连接#

用 J-Link 调试器连接 STM32 板卡的 SWD/JTAG 调试接口，接通板卡电源。

2. 新建 Ozone 工程#

打开 Ozone，点击「New Project」；
选择你的 STM32 芯片型号（如 STM32F334C8、STM32F407IG 等）；
下载对应芯片的 .svd 外设描述文件（可从 ST 官网获取，Ozone 也会自动匹配下载）；
在「Peripherals」选项中加载 .svd 文件，用于调试时查看外设寄存器。

3. 加载固件#

在工程设置中，选择编译生成的 .elf 文件路径：

1
工程目录/build/目标文件名.elf

4. 烧录与调试#

点击 Ozone 左上角绿色下载按钮，即可将固件烧录到 STM32 中；烧录完成后可设置断点、单步运行、查看寄存器与变量，调试体验与商业 IDE 一致。

八、常见问题排错#

1. VS Code 不显示 MSYS2 终端#

检查 settings.json 中 path 路径是否正确，注意使用正斜杠 /；
执行 Developer: Reload Window 重启 VS Code；
确认 MSYS2 安装目录下存在 usr/bin/bash.exe。

2. 编译报错：`This header is not available in freestanding mode`#

原因：裸机环境引用了 C++ 标准库头文件；
解决：确保 Makefile 中添加了 -nostdinc++ 和 -D_GLIBCXX_HOSTED 参数。

3. `make` 命令不是内部或外部命令#

原因：系统环境变量 Path 配置错误；
解决：检查 C:\msys64\usr\bin 是否已加入系统 Path，配置后重启终端。

4. J-Link 设备管理器显示黄色感叹号#

重新安装 J-Link 驱动；
更换 USB 接口，优先使用 USB 3.0 以下接口；
检查 J-Link 固件是否需要更新。

5. Ozone 无法识别芯片#

检查硬件连接、板卡是否上电；
确认芯片型号选择正确；
降低 JTAG/SWD 通信速率。

写在最后#

感谢香港科技大学ENTERPRIZE战队在开源社区做出的贡献！

参考： [1] 《Environment Setup WinOS》

如果文章对你有帮助，欢迎在评论区交流讨论。

前言#