PY32F403 开发环境搭建与调试配置完整笔记（小白友好版）

📖 一句话总结（先看这里，明白你在做什么）

目标：在 Windows 11 上用 VS Code 实现 PY32F403 单片机的一键编译、烧录、调试。

核心思路：
编译：用 MSYS2 提供 make 命令，配合 ARM GCC 编译工程
烧录：用 PyOCD 通过 ST-Link V2 把固件写入芯片
调试：用 arm-none-eabi-gdb 作为客户端，PyOCD 作为 GDB Server，实现断点调试

本文档记录的是 ARM GCC + Makefile + PyOCD + GDB + MSYS2 + VS Code 这套开源工具链的完整搭建流程。这套工具链的核心价值是"一次学习，到处通用"——换 MCU、换 IDE 都不用从头再来。所有环境已在 Windows 11 64位系统上验证通过。

📖 文档说明

适用系统：Windows 11 64位
已验证工具：Python 3.13.14、PyOCD 0.44.1、ST-Link V2、PY32F403C1DT6、MSYS2、ARM GCC 14.3.Rel1
最终目标：在 VS Code 中按 Ctrl+Shift+B 一键编译，按 F5 一键调试
网络要求：部分步骤需联网，建议全程保持 VPN 连接以加速下载
本文约定：
- 作者的 MSYS2 安装路径为 D:\msys64（读者请根据实际安装位置替换）
- 作者的 arm-none-eabi-gdb.exe 路径为 F:\Microsoft VS Code\gnu-toolchain\bin\arm-none-eabi-gdb.exe（读者请根据实际安装位置替换）

🗺️ 完整执行路线图

第一步：基础环境准备
    ├── 1.2 安装 Python
    ├── 1.3 安装 ST-Link 驱动
    └── 1.4 验证驱动

第二步：PyOCD 烧录环境
    ├── 2.1 安装 PyOCD
    ├── 2.2 安装 PY32F403 芯片支持
    └── 2.3 验证芯片识别

第三步：MSYS2 工具链安装
    ├── 3.2 安装 MSYS2
    ├── 3.3 更新系统
    ├── 3.4 安装 make 和工具链
    ├── 3.5 配置 Windows 环境变量
    ├── 3.6 验证 make
    ├── 3.7 设置终端中文界面
    └── 3.8 设置 Ctrl+Shift+C/V 快捷键

第四步：ARM 调试工具链（GDB）
    ├── 4.1 什么是 arm-none-eabi-gdb
    ├── 4.2 安装方式
    ├── 4.3 确认安装
    └── 4.4 让 MSYS2 终端识别它

第五步：VS Code 一键调试配置
    ├── 5.1 安装插件
    ├── 5.2 项目结构说明
    ├── 5.3 编写 tasks.json
    ├── 5.4 编写 launch.json
    ├── 5.5 编写 c_cpp_properties.json（可选）
    └── 5.6 编写 settings.json（可选）

第六步：一键编译与手动烧录
    ├── 6.1 编译（Ctrl+Shift+B）
    ├── 6.2 手动烧录（备用方式）
    └── 6.3 一键调试（F5）

第七步：核心坑点解决（小白必看！）
    ├── 7.1 路径空格问题
    └── 7.2 工具链 PATH 问题

第八步：常见问题

附录 A：关键路径速查表（作者实际路径）
附录 B：MSYS2 终端选择指南
附录 C：在 VS Code 中用命令行进行 GDB 调试
附录 D：安装完成后的验证清单

第一部分：基础环境准备

1.1 下载所需文件

文件	说明	下载来源
`python-3.13.14-amd64.exe`	Python 安装包	Python 官网
`stsw-link009.zip`	ST-Link 驱动	ST 官网
`msys2-x86_64-*.exe`	MSYS2 安装包	MSYS2 官网

1.2 安装 Python 环境

双击 python-3.13.14-amd64.exe 运行安装。
务必勾选 Add Python to PATH（这一步非常重要，否则后续命令找不到 Python）。
选择 Install Now 完成安装。
打开命令提示符（CMD），验证安装：

cmd

python --version
pip --version

应显示 Python 3.13.14 和 pip 版本信息。

1.3 安装 ST-Link V2 驱动

解压 stsw-link009.zip。
运行其中的 dpinst_amd64.exe（64位系统选这个，32位选 dpinst_x86.exe）。
按提示完成安装（一路"下一步"即可）。
插入 ST-Link V2 调试器。
打开设备管理器（右键"此电脑"→"管理"→"设备管理器"），确认在"通用串行总线设备"或"端口"下出现 STM32 ST-Link。如果没有，说明驱动没装好，重试步骤 1-3。

第二部分：PyOCD 烧录环境

2.1 安装 PyOCD

打开 CMD 或 PowerShell，使用清华镜像源加速安装：

cmd

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -U pyocd

验证安装：

cmd

pyocd --version

应显示版本号（如 0.44.1）。

2.2 检查 ST-Link 是否被识别

插上 ST-Link 调试器，执行：

cmd

pyocd list

应输出类似：

  #   Probe/Board    Unique ID                  Target
--------------------------------------------------------
  0   STM32 STLink   1B000B13A118303030303032   n/a

2.3 安装 PY32F403 芯片支持（关键步骤）

PyOCD 需要通过 CMSIS-Pack 识别 PY32F403 芯片，执行：

cmd

pyocd pack install PY32F403xC

该命令会自动下载并安装 Puya.PY32F4xx_DFP.1.0.3。

验证是否成功：

cmd

pyocd list --targets | findstr py32

应能看到 py32f403xc 条目，且 Installed 状态为 True。

第三部分：MSYS2 工具链安装

3.1 为什么需要 MSYS2？

Windows 没有原生的 make 命令（Linux 里用来编译程序的工具）。
MSYS2 提供了一个"小 Linux 环境"，让读者在 Windows 上也能用 make 和其他 Linux 工具。
简单理解：MSYS2 就是在 Windows 里装一个"工具箱"，里面放着 make、gcc、gdb 等开发工具。

3.2 安装 MSYS2

从 MSYS2 官网下载安装程序（msys2-x86_64-*.exe）。
双击运行，建议安装到 C:\msys64（路径不要有空格和中文，比如不要装到 C:\Program Files 下）。
作者实际安装到了 D:\msys64，同样可行（读者后续配置路径时请留意这个差异）。
安装完成后，点击"完成"退出安装程序。

3.3 更新 MSYS2 系统

从开始菜单找到并打开 MSYS2 MSYS（注意是 MSYS，不是 UCRT64）。
在终端中输入以下命令并回车：

bash

pacman -Syu

如果提示关闭终端，就关掉窗口，再从开始菜单重新打开 MSYS2 MSYS，然后再次执行 pacman -Syu 完成更新。
此过程可能需要较长时间（取决于网速），建议保持 VPN 连接。

3.4 安装 make 和 GCC 工具链

在 MSYS2 MSYS 终端中执行：

bash

pacman -S --needed base-devel mingw-w64-x86_64-toolchain

安装过程中会弹出一个软件包列表（共 13 个），直接按回车键（默认全部安装）。
总下载约 137 MB，安装后约占用 945 MB 硬盘空间，需耐心等待。
如果中途网络中断，重新执行一次命令即可，pacman 会继续下载未完成的包。

3.5 配置 Windows 系统环境变量（非常重要！）

这一步是为了让 VS Code 和 CMD 都能找到 make 命令。

右键点击"此电脑"→"属性"→"高级系统设置"→"环境变量"。
在"系统变量"区域找到 Path，双击打开编辑窗口。
点击"新建"，添加以下路径（根据读者的实际安装位置选择）：
- 如果装在了 C:\msys64：添加 C:\msys64\usr\bin
- 如果装在了 D:\msys64（作者的路径）：添加 D:\msys64\usr\bin
（推荐） 再新建一条，添加 C:\msys64\mingw64\bin（或 D:\msys64\mingw64\bin）。
一路点击"确定"保存所有窗口。

3.6 验证 make 是否安装成功

重新打开一个 CMD 或 PowerShell 窗口（不是 MSYS2 终端），输入：

cmd

make --version

如果显示 GNU Make 4.4.1 等版本信息，说明安装成功！

3.7 配置 MSYS2 终端：显示中文界面

打开 MSYS2 UCRT64 终端（从开始菜单）。
在终端标题栏上右键单击，选择 Options...（选项）。
在左侧菜单点击 Text（文本）。
在右侧找到 Locale（区域），下拉选择 zh_CN。
在 Character set（字符集）下拉选择 UTF-8。
点击 Save 保存，然后完全关闭终端再重新打开。

3.8 配置 MSYS2 终端：启用 Ctrl+Shift+C 复制 / Ctrl+Shift+V 粘贴

在终端标题栏右键 → Options...。
左侧点击 Keys（键盘）。
右侧找到 Ctrl+Shift shortcuts，勾选它。
点击 Save 保存。

设置后，可以使用 Ctrl+Shift+C 复制，Ctrl+Shift+V 粘贴。

第四部分：ARM 调试工具链（arm-none-eabi-gdb）

4.1 这个工具是干什么的？

arm-none-eabi-gdb 是 ARM 单片机专用的调试器。
电脑是 x86 架构，而 PY32 芯片是 ARM 架构。arm-none-eabi-gdb 负责在 x86 电脑上调试 ARM 芯片里的程序。
简单理解：它是"翻译官"，把调试命令翻译成 ARM 芯片能听懂的语言。

4.2 怎么安装？（作者实际使用的方式）

从 ARM 官网下载独立安装包：

访问 Arm GNU Toolchain 下载页面。
找到 Windows 版本，下载 arm-gnu-toolchain-*-mingw-w64-i686-arm-none-eabi.zip（约 100-200 MB）。
解压到想要的目录（作者的路径：F:\Microsoft VS Code\gnu-toolchain\）。
将解压后的 bin 文件夹路径添加到 Windows 系统环境变量 Path 中（参考 3.5 节）。

4.3 确认 arm-none-eabi-gdb 已安装

在 CMD 或 PowerShell 中执行：

cmd

where arm-none-eabi-gdb

如果显示路径，说明已安装且 PATH 配置正确。

4.4 让 MSYS2 终端也能找到 arm-none-eabi-gdb

在 MSYS2 UCRT64 终端中执行（注意将路径改为读者的实际位置）：

bash

echo 'export PATH="/f/Microsoft VS Code/gnu-toolchain/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

路径转换规则：
Windows 路径 F:\Microsoft VS Code\gnu-toolchain\bin
MSYS2 路径 /f/Microsoft VS Code/gnu-toolchain/bin
规则：盘符用小写，反斜杠 \ 改成正斜杠 /

然后验证：

bash

arm-none-eabi-gdb --version

应显示 GNU gdb (Arm GNU Toolchain 14.3.Rel1)。

第五部分：VS Code 一键调试配置（F5 自动化）

这是本文档的最终目标：在 VS Code 中按 F5 完成一键调试。但调试在底层依赖 GDB 命令，如果读者在按 F5 遇到问题时，附录 C 提供了完整的命令行调试流程用于排查。

5.1 安装 VS Code 插件

打开 VS Code，点击左侧扩展图标（或按 Ctrl+Shift+X），搜索并安装以下插件：

插件名称	作用
C/C++（微软官方）	提供代码语法高亮和基础调试接口
Cortex-Debug	专门对接 PyOCD 和 GDB，实现单片机调试
Makefile Tools（可选）	让 VS Code 识别 Makefile 的报错信息

安装后重启 VS Code。

5.2 项目结构说明

作者提醒：读者的项目根目录就是 PY32F403_EPD_ST7305 文件夹，VSCode 直接打开这个文件夹即可。Makefile 在根目录，编译输出在 build/ 目录。

PY32F403_EPD_ST7305/                          ← VSCode 工作区根目录（Makefile 所在目录）
├── .vscode/                                  ← VSCode 配置目录
│   ├── tasks.json                            ← 编译任务 (Ctrl+Shift+B)
│   ├── launch.json                           ← 调试配置 (F5)
│   ├── settings.json                         ← 编辑器设置
│   └── c_cpp_properties.json                 ← 头文件路径配置
├── app/                                      ← 应用源码目录
│   ├── main.c                                ← 主程序
│   ├── bsp/                                  ← 板级支持包（GPIO、SPI、延时等）
│   └── dev/                                  ← 设备驱动（屏幕、字体等）
├── build/                                    ← 编译输出目录
│   ├── firmware.elf                          ← ELF 文件（调试用）
│   ├── firmware.hex                          ← HEX 文件（烧录用）
│   └── firmware.bin                          ← BIN 文件（烧录用）
├── system/                                   ← 系统文件
│   ├── py32f403xc.ld                         ← 链接脚本（内存布局）
│   ├── startup_py32f403xx_gcc.S              ← 启动文件
│   ├── py32f403_hal_conf.h                   ← HAL 库配置文件
│   └── drivers/                              ← CMSIS 和 HAL 驱动
├── MDK-ARM/                                  ← Keil 工程文件（仅供兼容参考）
├── Makefile                                  ← 编译配置文件
└── README.md                                 ← 项目说明

核心文件说明：
Makefile：控制整个编译过程，读者已修改其中的 BUILD_DIR 和工具链路径
py32f403xc.ld：链接脚本，定义了 Flash 和 RAM 的地址空间
startup_py32f403xx_gcc.S：芯片启动文件，复位后第一个执行的代码
app/main.c：主程序入口，F5 调试时会自动停在 main 函数的第一行

5.3 编写 `.vscode/tasks.json`（编译任务）

在 .vscode 文件夹中创建 tasks.json：

json

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "编译 (Make)",
            "type": "shell",
            "command": "D:/msys64/usr/bin/make.exe",
            "args": ["-j4"],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": ["$gcc"],
            "presentation": {
                "panel": "dedicated",
                "clear": true
            },
            "detail": "编译固件 → build/firmware.elf"
        },
        {
            "label": "清理 (Clean)",
            "type": "shell",
            "command": "D:/msys64/usr/bin/make.exe",
            "args": ["clean"],
            "group": "build",
            "problemMatcher": [],
            "presentation": {
                "panel": "dedicated",
                "clear": true
            },
            "detail": "rm -rf build/"
        },
        {
            "label": "重新编译 (Rebuild)",
            "type": "shell",
            "command": "D:/msys64/usr/bin/make.exe",
            "args": ["clean", "all"],
            "group": "build",
            "problemMatcher": ["$gcc"],
            "presentation": {
                "panel": "dedicated",
                "clear": true
            },
            "detail": "clean → make -j4"
        }
    ]
}

读者需要修改的地方：
command：改成读者 make.exe 的实际路径
作者的是 D:/msys64/usr/bin/make.exe
如果读者装在了 C:\msys64，就改成 C:/msys64/usr/bin/make.exe

5.4 编写 `.vscode/launch.json`（调试配置）

在 .vscode 文件夹中创建 launch.json：

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "PY32 Debug (pyOCD)",
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "pyocd",
            "cwd": "${workspaceRoot}",
            "executable": "${workspaceFolder}/build/firmware.elf",
            "targetId": "py32f403xc",
            "preLaunchTask": "编译 (Make)",
            "gdbPath": "F:/Microsoft VS Code/gnu-toolchain/bin/arm-none-eabi-gdb.exe",
            "runToMain": true,
            "preRestartCommands": [
                "monitor reset halt",
                "load",
                "enable breakpoints"
            ],
            "serverArgs": ["--clock=4000000"],
            "showDevDebugOutput": "parsed"
        }
    ]
}

读者需要修改的地方：
gdbPath：改成读者 arm-none-eabi-gdb.exe 的实际路径
作者的是 F:/Microsoft VS Code/gnu-toolchain/bin/arm-none-eabi-gdb.exe
读者可以用 where arm-none-eabi-gdb 在 CMD 中查到自己电脑上的路径
preLaunchTask：必须和 tasks.json 里的 label 完全一致（"编译 (Make)"）

5.5 编写 `.vscode/c_cpp_properties.json`（头文件路径配置，可选）

此文件告诉 VSCode 的 C/C++ 插件去哪里找头文件，实现代码补全和跳转定义功能。即使不配置此文件，也不影响编译和调试，但会影响代码编辑体验。

在 .vscode 文件夹中创建 c_cpp_properties.json（作者的实际配置）：

json

{
    "configurations": [
        {
            "name": "PY32F403C1DT6",
            "includePath": [
                "${workspaceFolder}/app",
                "${workspaceFolder}/app/bsp",
                "${workspaceFolder}/app/dev",
                "${workspaceFolder}/system",
                "${workspaceFolder}/system/drivers/CMSIS/Include",
                "${workspaceFolder}/system/drivers/CMSIS/Device/PUYA/PY32F403/Include",
                "${workspaceFolder}/system/drivers/PY32F403_HAL_Driver/Inc"
            ],
            "defines": [
                "USE_HAL_DRIVER",
                "PY32F403xC",
                "__CORTEX_M4",
                "ARM_MATH_CM4"
            ],
            "compilerPath": "arm-none-eabi-gcc",
            "cStandard": "c99",
            "intelliSenseMode": "gcc-arm",
            "browse": {
                "limitSymbolsToIncludedHeaders": false,
                "path": [
                    "${workspaceFolder}/app",
                    "${workspaceFolder}/system"
                ]
            }
        }
    ],
    "version": 4
}

5.6 编写 `.vscode/settings.json`（编辑器设置，可选）

此文件控制 VSCode 编辑器的行为，不影响编译和调试，只影响编辑体验。

在 .vscode 文件夹中创建 settings.json（作者的实际配置）：

json

{
    "files.associations": {
        "*.c": "c",
        "*.h": "c"
    },
    "C_Cpp.intelliSenseEngine": "default",
    "editor.formatOnSave": false,
    "cortex-debug.variableUseNaturalFormat": false,
    "cortex-debug.armToolchainPath": ""
}

第六部分：一键编译与手动烧录

6.1 编译（Ctrl+Shift+B）

配置好 tasks.json 后，按 Ctrl+Shift+B，VSCode 自动执行 make -j4。

编译成功后，输出文件在 build/ 目录下：

build/firmware.elf — 调试用
build/firmware.hex — 烧录用
build/firmware.bin — 烧录用

6.2 手动烧录（备用方式）

如果只想烧录不想调试，在 VS Code 终端中执行：

cmd

pyocd flash -t py32f403xc --erase chip "build/firmware.hex"

作者的实际输出（成功示例）：

PS D:\...\PY32F403_EPD_ST7305> pyocd flash -t py32f403xc --erase chip "build/firmware.hex"
0000747 I Loading D:\...\PY32F403_EPD_ST7305\build\firmware.hex [load_cmd]
0000751 I Erasing... [loader]
[==================================================] 100%
0000822 I Programming... [loader]
[==================================================] 100%
0001869 I Erased chip, programmed 8960 bytes (35 pages) at 7.83 kB/s [loader]

看到 Erased chip, programmed XXXX bytes 即表示烧录成功。

6.3 一键调试（F5）

用 USB 线连接 ST-Link V2 和开发板，插到电脑上。
在 VS Code 中打开 app/main.c，在想要暂停的行号左侧点击，出现红点（断点）。
按 F5。
系统会自动执行：
- ① 执行 preLaunchTask 指定的编译任务（编译 (Make)）
- ② 自动启动 PyOCD 作为 GDB 服务器
- ③ 自动执行 preRestartCommands：复位 → 烧录 → 使能断点
- ④ 自动停在 main 函数的第一行
- ⑤ 读者可以自由打断点、单步执行（F10/F11）、查看变量

第七部分：核心坑点解决（小白必看！）

这两个坑是几乎所有新手都会遇到的问题，请读者务必理解。

7.1 路径空格问题

现象：项目路径中有空格（如 Program Files (x86)），make 编译失败，报错信息混乱。

原因：Make 在解析 %.o: %.c 规则时，会把路径按空格分割。如果路径是 /d/Program Files (x86)/.../build，Make 会以为 /d/Program 是一个目标，Files 是另一个目标，(x86)/... 又是另一个目标……全乱套了。

解决方案：把 Makefile 中的 BUILD_DIR 从绝对路径改成相对路径：

makefile

# ❌ 原来（含空格的绝对路径）
BUILD_DIR := $(CURDIR)/build

# ✅ 修复（不含空格的相对路径）
BUILD_DIR := build

为什么这样能解决：build 只是一个简单的单词，没有任何空格，Make 不会再被"骗"到。

作者给读者的建议：把整个项目移到 D:\projects\ 这种无空格、无中文的短路径，以后永远不会遇到这个问题。

7.2 工具链 PATH 问题

现象：在 MSYS2 终端中手动输入 make 能成功编译，但 VSCode 按 Ctrl+Shift+B 执行任务时却报错找不到 arm-none-eabi-gcc。

原因：

.bashrc 中配置了 export PATH=".../gnu-toolchain/bin:$PATH"
但 .bashrc 开头有一行 [[ "$-" != *i* ]] && return，意思是"如果是非交互式 shell，直接退出"
VSCode 调用 make.exe 时使用的是非交互式 shell，.bashrc 没执行完就退出了，PATH 里没有工具链路径

解决方案：在 Makefile 中强制从交互式 shell 获取工具链路径：

makefile

TC_BIN        := $(shell bash -l -i -c 'command -v arm-none-eabi-gcc' 2>/dev/null)
export PATH   := $(dir $(TC_BIN)):$(PATH)

为什么这样能解决：bash -l -i -c 强制启动一个交互式 shell（-i 参数），让它完整加载 .bashrc，然后把获取到的工具链路径塞回 Make 的执行环境。

7.3 Makefile 完整改动

读者的 Makefile 最终改成了这样（第 11-15 行）：

makefile

PROJECT_DIR   := $(CURDIR)
BUILD_DIR     := build                                    # 解决路径空格
TC_BIN        := $(shell bash -l -i -c 'command -v arm-none-eabi-gcc' 2>/dev/null)
export PATH   := $(dir $(TC_BIN)):$(PATH)                # 解决 VSCode 任务找不到工具链
TOOLCHAIN     ?= arm-none-eabi-


## 第八部分：常见问题

### PyOCD 调试时频繁断开连接

现象：调试过程中 VS Code 突然报错，无法继续调试。

可能原因：

- ST-Link USB 线接触不良
- 供电不足
- 程序触发了 `HardFault` 硬件错误

解决方法：

- 拔插 USB 线
- 更换 USB 接口
- 重新按 `F5` 启动调试

### 找不到 .hex 文件

现象：执行 `pyocd flash` 时提示 `No such file`。

解决：烧录命令指定正确路径：

```cmd
pyocd flash -t py32f403xc --erase chip "build/firmware.hex"

附录 A：关键路径速查表（作者实际路径）

组件	作者的实际路径
VSCode 工作区根目录	`D:\...\PY32F403_EPD_ST7305\`
Makefile 所在目录	`D:\...\PY32F403_EPD_ST7305\`（根目录）
编译输出目录	`D:\...\PY32F403_EPD_ST7305\build\`
源码目录	`D:\...\PY32F403_EPD_ST7305\app\`
MSYS2 安装目录	`D:\msys64`
`make.exe`	`D:\msys64\usr\bin\make.exe`
`arm-none-eabi-gdb.exe`	`F:\Microsoft VS Code\gnu-toolchain\bin\arm-none-eabi-gdb.exe`
VS Code 配置目录	`D:\...\PY32F403_EPD_ST7305\.vscode\`

读者注意：请将上述路径替换为自己电脑上的实际路径。

附录 B：MSYS2 终端选择指南

终端名称	什么情况下用
MSYS2 MSYS	系统更新（`pacman -Syu`）和安装工具包
MSYS2 UCRT64	日常开发、编译项目、配置环境变量

记住口诀：安装工具用 MSYS，写代码编译用 UCRT64。

附录 C：在 VS Code 中用命令行进行 GDB 调试

如果读者不想使用 F5 一键调试，或 F5 遇到问题需要排查底层原因，可以按照以下步骤在 VS Code 的集成终端中手动执行 GDB 调试。所有操作都在 VS Code 底部的终端面板中完成。

C.1 准备工作：在 VS Code 中打开两个终端

在 VS Code 中按 Ctrl+`（反引号）打开终端面板。
点击终端面板右上角的 "+"号 或 "拆分终端" 图标，创建两个并排的终端。
- 终端 1：用来运行 GDB Server（PyOCD）
- 终端 2：用来运行 GDB 客户端（arm-none-eabi-gdb）

如果读者已经配置了 launch.json，按 F5 会自动完成以下所有操作，无需手动输入。

C.2 终端 1：启动 GDB Server（PyOCD）

在 终端 1 中执行：

bash

pyocd gdbserver --target py32f403xc --port 3333

终端显示 Listening on port 3333... 即表示服务端就绪。这个终端保持运行，不要关闭。

C.3 终端 2：启动 GDB 客户端

在 终端 2 中执行：

bash

arm-none-eabi-gdb build/firmware.elf

此时终端进入 GDB 交互界面，提示符变为 (gdb)。

C.4 连接目标芯片

在 (gdb) 提示符下输入：

bash

target remote 127.0.0.1:3333

看到 Remote debugging using 127.0.0.1:3333 即握手成功，可以开始调试了。

C.5 烧录并开始调试

bash

load                    # 烧录固件到芯片
monitor reset           # 复位芯片
b main                  # 在 main 函数打断点
c                       # continue，全速运行，停在 main

C.6 常用命令速查

运行控制：

命令	作用	对应 VS Code 操作
`c` / `continue`	恢复程序运行	按"继续"按钮
`Ctrl+C`	暂停程序	按"暂停"按钮
`s` / `step`	单步跳入（进入函数内部）	F11
`n` / `next`	单步跳过（不进入函数）	F10
`finish`	跳出当前函数	Shift+F11
`monitor reset`	硬件复位	-
`quit`	退出调试	按"停止"按钮

断点：

命令	作用	对应 VS Code 操作
`b 文件名:行号`	在指定行打断点	点击行号左侧
`b 函数名`	在函数入口打断点	-
`info b`	查看所有断点	断点面板
`del 编号`	删除指定断点	删除红点
`watch 变量名`	监控变量写入（数据篡改时自动暂停）	-
`info watchpoints`	查看所有观察点	-

变量与内存：

命令	作用	对应 VS Code 操作
`p 变量名`	打印变量当前值	鼠标悬停变量
`set 变量名 = 数值`	运行中修改变量	调试控制台
`x /w 地址`	以 4 字节（word）读取内存	内存查看窗口
`x /b 地址`	以 1 字节读取内存	-
`x /4b 地址`	连续读取 4 个字节	-

C.7 退出命令行调试

在 (gdb) 提示符下输入 quit 退出 GDB 客户端。
在终端 1 中按 Ctrl+C 停止 PyOCD 服务端。

附录 D：安装完成后的验证清单

检查项	验证命令	预期结果
Python	`python --version`	显示 3.13.14
PyOCD	`pyocd --version`	显示 0.44.1
PY32 芯片支持	`pyocd list --targets \| findstr py32`	显示 `py32f403xc`
ST-Link 识别	`pyocd list`	显示 ST-Link 设备
make	`make --version`	显示 GNU Make 4.4.1
arm-none-eabi-gdb	`arm-none-eabi-gdb --version`	显示 GNU gdb 15.2

全部通过后，读者就可以：

按 Ctrl+Shift+B 一键编译
按 F5 一键调试
或按附录 C 的流程在 VS Code 终端中手动 GDB 调试

PY32F403 开发环境搭建与调试配置完整笔记（小白友好版） ​

📖 一句话总结（先看这里，明白你在做什么） ​

📖 文档说明 ​

🗺️ 完整执行路线图 ​

第一部分：基础环境准备 ​

1.1 下载所需文件 ​

1.2 安装 Python 环境 ​

1.3 安装 ST-Link V2 驱动 ​

第二部分：PyOCD 烧录环境 ​

2.1 安装 PyOCD ​

2.2 检查 ST-Link 是否被识别 ​

2.3 安装 PY32F403 芯片支持（关键步骤） ​

第三部分：MSYS2 工具链安装 ​

3.1 为什么需要 MSYS2？ ​

3.2 安装 MSYS2 ​

3.3 更新 MSYS2 系统 ​

3.4 安装 make 和 GCC 工具链 ​

3.5 配置 Windows 系统环境变量（非常重要！） ​

3.6 验证 make 是否安装成功 ​

3.7 配置 MSYS2 终端：显示中文界面 ​

3.8 配置 MSYS2 终端：启用 Ctrl+Shift+C 复制 / Ctrl+Shift+V 粘贴 ​

第四部分：ARM 调试工具链（arm-none-eabi-gdb） ​

4.1 这个工具是干什么的？ ​

4.2 怎么安装？（作者实际使用的方式） ​

4.3 确认 arm-none-eabi-gdb 已安装 ​

4.4 让 MSYS2 终端也能找到 arm-none-eabi-gdb ​

第五部分：VS Code 一键调试配置（F5 自动化） ​

5.1 安装 VS Code 插件 ​

5.2 项目结构说明 ​

5.3 编写 .vscode/tasks.json（编译任务） ​

5.4 编写 .vscode/launch.json（调试配置） ​

5.5 编写 .vscode/c_cpp_properties.json（头文件路径配置，可选） ​

5.6 编写 .vscode/settings.json（编辑器设置，可选） ​

第六部分：一键编译与手动烧录 ​

6.1 编译（Ctrl+Shift+B） ​

6.2 手动烧录（备用方式） ​

6.3 一键调试（F5） ​

第七部分：核心坑点解决（小白必看！） ​

7.1 路径空格问题 ​

7.2 工具链 PATH 问题 ​

7.3 Makefile 完整改动 ​

附录 A：关键路径速查表（作者实际路径） ​

附录 B：MSYS2 终端选择指南 ​

附录 C：在 VS Code 中用命令行进行 GDB 调试 ​

C.1 准备工作：在 VS Code 中打开两个终端 ​

C.2 终端 1：启动 GDB Server（PyOCD） ​

C.3 终端 2：启动 GDB 客户端 ​

C.4 连接目标芯片 ​

C.5 烧录并开始调试 ​

C.6 常用命令速查 ​

C.7 退出命令行调试 ​

附录 D：安装完成后的验证清单 ​

PY32F403 开发环境搭建与调试配置完整笔记（小白友好版）

📖 一句话总结（先看这里，明白你在做什么）

📖 文档说明

🗺️ 完整执行路线图

第一部分：基础环境准备

1.1 下载所需文件

1.2 安装 Python 环境

1.3 安装 ST-Link V2 驱动

第二部分：PyOCD 烧录环境

2.1 安装 PyOCD

2.2 检查 ST-Link 是否被识别

2.3 安装 PY32F403 芯片支持（关键步骤）

第三部分：MSYS2 工具链安装

3.1 为什么需要 MSYS2？

3.2 安装 MSYS2

3.3 更新 MSYS2 系统

3.4 安装 make 和 GCC 工具链

3.5 配置 Windows 系统环境变量（非常重要！）

3.6 验证 make 是否安装成功

3.7 配置 MSYS2 终端：显示中文界面

3.8 配置 MSYS2 终端：启用 Ctrl+Shift+C 复制 / Ctrl+Shift+V 粘贴

第四部分：ARM 调试工具链（arm-none-eabi-gdb）

4.1 这个工具是干什么的？

4.2 怎么安装？（作者实际使用的方式）

4.3 确认 arm-none-eabi-gdb 已安装

4.4 让 MSYS2 终端也能找到 arm-none-eabi-gdb

第五部分：VS Code 一键调试配置（F5 自动化）

5.1 安装 VS Code 插件

5.2 项目结构说明

5.3 编写 `.vscode/tasks.json`（编译任务）

5.4 编写 `.vscode/launch.json`（调试配置）

5.5 编写 `.vscode/c_cpp_properties.json`（头文件路径配置，可选）

5.6 编写 `.vscode/settings.json`（编辑器设置，可选）

第六部分：一键编译与手动烧录

6.1 编译（Ctrl+Shift+B）

6.2 手动烧录（备用方式）

6.3 一键调试（F5）

第七部分：核心坑点解决（小白必看！）

7.1 路径空格问题

7.2 工具链 PATH 问题

7.3 Makefile 完整改动

附录 A：关键路径速查表（作者实际路径）

附录 B：MSYS2 终端选择指南

附录 C：在 VS Code 中用命令行进行 GDB 调试

C.1 准备工作：在 VS Code 中打开两个终端

C.2 终端 1：启动 GDB Server（PyOCD）

C.3 终端 2：启动 GDB 客户端

C.4 连接目标芯片

C.5 烧录并开始调试

C.6 常用命令速查

C.7 退出命令行调试

附录 D：安装完成后的验证清单