VSCode + Zephyr RTOS开发STM32F103C8T6全流程指南

1. 从零开始：为什么要在VSCode里用Zephyr搞STM32F103C8T6

如果你手头有一块经典的STM32F103C8T6最小系统板，想从传统的Keil、IAR或者STM32CubeIDE转向更现代、更开源的开发方式，那么Zephyr RTOS加上VSCode的组合，绝对值得你花时间折腾一下。这个方案解决的核心问题是：让你在一个统一的、跨平台的、插件生态丰富的编辑器里，完成从代码编写、项目构建、调试到固件烧录的完整嵌入式开发流程。它特别适合已经厌倦了传统IDE的笨重，或者需要在Linux/macOS下进行STM32开发的工程师和爱好者。

最关键的价值在于，Zephyr提供了一个高度模块化、可配置的实时操作系统内核，而VSCode提供了极佳的代码编辑和项目管理体验。两者结合，意味着你可以用写应用层代码的舒适感，去开发底层嵌入式系统。但别被“现代”这个词唬住，它的落地过程依然充满了“嵌入式特色”的坑，比如工具链配置、环境变量、烧录器驱动，一个没对齐，就可能卡住半天。这篇文章就是带你完整走一遍，用VSCode在STM32F103C8T6上运行第一个Zephyr项目的全过程，重点不是罗列命令，而是告诉你每一步在干什么，以及卡住了该往哪看。

2. 动手前的准备：理清工具链与硬件清单

在打开VSCode之前，先把“战场”打扫干净。很多失败都源于环境没准备好。你需要的东西分为软件和硬件两大部分。

2.1 软件环境搭建（以Windows为例，Linux/macOS思路类似）

Zephyr的开发环境相对独立，官方推荐使用其工具链管理器。我们按顺序来。

第一步：安装Python和包管理器Zephyr的构建系统West严重依赖Python。请确保你安装了Python 3.8或更高版本，并且将Python和Pip添加到系统环境变量PATH中。安装后，在命令行输入python --version和pip --version确认。

第二步：安装Zephyr SDK这是最核心的一步。Zephyr SDK是一个集成了编译器、调试器、烧录工具等所有必需工具的套件。

1. 前往Zephyr项目官网的下载页面，找到适用于你操作系统（Windows、Linux或macOS）的SDK安装包。对于STM32F103（ARM Cortex-M3架构），你需要的是ARM工具链。
2. 下载后，运行安装程序。关键点来了：安装路径不要包含中文或空格。我一般直接装在C:\zephyr-sdk-0.16.0（版本号以实际为准）这样的路径下。
3. 安装过程中，可能会询问是否将工具链添加到环境变量，务必勾选“是”。如果没有这个选项，安装完成后需要手动将SDK的bin目录（例如C:\zephyr-sdk-0.16.0\arm-zephyr-eabi\bin）添加到系统的PATH环境变量中。

第三步：获取Zephyr源码并初始化环境Zephyr的源码和项目管理通过west工具进行。

1. 打开命令行（CMD或PowerShell），创建一个干净的工作目录，比如D:\zephyr_project。
2. 在这个目录下，执行初始化命令。这里有个小技巧，为了加快克隆速度，可以使用国内镜像源（如清华源）：

   # 设置镜像地址（非必须，但推荐） pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 安装west工具 pip install west # 初始化一个west工作区，并指定使用镜像源克隆主仓库 west init -m https://gitee.com/mirrors/zephyr.git --mr main zephyrproject

3. 进入初始化的工作区目录，并拉取所有模块：

   cd zephyrproject west update

4. 导出Zephyr环境变量。这一步非常重要，它告诉系统Zephyr的核心路径在哪：

   # 在Windows PowerShell中 .\zephyr\zephyr-env.cmd # 在Linux/macOS的bash中 source zephyr/zephyr-env.sh

   每次新开命令行窗口要编译Zephyr项目前，都需要执行这个命令。为了方便，你可以把这条命令加到系统的启动脚本里，或者使用VSCode的终端集成功能（后面会讲）。

2.2 硬件连接与驱动

硬件方面很简单：

1. 主控：STM32F103C8T6最小系统板一块。
2. 调试/烧录器：ST-Link V2（或兼容的DAPLink等）。这是最常用的，也是本文示例所用的。
3. 连接方式：用杜邦线将ST-Link与最小系统板连接好：
   • ST-Link SWDIO->板子的SWDIO (PA13)
   • ST-Link SWCLK->板子的SWCLK (PA14)
   • ST-Link GND->板子的GND
   • ST-Link 3.3V->板子的3.3V（注意：如果板子已有独立供电，可不接VCC，但GND必须共地）。

连接好后，将ST-Link插入电脑USB口。打开设备管理器，你应该能看到一个“STMicroelectronics STLink dongle”或类似的设备。如果显示为未知设备，你需要安装ST-Link的驱动，可以从ST官网下载“STSW-LINK009”这个软件包进行安装。

3. 在VSCode中构建并运行第一个Zephyr示例

环境就绪，硬件连通，现在进入VSCode环节。我们的目标是编译一个最简单的Blinky（闪烁LED）程序，并烧录到板子上。

3.1 VSCode插件与工作区配置

首先，安装必要的VSCode插件：

• C/C++(Microsoft)：提供代码智能感知、跳转、错误检查。
• CMake Tools(Microsoft)：因为Zephyr使用CMake作为构建系统，这个插件至关重要。
• Zephyr IDE(Zephyr Project)：官方插件，提供项目创建、构建、烧录、调试的图形化按钮，能极大提升效率。

安装完插件后，用VSCode打开之前创建的zephyrproject目录。这是你的工作区根目录。

接下来是关键一步：配置VSCode的终端环境。我们需要让VSCode内部的终端（比如集成终端）自动载入Zephyr环境变量。

1. 在VSCode中，按Ctrl+Shift+P打开命令面板，输入Preferences: Open User Settings (JSON)。
2. 在打开的settings.json文件中，添加以下配置（路径请替换为你自己的实际安装路径）：

   { "terminal.integrated.shellArgs.windows": ["-NoExit", "-Command", "& 'C:\\zephyrproject\\zephyr\\zephyr-env.cmd'"], "cmake.configureEnvironment": { "ZEPHYR_BASE": "C:\\zephyrproject\\zephyr", "PATH": "C:\\zephyr-sdk-0.16.0\\arm-zephyr-eabi\\bin;${env:PATH}" }, "zephyr-ide.sdkPath": "C:\\zephyr-sdk-0.16.0" }

   这个配置做了三件事：让终端启动时自动运行zephyr-env.cmd；告诉CMake工具Zephyr的基础路径和工具链路径；告诉Zephyr IDE插件SDK在哪。对于Linux/macOS，配置原理类似，但语法和路径不同。

3.2 编译Blinky示例

Zephyr源码中自带大量示例，位于zephyr/samples目录下。我们以最基本的blinky为例。

1. 在VSCode的资源管理器中，导航到zephyr/samples/basic/blinky。
2. 在这个文件夹上右键，选择“在集成终端中打开”。
3. 在终端中，首先确保环境变量已加载（如果配置了上述自动加载，则无需手动执行）。然后，使用west命令进行构建，并指定我们的目标板。STM32F103C8T6最小系统板通常对应bluepill开发板配置（因为很多F103C8T6板子模仿了BluePill的布局）。

   west build -b bluepill .

   • west build: 构建命令。
   • -b bluepill: 指定板型（Board Target）。Zephyr支持大量板型，bluepill就是为STM32F103C8T6这类板子预定义的配置。
   • .: 表示在当前目录（即blinky示例目录）下构建。
4. 如果一切顺利，你会看到编译进度，最后输出[100%] Linking C executable zephyr\zephyr.elf和Memory region Used Size Region Size %age Used等信息，这表示编译成功。生成的固件文件是build\zephyr\zephyr.bin。

常见问题排查点：

• west命令未找到：说明Python环境或west安装有问题，或者环境变量未生效。回到命令行（非VSCode终端）检查west --version。
• 板型bluepill未找到：检查拼写，或者运行west boards查看所有支持的板型列表。
• 编译错误，提示找不到编译器或头文件：99%是Zephyr SDK路径或环境变量ZEPHYR_BASE未正确设置。请仔细检查第2.1和3.1节的配置。

3.3 烧录固件到STM32F103C8T6

编译成功只是生成了二进制文件，下一步是把它“灌”进芯片里。Zephyr的west命令也集成了烧录功能。

1. 确保ST-Link已正确连接板子和电脑。

2. 在刚才编译的终端里（目录仍在blinky的build目录外），运行烧录命令：

   west flash

   west flash命令会自动调用SDK中对应的烧录工具（对于ST-Link和bluepill板型，通常是OpenOCD），找到连接的设备，并将zephyr.bin文件写入芯片的Flash。

3. 观察终端输出和板子。如果成功，你会看到类似以下信息：

   -- west flash: using runner openocd Open On-Chip Debugger ... Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : clock speed 1000 kHz Info : STLINK V2J... Info : Target voltage: 3.3 V Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints ** Programming Started ** ** Programming Finished ** ** Verify Started ** ** Verified OK ** ** Resetting Target **

   同时，板载的LED（通常是PC13引脚连接的LED）应该开始闪烁。

烧录失败排查：

• west flash找不到设备：首先检查设备管理器里ST-Link驱动是否正常（有无感叹号）。然后检查杜邦线连接是否牢固，特别是SWDIO、SWCLK和GND。
• 提示“No ST-Link detected”或“Cannot connect to target”：尝试给板子重新上电，或者按一下板子的复位键。有时芯片处于某种状态会导致连接失败。
• 权限问题（Linux/macOS常见）：可能需要将当前用户添加到dialout或plugdev组，或者使用sudo运行west flash（不推荐长期使用）。更好的方法是配置udev规则。

4. 进阶：理解项目结构与自定义开发

跑通示例只是开始。要开发自己的项目，你需要理解Zephyr项目的结构。

4.1 Zephyr项目目录结构

一个标准的Zephyr应用项目（比如你从blinky复制出来修改）通常包含以下关键文件：

my_app/ ├── CMakeLists.txt # 项目的CMake构建定义，必须包含 `find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})` 和 `target_sources(app PRIVATE src/main.c)` ├── prj.conf # 项目的Kconfig配置文件，用于启用/禁用Zephyr内核和驱动模块的功能 ├── src/ │ └── main.c # 你的应用程序主入口源文件 └── board.cmake (可选) # 板级特定配置，如果你有自定义板型

• CMakeLists.txt：告诉构建系统如何编译你的代码，链接哪些库。
• prj.conf：这是Zephyr的精髓之一。Zephyr内核、驱动、子系统都是可裁剪的模块。你在这里通过CONFIG_开头的宏来配置系统。例如，要使用GPIO和LED，就需要CONFIG_GPIO=y和CONFIG_LED=y。
• src/main.c：你的应用代码。入口函数是void main(void)。

4.2 创建并构建自定义项目

1. 在zephyrproject目录外（避免污染源码），新建一个目录，例如my_zephyr_app。
2. 按照上面的结构创建CMakeLists.txt,prj.conf,src/main.c。
3. 一个最简单的prj.conf可以只包含：

   CONFIG_GPIO=y CONFIG_LED=y

4. 在src/main.c中写一个简单的LED闪烁程序，可以参考blinky示例的代码。
5. 在my_zephyr_app目录下打开终端，执行构建和烧录：

   # 先加载环境变量（如果VSCode终端未自动加载） # 对于Windows: call C:\zephyrproject\zephyr\zephyr-env.cmd # 对于Linux/macOS: source /path/to/zephyrproject/zephyr/zephyr-env.sh west build -b bluepill . west flash

4.3 使用VSCode Zephyr IDE插件提升效率

手动敲命令虽然直接，但效率不高。Zephyr IDE插件提供了图形化界面：

1. 在VSCode活动栏找到Zephyr的图标（一个芯片形状）。
2. 在插件视图中，你可以选择板型 (bluepill)、项目目录、构建目录。
3. 点击“Build”按钮进行编译，点击“Flash”按钮进行烧录。
4. 插件还会在底部状态栏显示当前配置的板型和串口，非常直观。

更重要的是，这个插件能帮你自动补全prj.conf中的CONFIG_选项。当你输入CONFIG_时，它会列出所有可用的配置项及其说明，这对于探索Zephyr的强大功能至关重要。

5. 调试、问题排查与经验之谈

开发不可能一帆风顺。以下是几个高频问题点和我的排查经验。

5.1 串口打印调试信息

Blinky只能看灯，更复杂的调试需要输出日志。Zephyr默认使用串口（UART）作为控制台输出。

1. 硬件连接：将STM32F103C8T6的PA9 (TX) 和PA10 (RX) 通过USB转TTL模块连接到电脑。
2. 软件配置：在prj.conf中启用串口和控制台：

   CONFIG_SERIAL=y CONFIG_CONSOLE=y CONFIG_UART_CONSOLE=y # 对于STM32F1，通常使用USART1 CONFIG_UART_1=y

3. 代码中使用：在main.c中#include <zephyr/kernel.h>和#include <zephyr/sys/printk.h>，然后就可以用printk(“Hello Zephyr!\n”);打印信息了。
4. 电脑端查看：使用串口调试助手（如Putty、SecureCRT、或者VSCode的串口监视器插件），选择正确的COM口，波特率通常设置为115200。

5.2 内存不足与配置优化

STM32F103C8T6只有64KB Flash和20KB RAM，资源紧张。编译后留意终端输出的内存占用报告。如果接近或超出限制：

• 优化prj.conf：关掉不需要的功能。例如，如果不调试，可以关闭CONFIG_DEBUG；如果不用浮点数，可以关掉CONFIG_FPU。使用west build -t menuconfig可以打开一个图形化配置界面，更方便地裁剪模块。
• 编译器优化：在prj.conf中设置CONFIG_SIZE_OPTIMIZATIONS=y可以开启尺寸优化。
• 检查代码：避免使用大的全局数组，谨慎使用递归和动态内存分配（malloc）。

5.3 烧录后程序不运行

如果west flash成功但板子没反应（LED不闪）：

1. 检查启动模式：确保BOOT0引脚通过跳线帽接地（Boot from Main Flash）。这是最常见的原因。
2. 检查复位电路：有些最小系统板复位电路设计或元件有问题，尝试手动按一下复位键。
3. 检查时钟配置：Zephyr的bluepill板型配置默认使用内部HSI时钟（8MHz）。如果你的板子外部接了8MHz晶振，配置通常是正确的。如果接了其他频率的晶振，可能需要修改设备树（dts）文件，这属于进阶内容。
4. 验证二进制文件：用west build -t rom_report可以查看编译出的固件各部分在Flash中的布局，确认入口地址正确。

5.4 关于国产替代芯片

搜索热词里有“stm32f103c8t6国产替代”。像GD32F103、APM32F103等Pin-to-Pin兼容芯片，理论上可以尝试使用相同的bluepill配置，因为内核相同。但存在风险：

• Flash/RAM大小可能不同：需要修改设备树中的内存定义。
• 外设寄存器地址或行为可能有细微差异：可能导致驱动不工作。
• 最稳妥的做法：在Zephyr的boards/arm/目录下，复制一份bluepill板型定义，重命名为你的国产芯片板子名（如my_gd32_pill），然后根据芯片数据手册，仔细修改dts（设备树源文件）和Kconfig.defconfig中的相关配置。这是一个需要耐心对照手册和源码的过程。

整个过程走下来，你会发现用VSCode开发Zephyr项目，核心是把几个关键路径和环境变量配通。一旦配通，其代码编辑的流畅度、项目管理的清晰度，相比传统IDE有很大提升。对于STM32F103C8T6这类资源有限的板子，Zephyr提供了精细的配置能力，让你能真正掌控每一字节的Flash和RAM。建议你先从blinky和hello_world（串口打印）这两个最基础的示例跑通，建立起“编辑-构建-烧录-观察”的闭环信心，然后再逐步探索更复杂的驱动和子系统。遇到问题，多查看build目录下的zephyr/.config文件（它是由prj.conf生成的最终配置），以及编译输出的警告和错误信息，它们通常比想象中更有帮助。