1. 先搞清楚 Zephyr SDK 和 STM32F103C8T6 的关系如果你手上有一块 STM32F103C8T6 最小系统板想用 Zephyr RTOS 来开发那么第一步不是急着去写代码而是要把 Zephyr SDK 和环境变量配好。很多人卡在这一步不是编译报错就是找不到工具链折腾半天发现是环境没弄对。Zephyr SDK 是什么简单说它就是一套为 Zephyr 项目定制的工具链集合里面包含了编译、调试、烧录 STM32 这类 ARM Cortex-M 芯片所需的所有工具比如 GCC、OpenOCD、CMake、Ninja 等。它最大的好处是官方帮你把版本和兼容性都调好了你不需要自己一个个去下载、配置、解决依赖冲突。对于 STM32F103C8T6 这种基于 Cortex-M3 内核的芯片用 SDK 是最省事的入门方式。那么配置环境变量的核心目的就是让系统在任何目录下都能找到 SDK 里的这些工具。否则你每次编译可能都要输入一长串绝对路径或者直接报“命令未找到”。这个过程和配置 Java 的 JDK、Python 或 Maven 的环境变量逻辑是相通的都是为了让命令行工具全局可用。所以这篇文章的目标很明确带你走通从零开始在 Linux 或 Windows 环境下为 STM32F103C8T6 配置 Zephyr SDK 并完成验证的完整流程。我会重点讲清楚几个关键点SDK 版本怎么选、环境变量到底设在哪、如何验证配置是否真的生效以及最常遇到的几个坑怎么绕过去。2. 环境准备选对系统、版本和依赖在动手下载 SDK 之前先确认你的基础环境。Zephyr 对 Linux 的支持最友好Windows 次之建议用 WSL2macOS 也可以但不在本文重点。我们以最常见的 Ubuntu 20.04/22.04 和 Windows 10/11 的 WSL2Ubuntu 发行版为例。2.1 操作系统与基础依赖首先无论哪个系统都需要先安装一些基础编译工具和依赖库。打开终端执行以下命令更新并安装# 更新软件包列表 sudo apt update sudo apt upgrade -y # 安装编译依赖和工具 sudo apt install --no-install-recommends 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 gcc-multilib g-multilib libsdl2-dev libmagic1 -y注意dfu-util和device-tree-compiler是针对嵌入式开发的工具前者用于 USB DFU 模式烧录后者用于处理设备树。虽然 STM32F103C8T6 常用串口或 ST-Link 烧录但装上有备无患。2.2 获取 Zephyr SDK现在去下载 Zephyr SDK。不要直接去 GNU Arm 官网下裸工具链就用 Zephyr 官方维护的 SDK。访问 Zephyr SDK 发布页面 找到最新的稳定版本。写作时最新版是0.16.5但请以你看到的最新版为准。对于 STM32F103C8T6Cortex-M3我们需要的是支持arm-zephyr-eabi的工具链。通常下载文件名类似zephyr-sdk-0.16.5_linux-x86_64.tar.xzLinux 64位或zephyr-sdk-0.16.5_windows-x86_64.zipWindows。在终端里我们通常下载到用户主目录并解压# 进入主目录 cd ~ # 下载 SDK请替换为实际的最新版本链接 wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.5/zephyr-sdk-0.16.5_linux-x86_64.tar.xz # 解压 tar xvf zephyr-sdk-0.16.5_linux-x86_64.tar.xz解压后你会得到一个名为zephyr-sdk-0.16.5的目录。记住这个完整路径比如/home/你的用户名/zephyr-sdk-0.16.5后面配置环境变量要用。2.3 运行 SDK 安装后脚本解压只是第一步SDK 目录里有一个重要的安装脚本用于设置工具链的链接和许可。必须执行# 进入 SDK 目录 cd ~/zephyr-sdk-0.16.5 # 运行安装脚本 ./setup.sh这个脚本会做几件事询问你是否将工具链添加到用户 PATH通常选“是”。安装 SDK 所需的 udev 规则方便 USB 设备访问。注册工具链到 CMake。安装 QEMU 模拟器可选但建议装。关键点即使这个脚本说会帮你加 PATH我们仍然需要手动设置一个关键的环境变量ZEPHYR_SDK_INSTALL_DIR这是很多 Zephyr 构建脚本查找 SDK 的默认方式。3. 核心步骤配置环境变量并验证环境变量配置是核心也是最容易出错的地方。很多人照着教程配了但编译时还是报错问题往往出在变量没生效、路径不对或配置在了错误的地方。3.1 设置 ZEPHYR_SDK_INSTALL_DIR这个变量告诉 Zephyr 的构建系统你的 SDK 安装在哪里。我们需要把它设为 SDK 解压目录的绝对路径。对于 Linux/WSL2 环境变量通常设置在用户级的 shell 配置文件里比如~/.bashrc如果你用 Bash或~/.zshrc如果你用 Zsh。这里以 Bash 为例。用文本编辑器打开~/.bashrcnano ~/.bashrc或者vim ~/.bashrc在文件末尾添加以下两行请将/home/你的用户名替换为你的实际路径# 设置 Zephyr SDK 安装目录 export ZEPHYR_SDK_INSTALL_DIR/home/你的用户名/zephyr-sdk-0.16.5 # 将 SDK 的 bin 目录加入 PATH确保工具链命令可直接调用 export PATH$ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin:$PATH注意第二行 PATH 的添加很重要。虽然setup.sh可能加了但自己显式加上更保险。路径中的x86_64-pokysdk-linux是 SDK 的主机平台目录里面的usr/bin包含了arm-zephyr-eabi-gcc等核心工具。保存文件并退出编辑器在 nano 中是CtrlX然后按Y再按Enter在 vim 中是:wq。让配置立即生效source ~/.bashrc对于 Windows非 WSL 如果你坚持在原生 Windows 命令行或 PowerShell 中使用过程类似但语法不同。在 PowerShell 中临时设置重启失效$env:ZEPHYR_SDK_INSTALL_DIR C:\你的路径\zephyr-sdk-0.16.5 $env:Path ;$env:ZEPHYR_SDK_INSTALL_DIR\sysroots\x86_64-pokysdk-mingw32\usr\bin永久设置需要到“系统属性”-“高级”-“环境变量”中新建用户变量ZEPHYR_SDK_INSTALL_DIR并在Path变量中添加上述 bin 目录。强烈建议在 Windows 下开发 Zephyr优先使用 WSL2 获得完整的 Linux 环境能避免大量路径和兼容性问题。3.2 验证环境变量是否生效配置完后必须验证。打开一个新的终端窗口重要这样才会加载新的.bashrc执行# 打印 ZEPHYR_SDK_INSTALL_DIR 的值 echo $ZEPHYR_SDK_INSTALL_DIR # 检查 arm-zephyr-eabi-gcc 编译器是否能找到 which arm-zephyr-eabi-gcc # 查看编译器版本 arm-zephyr-eabi-gcc --version如果echo命令正确显示了你的 SDK 路径并且which命令返回了类似/home/.../zephyr-sdk-0.16.5/sysroots/x86_64-pokysdk-linux/usr/bin/arm-zephyr-eabi-gcc的路径且--version能输出版本信息如gcc version 12.2.0那么环境变量配置就成功了。3.3 获取 Zephyr 源码并设置 Zephyr 环境仅有 SDK 还不够我们还需要 Zephyr RTOS 的源代码。通常我们会把 Zephyr 源码、SDK 和项目放在一个工作空间里。# 回到主目录创建一个工作空间 cd ~ mkdir -p zephyrproject cd zephyrproject # 使用 West 工具获取 Zephyr 源码及其所有模块 west init west updatewest是 Zephyr 的项目管理工具。init会克隆主仓库update会拉取所有必要的模块如 HAL 库、驱动等。这步可能需要一些时间。接下来导出 Zephyr 的环境变量这能让你在任意目录使用west命令和 Zephyr 的 CMake 函数# 进入 Zephyr 源码目录 cd ~/zephyrproject/zephyr # 导出 Zephyr 环境变量 source zephyr-env.sh每次打开新终端进行 Zephyr 开发时都需要先source这个脚本。为了方便你也可以把source ~/zephyrproject/zephyr/zephyr-env.sh这行加到你的~/.bashrc文件中ZEPHYR_SDK_INSTALL_DIR设置的后面。4. 实战验证为 STM32F103C8T6 编译一个 Blinky理论配置完成现在用实际编译来验证整个工具链是否工作。我们选择 Zephyr 自带的blinky示例它会让 LED 闪烁是嵌入式界的“Hello World”。4.1 确认开发板标识在 Zephyr 中每个支持的开发板都有一个唯一的标识符。STM32F103C8T6 最小系统板最常对应的板型是nucleo_f103rb。因为 Nucleo-F103RB 板载的 MCU 就是 STM32F103RBT6与 C8T6 同系列引脚和寄存器兼容只是 Flash/RAM 大小略有不同。Zephyr 的板级支持包BSP通常以这类官方评估板为基础。你可以先列出所有支持的板子确认west boards在输出列表中查找nucleo_f103rb。4.2 编译 Blinky 示例进入示例目录并开始编译# 进入 blinky 示例目录 cd ~/zephyrproject/zephyr/samples/basic/blinky # 使用 west 构建指定目标板为 nucleo_f103rb并创建 build 目录 west build -b nucleo_f103rb命令解释west build启动构建。-b nucleo_f103rb指定目标板。默认会在当前目录下生成一个build文件夹所有中间文件和最终固件都在里面。如果一切配置正确你会看到 CMake 配置信息和编译进度最后以[100%] Linking C executable zephyr/zephyr.elf和[100%] Built target zephyr_final结束没有报错。4.3 关键输出文件与烧录编译成功后在build/zephyr/目录下你会找到几个关键文件zephyr.elf包含调试信息的可执行文件。zephyr.bin纯二进制镜像适合大多数烧录工具。zephyr.hexIntel HEX 格式文件。对于 STM32F103C8T6常用的烧录方式有ST-Link (V2/V3)通过 SWD 接口。使用openocd已包含在 SDK 中或 ST 的 STM32CubeProgrammer。串口 (USART1)通过 BOOT0 引脚置高进入系统存储器启动模式然后使用dfu-util或串口工具。这里以ST-Link和openocd为例确保你的 ST-Link 已连接板子的 SWDIO 和 SWCLK 引脚且共地# 在 blinky 目录下使用 west 和 openocd 烧录 west flashwest flash命令会尝试自动调用合适的 Runner这里是openocd来连接设备并烧录zephyr.hex或zephyr.bin。如果成功你会看到 OpenOCD 的连接日志和编程进度最后板载的 LED通常是 PC13具体看板子原理图应该开始闪烁。如果west flash失败检查 ST-Link 驱动是否安装lsusb应能看到 ST-Link 设备。检查 OpenOCD 配置。对于 STM32通常使用interface/stlink.cfg和target/stm32f1x.cfg。你可以创建一个简单的openocd.cfg文件来手动测试source [find interface/stlink.cfg] source [find target/stm32f1x.cfg] reset_config srst_only然后运行openocd -f openocd.cfg看是否能连接。权限问题在 Linux 下可能需要将用户加入plugdev组或为 ST-Link 设备设置 udev 规则。Zephyr SDK 的setup.sh应该已经处理了这部分。4.4 验证编译配置细节编译时CMake 会输出大量信息。有几个关键点值得关注工具链路径在 CMake 初始输出中会显示Using toolchain: zephyr以及路径确认它指向了你的 SDK 目录。设备树Zephyr 使用设备树DTS来描述硬件。编译时会看到Generating zephyr.dts最终生成的build/zephyr/zephyr.dts文件描述了nucleo_f103rb板的硬件配置。对于 C8T6你可能需要根据实际硬件如 LED 引脚调整设备树覆盖文件.overlay但blinky示例通常能直接运行在 PC13 上。内存布局链接脚本会依据芯片型号分配 Flash 和 RAM。对于 C8T664KB Flash, 20KB RAM编译日志会确认使用的链接脚本确保没有超出容量。5. 常见问题排查与深度配置即使按照步骤也可能遇到问题。下面是一些常见坑点和排查思路。5.1 环境变量未生效或路径错误现象west build时提示找不到编译器、ZEPHYR_TOOLCHAIN_VARIANT not set或Could not find toolchain。排查确认变量已加载在新终端中执行echo $ZEPHYR_SDK_INSTALL_DIR和which arm-zephyr-eabi-gcc。如果为空或路径不对说明.bashrc没生效。检查是否有拼写错误是否source ~/.bashrc了。检查变量值确保ZEPHYR_SDK_INSTALL_DIR指向的是 SDK 的根目录即包含setup.sh的目录而不是里面的arm-zephyr-eabi子目录。多版本冲突如果你之前安装过其他 ARM 工具链如gcc-arm-none-eabi可能会被优先找到。可以通过which -a arm-zephyr-eabi-gcc查看所有同名命令的位置确保第一个是 SDK 下的。Zephyr 环境未激活如果你没把source zephyr-env.sh加入.bashrc那么每次在新终端都需要手动进入zephyrproject/zephyr目录执行一次。否则west命令可能无法识别当前 Zephyr 环境。5.2 编译过程中的特定错误No SOURCES given to Zephyr library: drivers__console等类似错误 这通常是 Zephyr 源码或模块没有完整拉取。确保在zephyrproject目录下执行了west update并且网络通畅。可以尝试删除zephyrproject目录注意备份你的项目重新west init和west update。CMake Error at .../cmake/toolchain/zephyr/host-tools.cmake 这可能是 SDK 的setup.sh没有成功运行或者 CMake 找不到 host tools。确保你运行了./setup.sh并同意了所有选项。也可以尝试手动运行 SDK 目录下的cmake配置脚本如果有。内存不足错误STM32F103C8T6 的 RAM 只有 20KB。如果你的应用程序包括 Zephyr 内核、驱动、你的代码太大链接时会报错。使用west build -t rom_report和west build -t ram_report查看内存占用详情优化配置比如在prj.conf中禁用不必要的内核功能如CONFIG_SHELLn,CONFIG_CONSOLEn等。5.3 为自定义板创建板级定义如果你用的不是标准的 Nucleo 板而是一个纯粹的 STM32F103C8T6 最小系统板你可能需要创建一个自定义的板级定义。这不是必须的但能更精确地匹配你的硬件。在 Zephyr 中复制最接近的板定义cd ~/zephyrproject/zephyr/boards/arm cp -r nucleo_f103rb my_f103c8t6_board cd my_f103c8t6_board修改关键文件my_f103c8t6_board.yaml修改板子标识符和名称。my_f103c8t6_board.dts修改设备树根据你的原理图调整 LED、按键、晶振、调试接口等引脚定义。对于 C8T6主要确认 Flash 大小为 64KBRAM 为 20KB。Kconfig.board和Kconfig.defconfig修改默认配置。支持文件如pinmux.c、arduino_r3_connector.dtsi如果不需要可删除等。编译测试在你的应用目录中使用west build -b my_f103c8t6_board进行编译。这个过程涉及对 Zephyr 设备树和 Kconfig 系统的理解初期可以直接使用nucleo_f103rb作为起点大部分功能是兼容的。5.4 进阶使用 VSCode 进行开发命令行足够强大但图形化 IDE 能提升效率。VSCode 有很好的 Zephyr 支持。安装插件安装 “C/C” 和 “CMake Tools” 扩展。配置 CMake Tools在项目根目录即你的应用目录如blinky下VSCode 的 CMake Tools 会自动检测到CMakeLists.txt。它会读取ZEPHYR_BASE环境变量由zephyr-env.sh设置来配置工具链。选择工具链和构建目标在 VSCode 底部状态栏点击 “CMake”选择 “Debug” 或 “Release” 配置然后选择目标板nucleo_f103rb。之后就可以使用 VSCode 的构建、调试按钮了。调试配置结合 OpenOCD 和 Cortex-Debug 插件可以实现在 VSCode 中单步调试 STM32。这需要配置launch.json指定 OpenOCD 配置文件和 ELF 文件路径。6. 总结与后续方向走通 Zephyr SDK 的配置和第一个例程是使用 Zephyr 开发 STM32F103C8T6 最关键的一步。整个过程的核心逻辑是准备基础环境 - 获取并安装官方 SDK - 正确设置指向 SDK 的环境变量 - 获取 Zephyr 源码并激活其环境 - 使用正确的板型标识进行编译和烧录验证。配置成功后你就可以基于这个稳定的环境进行更深入的开发探索更多示例Zephyr 提供了传感器、网络、文件系统等大量示例 (samples/目录下)。添加外部库通过west管理模块可以方便地添加如 LVGL图形库、LittleFS文件系统等第三方组件。优化配置通过menuconfig(west build -t menuconfig) 图形化界面或直接修改prj.conf裁剪内核功能以适应 C8T6 有限的资源。编写自定义驱动学习 Zephyr 的设备驱动模型为你的特定外设编写驱动。最后记住一个习惯当你更换开发环境、升级 SDK 或 Zephyr 版本后第一件事就是重新验证环境变量和工具链路径。很多“诡异”的编译错误根源都在于此。把环境配扎实了后面的开发才会顺畅。