如果你正在寻找一个能让你在熟悉的 VSCode 环境中，用 Zephyr RTOS 快速上手 STM32F103C8T6 最小系统板的完整方案，那么这篇文章就是为你准备的。Zephyr 作为一个功能强大的开源实时操作系统，其模块化设计和丰富的驱动支持，使其成为嵌入式开发的优秀选择。然而，对于初学者或习惯了传统 IDE 的开发者来说，其基于命令行的构建系统和复杂的工具链配置往往是一道门槛。

本文将聚焦于一个核心目标：在 Windows 环境下，使用 VSCode 作为主要开发工具，完成从 Zephyr 环境搭建、项目创建、代码编写到最终将程序烧录到 STM32F103C8T6 最小系统板的全过程。我们会避开繁琐的理论，直接进入实战，重点关注每一步的操作细节、可能遇到的坑以及如何验证结果。无论你是想评估 Zephyr 的开发体验，还是希望为手头的“蓝色药丸”开发板寻找一个现代化的开发框架，这套流程都能让你快速跑通第一个点灯程序。

1. 核心能力速览

在开始动手之前，我们先快速了解这套方案的核心特性和你需要准备的东西。

这套方案的优势在于，它利用 VSCode 强大的扩展生态和 Zephyr 官方工具，将原本分散的命令行操作整合到一个相对统一的界面中，提升了开发效率，尤其适合从 Arduino、STM32CubeIDE 等环境过渡过来的开发者。

2. 适用场景与使用边界

适合谁？

• 嵌入式初学者：希望通过一个具体的硬件平台（STM32F103C8T6）来学习 RTOS 和现代嵌入式开发流程。
• Zephyr 评估者：想在实际硬件上快速体验 Zephyr 的开发模式、驱动丰富度和性能。
• 项目原型开发者：需要为基于 Cortex-M3 内核的 MCU 快速搭建一个稳定、可扩展的软件基础。
• VSCode 忠实用户：希望在嵌入式开发中也延续使用 VSCode 的高效编辑和插件生态。

能解决什么问题？

1. 环境配置标准化：通过 Zephyr SDK 和工具链，避免手动配置编译器、OpenOCD 的繁琐和版本冲突。
2. 项目构建自动化：基于 CMake 和 Kconfig，实现跨平台的一键构建，管理依赖清晰。
3. 开发体验现代化：在 VSCode 中获得代码补全、语法高亮、跳转定义、构建任务集成等 IDE 级体验。
4. 烧录流程简化：通过集成好的命令或脚本，一键完成编译和烧录，无需切换多个工具。

不适合什么场景？

• 极度追求编译速度：Zephyr 的构建系统（CMake + Kconfig）在首次配置或大幅修改配置时可能较慢，对于需要极速迭代的简单项目，可能不如直接寄存器编程或 CubeIDE 快捷。
• 资源极度受限：虽然 Zephyr 可裁剪，但其内核本身会占用一定的 ROM/RAM。如果项目对几 KB 的 Flash/ROM 都锱铢必较，可能需要精细配置或考虑更轻量的 RTOS。
• 仅需裸机开发：如果项目非常简单，完全不需要任务调度、IPC 等 RTOS 功能，使用 Zephyr 可能会引入不必要的复杂度。

安全与合规边界

• 硬件操作：连接和烧录开发板时，请确保电源和接口连接正确，避免短路。
• 软件版权：Zephyr 采用 Apache 2.0 许可证，可免费用于商业和个人项目，但需遵守其许可证要求。
• 固件安全：本文涉及的烧录操作会擦写 MCU 内部 Flash，操作前请确认板载无重要数据。

3. 环境准备与前置条件

请确保你的 Windows 系统满足以下条件，并提前下载好必要的安装包。

3.1 硬件准备

1. STM32F103C8T6 最小系统板：一块。
2. ST-Link V2 调试器（或兼容的 DAPLink 调试器）：一个。
3. Micro-USB 数据线：两条（一条用于给开发板供电/通信，另一条用于连接 ST-Link 到电脑）。
4. 杜邦线：若干（用于连接 ST-Link 与开发板）。

3.2 软件准备（下载安装包）

在开始安装前，建议先下载好以下软件：

• VSCode: 从官网下载并安装。
• Git for Windows: 从官网下载并安装，安装时记得勾选“将 Git 添加到系统 PATH”。
• Python 3.8 或更高版本: 从官网下载 Windows 安装包，安装时务必勾选“Add Python to PATH”。
• Zephyr SDK: 这是包含编译器、调试器等工具链的集成包。从 Zephyr SDK 发布页面下载适用于 Windows 的安装程序（如zephyr-sdk-0.16.5_windows-x86_64.exe或更新版本）。

4. 安装部署与启动方式

接下来，我们一步步安装和配置所有软件。

4.1 安装 Python 及必要包

1. 完成 Python 安装后，以管理员身份打开命令提示符（CMD）或 PowerShell。
2. 安装用于 Zephyr 环境管理的west工具和其他依赖：

   pip install west pip install pyelftools pip install pyyaml pip install packaging

   west是 Zephyr 项目的元工具，用于管理多个仓库和构建命令。

4.2 安装 Zephyr SDK

1. 运行之前下载的 Zephyr SDK 安装程序。
2. 安装路径建议保持默认（如C:\zephyr-sdk-0.16.5），避免中文和空格。
3. 在安装最后一步，务必勾选“将工具链添加到系统 PATH”的选项，这样后续命令才能找到编译器。

4.3 获取 Zephyr 源码并设置环境

1. 选择一个合适的目录作为工作空间，例如D:\zephyrproject。在命令行中进入该目录：

   cd /d D:\zephyrproject

2. 使用west初始化 Zephyr 源码仓库：

   west init

3. 拉取 Zephyr 主仓库及其所有模块（此过程耗时较长，依赖网络环境）：

   west update

4. 导出 Zephyr 环境变量。这是一个关键步骤，让系统知道 Zephyr 的根目录在哪里：

   west zephyr-export

5. 安装 Zephyr 的 Python 依赖。在D:\zephyrproject目录下，运行：

   pip install -r zephyr\scripts\requirements.txt

4.4 安装 VSCode 插件

打开 VSCode，安装以下核心插件以提升开发体验：

• C/C++(Microsoft): 提供代码智能感知、跳转、调试支持。
• CMake Tools(Microsoft): 集成 CMake 构建、配置、调试。
• Zephyr IDE(Zephyr Project): 官方插件，提供 Kconfig 图形化配置、项目模板等（可选但推荐）。

5. 硬件连接与驱动检查

在烧录之前，必须确保电脑能正确识别调试器。

5.1 ST-Link 与开发板连接

ST-Link V2 通常有 4 个关键引脚需要连接到 STM32F103C8T6：

• SWDIO->PA13(JTMS)
• SWCLK->PA14(JTCK)
• GND->GND
• 3.3V->3.3V(为开发板供电，如果开发板已通过 USB 供电，则可不接)

注意：连接时务必断电操作，确认线序无误后再通电。

5.2 安装 ST-Link 驱动

1. 将 ST-Link 通过 USB 线连接到电脑。
2. 打开设备管理器，查看“通用串行总线设备”或“其他设备”中是否有“STM32 STLink”或未知设备。
3. 如果未自动安装，可以下载 ST 官方的STSW-LINK009(ST-Link USB driver) 进行手动安装。更简单的方法是安装STM32CubeProgrammer软件，其安装包内包含所需驱动。

安装成功后，在设备管理器的“通用串行总线设备”中应能看到 “STM32 STLink”。

5.3 验证工具链和连接

打开一个新的命令行窗口，执行以下命令进行验证：

# 验证编译器 arm-zephyr-eabi-gcc --version # 验证 west 工具 west --version # 验证设备连接（需要先安装 OpenOCD，Zephyr SDK 已包含） # 以下命令会尝试通过 ST-Link 连接目标板，如果成功会显示芯片 ID openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c init -c "reset halt" -c "flash probe 0" -c exit

如果openocd命令能成功执行并识别到芯片（例如显示stm32f1x.cpu），说明硬件连接和驱动一切正常。如果失败，请检查连接、驱动以及是否有其他软件（如 Keil, IAR）占用了 ST-Link。

6. 创建并构建第一个 Zephyr 项目

现在，我们创建一个最简单的 Blinky（闪烁 LED）项目。

6.1 使用 west 创建项目

在D:\zephyrproject目录外，找一个地方存放你的应用项目，例如D:\my_zephyr_apps。

cd /d D:\my_zephyr_apps west build -p always -b stm32f103c8t6 zephyr/samples/basic/blinky

命令解释：

• -p always: 总是清理之前的构建目录。
• -b stm32f103c8t6: 指定目标开发板为stm32f103c8t6。Zephyr 已经内置了对这块板子的支持。
• zephyr/samples/basic/blinky: 指定要构建的示例项目路径。

构建成功后，输出会显示生成的文件位于D:\my_zephyr_apps\build\zephyr目录下，其中zephyr.bin和zephyr.hex就是我们要烧录的固件。

6.2 在 VSCode 中打开并构建项目

虽然命令行可以构建，但在 VSCode 中操作更直观。

1. 在 VSCode 中打开文件夹D:\my_zephyr_apps。
2. VSCode 可能会自动检测到 CMake 项目。如果没有，可以按Ctrl+Shift+P，输入 “CMake: Configure” 来配置。
3. 底部的状态栏会显示构建目标（Kit）。点击它，选择[Unspecified]，然后从列表中选择GCC arm-none-eabi或Zephyr arm之类的工具链。
4. 再次按Ctrl+Shift+P，输入 “CMake: Build”，即可开始构建。构建输出会显示在终端面板中。

7. 烧录固件到开发板

烧录是将编译好的二进制文件写入单片机 Flash 的过程。这里介绍几种常用方法。

7.1 使用 west flash 命令（推荐）

这是最集成化的方式。确保开发板已通过 ST-Link 连接好且驱动正常，在项目构建目录下执行：

cd /d D:\my_zephyr_apps\build west flash

west flash命令会自动调用正确的烧录工具（如 OpenOCD）和配置文件，将固件烧录到板子上。如果看到类似 “** Programming Finished**” 和 “** verify OK**” 的输出，即表示烧录成功。此时，STM32F103C8T6 板载的 PC13 引脚连接的 LED（如果板子有）应该开始闪烁。

7.2 使用 STM32CubeProgrammer（图形化）

如果你更喜欢图形界面：

1. 打开 STM32CubeProgrammer。
2. 在连接方式中选择 “ST-LINK”，并点击刷新按钮连接到设备。
3. 连接成功后，在 “Binary File” 一栏选择之前生成的zephyr.hex或zephyr.bin文件。
4. 点击 “Download” 按钮开始烧录。进度条完成后，按一下板子的复位键，LED 应开始闪烁。

7.3 使用 OpenOCD 命令（底层）

对于想了解底层过程的开发者，可以直接使用 OpenOCD：

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "program D:/my_zephyr_apps/build/zephyr/zephyr.bin verify reset exit 0x08000000"

此命令会连接芯片、擦除、编程、校验并复位芯片。

8. 功能测试与效果验证

烧录完成后，需要进行验证以确保系统按预期工作。

8.1 基础验证：LED 闪烁

• 预期结果：STM32F103C8T6 最小系统板上与 PC13 引脚连接的 LED（通常是蓝色或绿色）以大约 1Hz 的频率闪烁。
• 验证方法：肉眼观察。
• 如果 LED 不闪：
  1. 检查硬件连接，特别是 SWDIO 和 SWCLK 是否接反。
  2. 确认烧录过程是否真的成功（查看命令行输出或 CubeProgrammer 日志）。
  3. 有些最小系统板的 LED 连接在别的引脚（如 PA1）。需要查看板子的原理图，并修改 Zephyr 项目中的设备树（dts）或prj.conf文件中的 LED 引脚定义。对于blinky示例，默认就是 PC13。

8.2 串口输出验证（进阶）

Blinky 示例默认没有串口输出。我们可以创建一个包含串口打印的项目来验证更复杂的功能。

1. 创建一个新应用目录，例如hello_world。
2. 创建src/main.c文件，写入以下内容：

   #include <zephyr/kernel.h> #include <zephyr/drivers/uart.h> #include <zephyr/sys/printk.h> void main(void) { const struct device *uart_dev = DEVICE_DT_GET(DT_NODELABEL(usart1)); if (!device_is_ready(uart_dev)) { printk("UART device not ready!\n"); return; } printk("Hello Zephyr on STM32F103C8T6!\n"); while (1) { printk("Tick...\n"); k_sleep(K_SECONDS(1)); } }

3. 创建CMakeLists.txt:

   cmake_minimum_required(VERSION 3.20.0) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(hello_world) target_sources(app PRIVATE src/main.c)

4. 创建prj.conf配置文件，启用 UART1：

   CONFIG_SERIAL=y CONFIG_UART_CONSOLE=y CONFIG_UART_ASYNC_API=n

5. 构建并烧录：

   west build -p always -b stm32f103c8t6 west flash

6. 使用串口调试助手（如 Putty、SecureCRT），连接开发板的 USART1 (PA9: TX, PA10: RX)，波特率设置为 115200，即可看到输出的 “Hello Zephyr…” 和 “Tick…” 信息。

9. 在 VSCode 中配置调试（可选但重要）

虽然烧录运行成功了，但高效的开发离不开调试。Zephyr 结合 VSCode 和 Cortex-Debug 插件可以实现源码级调试。

9.1 安装 Cortex-Debug 插件

在 VSCode 扩展商店中搜索并安装 “Cortex-Debug”。

9.2 创建调试配置文件

在项目根目录（D:\my_zephyr_apps\blinky）下创建.vscode/launch.json文件：

{ "version": "0.2.0", "configurations": [ { "name": "Cortex Debug (ST-Link)", "cwd": "${workspaceRoot}", "executable": "${workspaceRoot}/build/zephyr/zephyr.elf", "request": "launch", "type": "cortex-debug", "servertype": "openocd", "serverpath": "C:/zephyr-sdk-0.16.5/sysroots/x86_64-pokysdk-mingw32/usr/bin/openocd.exe", "device": "STM32F103C8", "interface": "swd", "runToEntryPoint": "main", "openOCDConfigFiles": [ "interface/stlink.cfg", "target/stm32f1x.cfg" ], "svdFile": "${env:ZEPHYR_BASE}/../modules/hal/stm32/svd/stm32f103.svd" } ] }

注意：serverpath需要修改为你本地 Zephyr SDK 中 OpenOCD 的实际路径。svdFile路径指向 SVD 文件，它帮助调试器解析外设寄存器。

9.3 开始调试

1. 确保开发板已连接。
2. 在 VSCode 中打开src/main.c，在printk语句处设置断点。
3. 按F5或点击运行与调试视图中的绿色开始按钮。
4. 程序会在断点处暂停，此时可以查看变量、单步执行、查看外设寄存器等。

10. 常见问题与排查方法

在实践过程中，你很可能遇到以下问题。这里提供快速的排查思路。

11. 最佳实践与使用建议

为了获得更顺畅的 Zephyr 开发体验，这里有一些建议：

1. 项目结构清晰：将自己的应用代码放在src/目录下，配置文件（prj.conf,boards/下的板级覆盖）放在项目根目录。与 Zephyr 源码分离。
2. 善用 Kconfig 配置：不要直接修改Kconfig文件。使用prj.conf进行应用级配置，使用boards/子目录下的.conf文件进行板级覆盖。使用menuconfig工具（west build -t menuconfig）可以图形化查看和修改配置。
3. 版本控制：将你的应用项目用 Git 管理起来。但切记将build/目录添加到.gitignore中。可以考虑将 Zephyr 本身作为 Git 子模块（Submodule），或者依赖west管理，以保证团队环境一致。
4. 调试是利器：尽早配置好 VSCode 的调试环境。单步执行、查看变量和寄存器，能极大提升排查问题的效率。
5. 查阅官方文档：Zephyr 官方文档是宝库。遇到驱动、内核 API 或构建系统的问题，首先去 docs.zephyrproject.org 搜索。
6. 从示例开始：zephyr/samples/目录下有大量示例，涵盖了从传感器、网络到文件系统的方方面面。在开发新功能前，先看看有没有现成的示例可以参考。
7. 管理多个板子：如果你有多个不同型号的开发板，可以使用west build -b <board_name>来指定目标板，并为每个板子创建不同的构建目录或配置覆盖。

通过以上步骤，你应该已经成功地在 STM32F103C8T6 上运行了 Zephyr，并在 VSCode 中建立了一套从编码、构建、烧录到调试的完整工作流。这套流程的核心价值在于将强大的 Zephyr RTOS 与高效的 VSCode 编辑器相结合，为嵌入式开发提供了现代化、可扩展的解决方案。接下来，你可以基于此环境，去探索 Zephyr 提供的更多功能，如线程、信号量、消息队列、设备驱动模型以及丰富的网络协议栈，从而构建更复杂的嵌入式应用。