在嵌入式开发领域，Zephyr RTOS 以其模块化、高度可配置和跨平台特性，正成为越来越多开发者的选择。然而，对于习惯了传统 IDE（如 Keil、IAR）的 STM32 开发者，尤其是使用 STM32F103C8T6 这类经典“蓝桥杯”最小系统板的用户来说，如何将 Zephyr 与现代化的编辑器 VSCode 结合，搭建一个流畅的开发、编译、烧录环境，是一个充满挑战但又极具价值的过程。本文将以 STM32F103C8T6 最小系统板为目标硬件，详细讲解如何在 VSCode 中配置 Zephyr 开发环境，运行一个简单的示例项目，并最终通过 ST-Link 将程序烧录到板卡中。整个过程不仅涉及工具链的安装，更关键的是理解 Zephyr 的构建系统、设备树配置以及调试器连接等核心概念，让你能脱离对特定商业 IDE 的依赖，拥抱更开放、更高效的嵌入式开发工作流。
1. 理解 Zephyr RTOS 与 VSCode 开发模式的优势
在开始动手之前，需要先厘清我们为什么要选择 Zephyr + VSCode 这套组合，以及它和传统开发方式的核心差异。
1.1 Zephyr RTOS 的核心特点
Zephyr 是一个面向资源受限设备的小型、可扩展实时操作系统（RTOS），由 Linux 基金会托管。它的设计哲学是高度模块化和可配置。与 FreeRTOS 等相比，Zephyr 通过 Kconfig 和设备树（Device Tree）提供了极强的硬件抽象和配置能力。这意味着，针对 STM32F103C8T6 的开发，你无需直接面对繁琐的寄存器地址和底层驱动，而是通过修改配置文件来声明和使用板载资源（如 UART、GPIO、I2C）。这种“描述硬件”而非“硬编码硬件”的方式，极大地提升了代码在不同硬件平台间的可移植性。
1.2 VSCode 作为嵌入式开发 IDE 的价值
Visual Studio Code 本身是一个轻量级代码编辑器，但其强大的扩展生态系统使其能够胜任复杂的嵌入式开发任务。对于 Zephyr 项目，VSCode 的优势在于：
- 智能感知与导航：通过 C/C++ 扩展，可以获得媲美专业 IDE 的代码补全、跳转定义、查找引用等功能，这对于浏览 Zephyr 庞大的源码库至关重要。
- 集成终端与任务系统：Zephyr 主要使用命令行工具（west, cmake, ninja）进行构建。VSCode 的集成终端可以无缝运行这些命令，而其任务系统（Tasks）可以将编译、烧录等命令固化，实现一键操作。
- 强大的调试支持：通过 Cortex-Debug 等扩展，可以图形化地配置和启动 GDB 调试会话，实现设置断点、查看变量、单步执行等操作，调试体验直观。
- 版本控制集成：内置的 Git 支持方便管理你的应用代码和项目配置。
这套组合的核心工作流是：在 VSCode 中编辑代码和配置文件，通过集成终端调用 Zephyr 的west构建系统进行编译，最后使用west flash命令或配置好的调试器进行程序烧录和调试。
2. 开发环境搭建：从零准备工具链
这是最繁琐但决定成败的一步。我们将基于 Ubuntu 22.04 LTS（或 Windows WSL2）进行环境搭建，因为这是 Zephyr 官方推荐且问题最少的方式。Windows 原生环境也可行，但路径和依赖问题更多。
2.1 安装系统依赖与 Python 环境
Zephyr 的构建工具west基于 Python，因此首先需要确保 Python 3.8+ 和 pip 可用。
# 更新系统包列表并安装基础依赖 sudo apt update sudo apt install -y git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc g++ libssl-dev libncurses-dev2.2 获取 Zephyr 源码并安装 west
west是 Zephyr 的多仓库管理工具，用于拉取源码、构建和烧录。
# 安装 west pip3 install --user -U west echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 验证 west 安装 west --version # 创建工作目录并初始化 Zephyr 源码 mkdir -p ~/zephyrproject cd ~/zephyrproject west init west updatewest init会克隆zephyr主仓库，west update会拉取所有必要的模块（如 hal_stm32, cmsis 等）。这是一个较耗时的过程。
2.3 安装 Zephyr SDK 和工具链
Zephyr SDK 包含了针对多种架构（如 ARM）的交叉编译工具链（gcc）、调试器（gdb）以及用于构建的主机工具。
cd ~/zephyrproject # 运行 Zephyr 提供的环境安装脚本 # 此脚本会提示你下载并安装 SDK，请选择默认或推荐的安装路径（如 /opt/zephyr-sdk-0.16.0） west zephyr-export # 安装 Zephyr SDK (以 0.16.0 版本为例，请检查官网获取最新版本链接) wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/zephyr-sdk-0.16.0_linux-x86_64.tar.xz wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/sha256.sum | shasum --check --ignore-missing tar xvf zephyr-sdk-0.16.0_linux-x86_64.tar.xz -C ~/ cd ~/zephyr-sdk-0.16.0 ./setup.sh -t arm-zephyr-eabi -h -c安装过程中，脚本会询问是否添加用户到udev规则，以便普通用户能访问调试器（如 ST-Link），务必选择 yes。
2.4 配置 VSCode 及必要扩展
在 Ubuntu 上安装 VSCode 后，需要安装以下核心扩展：
- C/C++ (ms-vscode.cpptools)：提供代码智能感知、调试支持。
- CMake Tools (ms-vscode.cmake-tools)：增强对 CMake 项目的支持，方便配置和构建。
- Cortex-Debug (marus25.cortex-debug)：针对 ARM Cortex-M 系列芯片的专用调试扩展。
- Zephyr IDE (zephyr-rtos.zephyr-ide)：官方扩展，提供 Kconfig、设备树语法高亮和片段。
安装完成后，在 VSCode 中打开我们之前创建的~/zephyrproject文件夹。
3. 创建并构建第一个 Zephyr 示例项目
环境就绪后，我们创建一个最简单的blinky（LED 闪烁）示例，并针对 STM32F103C8T6 进行构建。
3.1 创建应用程序目录
Zephyr 的应用代码需要放在zephyrproject目录之外，这是为了将你的应用与 Zephyr 源码分离。
# 回到用户主目录，创建你的应用工作区 cd ~ mkdir -p my_zephyr_apps/blinky_f103 cd my_zephyr_apps/blinky_f1033.2 编写应用源码与配置文件
一个最小的 Zephyr 应用需要三个文件：src/main.c,CMakeLists.txt,prj.conf。
首先创建src/main.c：
#include <zephyr/kernel.h> #include <zephyr/drivers/gpio.h> /* 定义 LED 设备树节点标签。 * 对于 STM32F103C8T6 最小系统板，通常板载 LED 连接在 PC13。 * 具体标签需要根据板级定义确认，这里使用一个通用标签示例。 * 实际中，我们会在后续的设备树覆盖文件中精确定义。 */ #define LED0_NODE DT_ALIAS(led0) static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios); void main(void) { int ret; // 检查 LED 设备是否就绪 if (!device_is_ready(led.port)) { return; } // 配置 LED 引脚为输出，并初始化为低电平（点亮） ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE); if (ret < 0) { return; } while (1) { // 翻转 LED 状态 gpio_pin_toggle_dt(&led); // 延时 1000 毫秒 k_msleep(1000); } }接着，在应用根目录（blinky_f103）创建CMakeLists.txt：
# 设置 Zephyr 所需的最低 CMake 版本 cmake_minimum_required(VERSION 3.20.0) # 查找 Zephyr 包。ZEPHYR_BASE 环境变量或在构建时通过 -DZEPHYR_BASE=... 指定 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) # 将你的应用命名为 `app`，并指定源码目录 project(blinky_f103) # 添加应用的源码文件 target_sources(app PRIVATE src/main.c)最后，创建配置文件prj.conf。这个文件用于通过 Kconfig 系统启用或禁用 Zephyr 的内核和驱动特性。
# 启用 GPIO 驱动 CONFIG_GPIO=y # 启用系统时钟和 tick，用于 k_msleep CONFIG_SYS_CLOCK_TICKS_PER_SEC=10003.3 为 STM32F103C8T6 准备板级支持
STM32F103C8T6 核心板通常不是 Zephyr 官方直接支持的开发板。我们需要使用一个最接近的官方板定义作为基础，并通过“板级覆盖”和“设备树覆盖”来适配我们的硬件。
Zephyr 中已有stm32f103c8t6的 SoC 级支持。我们可以选择nucleo_f103rb（基于 STM32F103RBT6）作为基础板，因为其芯片系列相同，主要区别在于引脚数量和封装。我们通过覆盖文件来调整引脚映射。
创建板级目录结构：
cd ~/my_zephyr_apps/blinky_f103 mkdir -p boards/arm/my_f103_board cd boards/arm/my_f103_board创建板级定义文件
my_f103_board.yaml：identifier: my_f103_board name: My STM32F103C8T6 Board type: mcu arch: arm toolchain: - zephyr ram: 20 flash: 64 supported: - arduino_gpio - arduino_i2c - arduino_spi这里定义了板卡标识符、名称、架构、RAM/Flash 大小（STM32F103C8T6 是 20KB RAM，64KB Flash）和支持的接口。
创建设备树源文件
my_f103_board.dts：/dts-v1/; #include <st/f1/stm32f103Xb.dtsi> #include <st/f1/stm32f103c(8-b)tx-pinctrl.dtsi> #include <dt-bindings/clock/stm32_clock.h> #include <dt-bindings/gpio/gpio.h> #include <dt-bindings/pinctrl/stm32-pinctrl.h> / { model = "My STM32F103C8T6 Board"; compatible = "st,my-f103-board"; chosen { zephyr,console = &usart1; zephyr,shell-uart = &usart1; zephyr,sram = &sram0; zephyr,flash = &flash0; }; leds { compatible = "gpio-leds"; led0: led_0 { gpios = <&gpioc 13 GPIO_ACTIVE_LOW>; label = "User LED"; }; }; aliases { led0 = &led0; }; }; &usart1 { pinctrl-0 = <&usart1_tx_pa9 &usart1_rx_pa10>; pinctrl-names = "default"; current-speed = <115200>; status = "okay"; }; &clk_hse { clock-frequency = <8000000>; /* 外部 8MHz 晶振 */ status = "okay"; }; &pll { mul = <9>; clocks = <&clk_hse>; status = "okay"; }; &rcc { clocks = <&pll>; clock-frequency = <DT_FREQ_M(72)>; /* PLL 输出 72MHz */ ahb-prescaler = <1>; apb1-prescaler = <2>; apb2-prescaler = <1>; };这个文件是关键，它描述了硬件：
- 定义了用户 LED 在
PC13，并创建了别名led0，这与main.c中的DT_ALIAS(led0)对应。 - 配置了 USART1 在
PA9(TX) 和PA10(RX)，用于控制台输出。 - 配置了时钟树，使用外部 8MHz 晶振，通过 PLL 倍频到 72MHz 系统时钟。
- 定义了用户 LED 在
创建 Kconfig 板级配置
Kconfig.board和Kconfig.defconfig：Kconfig.board内容：config BOARD_MY_F103_BOARD bool "My STM32F103C8T6 Board" depends on SOC_STM32F103XBKconfig.defconfig内容：if BOARD_MY_F103_BOARD config BOARD default "my_f103_board" endif # BOARD_MY_F103_BOARD创建 CMake 板级文件
CMakeLists.txt：# SPDX-License-Identifier: Apache-2.0 cmake_minimum_required(VERSION 3.20.0) define_property(GLOBAL PROPERTY ZEPHYR_LIBS) define_property(GLOBAL PROPERTY ZEPHYR_INTERFACE_LIBS)
3.4 使用 west 构建项目
现在回到应用目录，使用west命令进行构建，并指定我们的自定义板卡。
cd ~/my_zephyr_apps/blinky_f103 # 构建，指定板卡为自定义的 my_f103_board，构建目录为 build west build -b my_f103_board .如果一切顺利，你将在build目录下得到zephyr/zephyr.elf,zephyr/zephyr.bin,zephyr/zephyr.hex等输出文件。
关键解释：
-b my_f103_board：告诉 west 使用我们自定义的板卡配置。.：表示在当前目录（即应用目录）查找CMakeLists.txt和prj.conf。- 构建过程会依次执行：CMake 配置、Kconfig 菜单生成（如果需要）、设备树处理、最终编译链接。
4. 硬件连接与程序烧录
编译成功后，需要将生成的二进制文件烧录到 STM32F103C8T6 芯片中。最常用的工具是 ST-Link 调试器。
4.1 硬件连接
将 ST-Link V2（或兼容调试器）与 STM32F103C8T6 最小系统板连接：
| ST-Link 引脚 | STM32F103C8T6 引脚 | 功能 |
|---|---|---|
| SWDIO | PA13 (JTMS) | 数据输入输出 |
| SWCLK | PA14 (JTCK) | 时钟 |
| GND | GND | 地 |
| 3.3V | 3.3V | 电源（可选，如果板子已独立供电） |
注意：务必先连接 GND，再连接信号线。确保最小系统板的 Boot0 引脚已通过跳线帽或电阻接地（Boot0=0），使其从主闪存启动。
4.2 使用 west flash 命令烧录
Zephyr 的west工具集成了烧录功能。只要调试器连接正确且系统udev规则已配置，一条命令即可完成烧录。
# 在应用目录下执行 west flashwest flash命令会：
- 自动检测连接的调试器和目标芯片。
- 根据板卡定义（
my_f103_board）选择合适的烧录工具（通常是openocd或pyocd）。 - 将
build/zephyr/zephyr.bin或zephyr.hex文件烧录到芯片的 Flash 中。 - 完成后自动复位芯片运行。
4.3 在 VSCode 中配置一键烧录任务
为了更便捷，可以在 VSCode 中配置一个任务，实现快捷键烧录。
在项目根目录（blinky_f103）创建.vscode/tasks.json：
{ "version": "2.0.0", "tasks": [ { "label": "West Build", "type": "shell", "command": "west", "args": ["build", "-b", "my_f103_board", "."], "group": { "kind": "build", "isDefault": true }, "problemMatcher": ["$gcc"], "detail": "使用 west 构建 Zephyr 应用" }, { "label": "West Flash", "type": "shell", "command": "west", "args": ["flash"], "group": "build", "problemMatcher": [], "detail": "使用 west 烧录程序到开发板" } ] }配置后，你可以通过 VSCode 的 Terminal -> Run Task... 菜单选择West Flash来执行烧录。也可以绑定快捷键。
4.4 验证结果
烧录完成后，观察 STM32F103C8T6 最小系统板上的用户 LED（通常连接在 PC13）。它应该以 1 秒的间隔闪烁。如果没有闪烁，请进入下一章的排查步骤。
5. 常见问题与深度排查指南
初次搭建环境并运行项目，很可能会遇到各种问题。以下是按优先级排序的排查路径。
5.1 构建阶段问题
| 问题现象 | 可能原因 | 检查方式与解决方案 |
|---|---|---|
west build失败，提示board … not found | 1. 板卡名称拼写错误。 2. 自定义板卡目录未放在正确位置或结构错误。 3. 未导出 ZEPHYR_BASE环境变量。 | 1. 使用west boards命令列出所有可用板卡，确认名称。2. 检查 boards/arm/my_f103_board/目录结构及文件是否完整，与章节 3.3 对照。3. 确保在构建前执行了 source ~/zephyrproject/zephyr/zephyr-env.sh。 |
| CMake 配置错误，提示找不到工具链 | Zephyr SDK 未正确安装或路径未设置。 | 1. 检查~/.zephyrrc或zephyr-sdk-0.16.0目录下的environment-setup文件是否被 source。2. 运行 which arm-zephyr-eabi-gcc确认工具链可用。3. 重新运行 SDK 的 setup.sh脚本。 |
编译错误，提示DT_ALIAS(led0) not found | 设备树中未正确定义led0别名或 GPIO 引脚。 | 1. 检查my_f103_board.dts文件，确保leds节点和aliases节点正确定义。2. 检查 gpios = <&gpioc 13 GPIO_ACTIVE_LOW>;中的 GPIO 控制器（gpioc）和引脚号（13）是否与你的硬件原理图一致。3. 使用 west build -t menuconfig检查 GPIO 相关配置是否启用。 |
| 链接错误，提示内存不足 | 应用程序大小超过了芯片的 Flash 或 RAM 容量。 | 1. STM32F103C8T6 Flash 为 64KB，RAM 为 20KB。检查build/zephyr/zephyr.map文件末尾的占用情况。2. 在 prj.conf中禁用不必要的功能，如CONFIG_SHELL=n,CONFIG_CONSOLE=n。3. 优化代码，移除不用的模块。 |
5.2 烧录与调试阶段问题
| 问题现象 | 可能原因 | 检查方式与解决方案 |
|---|---|---|
west flash失败，提示No ST-Link detected或OpenOCD failed | 1. ST-Link 驱动未安装或udev规则未生效。2. ST-Link 与目标板连接错误或接触不良。 3. 目标板未供电或供电不足。 | 1. 运行lsusb查看是否有STMicroelectronics ST-LINK设备。若无，需安装驱动（Linux 下通常是stlink-tools包）。2. 重新检查并连接 SWDIO, SWCLK, GND 四根线。 3. 确保目标板有电（可通过 ST-Link 供电或外部 3.3V）。 4. 尝试使用 openocd命令手动连接：openocd -f interface/stlink.cfg -f target/stm32f1x.cfg。 |
| 烧录成功但 LED 不闪烁 | 1. 设备树中 LED 引脚定义错误（如 active-high/low 不对）。 2. 系统时钟配置错误，导致 k_msleep实际延时不准。3. 程序未运行（可能 Boot0 引脚为高电平，进入了系统存储器启动模式）。 | 1. 用万用表或逻辑分析仪检查 PC13 引脚是否有电平变化。若无，检查设备树 GPIO 配置。 2. 在 main函数开头添加printk(“Start\n”);并通过串口工具（如minicom,picocom）查看 PA9/PA10 是否有输出，验证系统初始化和时钟。3. 确认 Boot0 引脚已接地。 |
| 无法进入调试模式（VSCode Cortex-Debug） | 1.launch.json配置错误。2. 调试器类型或芯片型号选错。 3. 调试接口被占用（如 west flash后未复位）。 | 1. 在.vscode/launch.json中正确配置servertype（如openocd）、interface（如stlink.cfg）和device（如stm32f1x.cfg）。2. 先通过 west flash确认硬件连接和烧录正常，再尝试调试。3. 关闭可能占用调试接口的其他软件。 |
5.3 环境与配置问题
| 问题现象 | 可能原因 | 检查方式与解决方案 |
|---|---|---|
| VSCode C/C++ 扩展报错，无法找到头文件 | c_cpp_properties.json未正确配置包含路径。 | 1. 在 VSCode 中按Ctrl+Shift+P，运行C/C++: Edit Configurations (UI)。2. 在 Include Path中添加 Zephyr 内核头文件路径，如“${workspaceFolder}/../zephyrproject/zephyr/include/**”和“${workspaceFolder}/build/zephyr/include/generated/**”。3. 在 Defines中添加__ZEPHYR__。 |
修改prj.conf或设备树后，构建似乎未生效 | 构建缓存导致。CMake 不会因为配置文件的更改而自动重新运行。 | 1. 最彻底的方式：删除build目录，重新执行west build。2. 推荐方式：使用 west build -t run或west build -t menuconfig等目标，它们会触发必要的重新配置。 |
6. 进阶配置与最佳实践
成功运行第一个示例后，可以进一步优化开发流程并探索更多功能。
6.1 配置 VSCode 实现高效开发
- 智能感知配置：创建
.vscode/c_cpp_properties.json文件，手动指定 Zephyr 的包含路径和宏定义，确保代码跳转和补全准确。 - 集成构建与烧录：结合
tasks.json和快捷键绑定，将west build和west flash绑定到Ctrl+Shift+B和F5，实现一键编译烧录。 - 图形化调试：配置
.vscode/launch.json，使用 Cortex-Debug 扩展。一个基础的配置示例如下：
配置后，按 F5 即可启动调试会话，在源码中设置断点、观察变量。{ "version": "0.2.0", "configurations": [ { "name": "Cortex Debug (OpenOCD)", "cwd": "${workspaceRoot}", "executable": "${workspaceRoot}/build/zephyr/zephyr.elf", "request": "launch", "type": "cortex-debug", "servertype": "openocd", "serverpath": "openocd", "configFiles": [ "interface/stlink.cfg", "target/stm32f1x.cfg" ], "runToEntryPoint": "main", "device": "STM32F103C8" } ] }
6.2 为生产环境优化配置
用于学习的prj.conf通常比较简陋。对于实际项目，需要考虑以下配置：
# 硬件驱动 CONFIG_GPIO=y CONFIG_SERIAL=y CONFIG_UART_INTERRUPT_DRIVEN=y # 内核与调度 CONFIG_MAIN_STACK_SIZE=2048 CONFIG_IDLE_STACK_SIZE=1024 CONFIG_ISR_STACK_SIZE=2048 CONFIG_SYS_CLOCK_TICKS_PER_SEC=1000 CONFIG_OPTIMIZE_SIZE=y # 优化代码大小 # 日志与调试（开发时开启，生产时可关闭） CONFIG_LOG=y CONFIG_LOG_MODE_IMMEDIATE=y # 立即输出日志，便于调试 CONFIG_CONSOLE=y CONFIG_UART_CONSOLE=y # 硬件特定配置 CONFIG_CLOCK_CONTROL=y CONFIG_CLOCK_STM32_CUBE=y CONFIG_PWM=y # 如果需要PWM CONFIG_I2C=y # 如果需要I2C CONFIG_SPI=y # 如果需要SPI6.3 管理多个应用与自定义板卡
随着项目增多，建议：
- 应用目录独立：每个应用（如
blinky,sensor_app）都像blinky_f103一样，是zephyrproject同级目录下的独立文件夹。 - 板卡定义集中管理：可以将自定义的
boards/arm/my_f103_board目录移动到zephyrproject下的某个位置（如zephyrproject/my_boards），并通过设置BOARD_ROOT环境变量来让 west 找到它：export BOARD_ROOT=~/zephyrproject/my_boards。这样所有应用都可以共享这个板卡定义。 - 使用版本控制：将你的应用代码和自定义板卡定义纳入 Git 管理。但注意，
build目录和 Zephyr 源码本身（由 west 管理）不应提交。
6.4 扩展方向
在点亮 LED 的基础上，可以尝试：
- 使用串口打印日志：在
prj.conf中启用CONFIG_SERIAL和CONFIG_UART_CONSOLE，在代码中使用printk输出信息，通过 USB 转 TTL 模块连接 PA9/PA10 查看。 - 添加传感器驱动：例如，通过 I2C 或 SPI 连接一个温湿度传感器，在 Zephyr 中启用对应的驱动（如
CONFIG_SENSOR和CONFIG_BME280），并参考示例代码读取数据。 - 使用线程和同步原语：创建多个线程（
k_thread_create），使用信号量（k_sem）或消息队列（k_msgq）进行通信，体验 Zephyr 的实时调度能力。 - 功耗管理：配置低功耗模式，测量系统在不同睡眠模式下的电流消耗。
从在 VSCode 中成功编译并烧录第一个 Zephyr 程序到 STM32F103C8T6，标志着你已经打通了基于现代工具链的嵌入式开发流程。这个流程的核心价值在于其可重复性和可扩展性——一旦环境配通，后续开发新功能、移植到其他芯片或板卡，大部分工作就变成了修改配置文件和编写应用逻辑，而非重复搭建环境。遇到问题时，务必遵循从环境（工具链、驱动）、连接（硬件、调试器）、配置（Kconfig、设备树）到代码的逻辑进行分层排查。将自定义板卡定义标准化并纳入版本管理，是团队协作和项目复用的关键一步。接下来，你可以深入探索 Zephyr 的设备驱动模型、电源管理、网络协议栈等高级特性，将其应用到更复杂的物联网设备开发中。
