如果你正在尝试把 Zephyr RTOS 跑在 STM32F103C8T6 这种常见的最小系统板上环境变量配置往往是第一个实际门槛。很多人卡在这一步不是因为 Zephyr 本身复杂而是因为环境变量没配对导致工具链找不到、编译报错、烧录失败。这篇文章会直接带你走一遍我在实际项目里验证过的配置流程重点不是讲 Zephyr 多强大而是让你能在普通 Windows 或 Linux 环境下把基础环境变量配对顺利编译并烧录一个示例程序到 STM32F103C8T6 板上。1. 先搞清楚 Zephyr 环境变量到底管什么Zephyr 的环境变量核心是告诉系统三件事工具链在哪、SDK 在哪、当前项目怎么找依赖。很多人一上来就照搬教程设置ZEPHYR_BASE但经常忽略工具链路径和 CMake 变量导致编译时找不到编译器或头文件。1.1 关键变量清单这几个变量必须设对缺一不可ZEPHYR_BASE: Zephyr 源码根目录路径编译时 CMake 靠它定位内核和模块。ZEPHYR_TOOLCHAIN_VARIANT: 工具链类型比如gnuarmembARM GCC 嵌入式版或zephyr如果用 Zephyr SDK。GNUARMEMB_TOOLCHAIN_PATH如果选 gnuarmemb: ARM GCC 工具链的安装路径。另外如果你用 Zephyr SDK通常不需要手动设工具链路径但需要确保 SDK 安装正确且版本匹配。1.2 为什么容易配错最常见的问题是把ZEPHYR_BASE设成了子目录比如samples/hello_world而不是真正的源码根目录。另一个高频错误是工具链路径里带了bin子目录比如设成C:\gcc-arm\bin而不是C:\gcc-arm导致 CMake 找不到arm-none-eabi-gcc。我建议先通过一个小测试验证变量是否生效打开终端输入echo %ZEPHYR_BASE%Windows或echo $ZEPHYR_BASELinux/Mac看输出是不是正确的完整路径。2. 准备你的实战环境在配环境变量之前先把基础软件装好。下面是我在 Windows 和 Ubuntu 22.04 上实测可用的组合。2.1 硬件和软件清单开发板: STM32F103C8T6 最小系统板核心芯片是 Cortex-M3。调试器: ST-Link V2便宜常见烧录和调试都支持。主机系统: Windows 10/11 或 Ubuntu 22.04 LTS。必备软件:Git用于拉取 Zephyr 源码和模块。CMake 3.20.5 或更高版本Zephyr 的构建系统依赖它。Python 3.8 或更高版本Zephyr 的脚本工具用 Python 写的。ARM GCC 工具链建议用官方arm-none-eabi-gcc版本 12.3 或 13.2 都行。不要急着装 Zephyr SDK先用 ARM GCC 工具链走通流程之后再换 SDK 会更简单。2.2 安装 ARM GCC 工具链Windows 用户直接下载 ARM GNU Toolchain 官方安装包 选 “AArch32 bare-metal target (arm-none-eabi)” 版本安装到不含空格的路径比如C:\gcc-arm\13.2\。Linux 用户可以用包管理器安装sudo apt update sudo apt install gcc-arm-none-eabi装完后验证工具链是否可用arm-none-eabi-gcc --version如果提示命令找不到说明安装路径没加入 PATH或者需要重启终端。3. 一步步配置环境变量我推荐手动设置环境变量而不是依赖安装脚本。手动设置能让你更清楚每个变量的作用出错了也容易排查。3.1 Windows 用户配置步骤右键“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”部分新建或编辑以下变量变量名值示例说明ZEPHYR_BASEC:\zephyrproject\zephyr替换为你的 Zephyr 源码实际路径ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb固定值表示用 ARM GCCGNUARMEMB_TOOLCHAIN_PATHC:\gcc-arm\13.2替换为你的 ARM GCC 安装路径找到系统变量Path双击编辑在末尾添加%GNUARMEMB_TOOLCHAIN_PATH%\bin%ZEPHYR_BASE%\scripts全部确认后重新打开一个命令提示符让变量生效。3.2 Linux 用户配置步骤把以下内容加到~/.bashrc或~/.zshrc根据你用的 shellexport ZEPHYR_BASE~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb export GNUARMEMB_TOOLCHAIN_PATH/usr如果 ARM GCC 是手动安装到自定义目录比如/opt/gcc-arm/13.2则把GNUARMEMB_TOOLCHAIN_PATH设为该路径。然后执行source ~/.bashrc或新开终端窗口。3.3 验证变量是否生效新开终端依次运行echo $ZEPHYR_BASE echo $ZEPHYR_TOOLCHAIN_VARIANT arm-none-eabi-gcc --version如果都能正确输出说明基础变量设对了。4. 拉取 Zephyr 源码并编译示例变量配好之后实际跑一个编译流程用 STM32F103C8T6 的板型配置测试。4.1 获取源码和模块# 创建项目目录 mkdir zephyrproject cd zephyrproject # 克隆 zephyr 源码 git clone https://github.com/zephyrproject-rtos/zephyr cd zephyr # 拉取依赖模块需要 Python 和 west 工具 pip install west west init .. west update这一步可能会花点时间取决于网络。如果west update失败通常是网络问题重试或换镜像源。4.2 编译 hello_world 示例进入示例目录指定板型为stm32f103c8t6Zephyr 内置支持这个板型cd samples/hello_world west build -b stm32f103c8t6如果编译成功会在build/zephyr目录下生成zephyr.elf、zephyr.bin等文件。4.3 常见编译错误和解决找不到编译器: 检查GNUARMEMB_TOOLCHAIN_PATH是否指向正确路径且bin子目录下有arm-none-eabi-gcc。CMake 报错找不到 Zephyr: 确认ZEPHYR_BASE指向的是源码根目录并且执行west update拉全了模块。板型不支持: 确认板型名字拼写正确比如stm32f103c8t6全是小写。5. 烧录到 STM32F103C8T6 并验证编译通过后用 ST-Link 烧录到板子上。5.1 连接硬件ST-Link 的 SWDIO 接 STM32 的 PA13SWDIOST-Link 的 SWCLK 接 STM32 的 PA14SWCLKGND 接 GND3.3V 接 3.3V接好后给板子上电ST-Link 指示灯应该亮起。5.2 烧录命令在 hello_world 示例目录下执行west flash如果一切正常west 会自动检测 ST-Link 并烧录zephyr.hex或zephyr.bin文件。5.3 验证输出STM32F103C8T6 没有默认串口输出但你可以接一个 USB 转 TTL 模块PA9TX接 TTL 模块的 RXPA10RX接 TTL 模块的 TXGND 接 GND用串口工具如 PuTTY、minicom打开对应串口波特率设 115200复位板子应该能看到 Hello World! stm32f103c8t6 输出。如果没输出先检查接线再看烧录时是否有错误提示。6. 环境变量相关的深度排查即使按照上面步骤走有时还是会遇到环境变量导致的问题。这里把我自己排查时的顺序列出来。6.1 变量未生效的排查顺序确认终端会话是新开的修改环境变量后必须新开终端窗口否则老会话读不到新变量。检查变量值是否被覆盖比如在~/.bashrc里设了但~/.profile或系统级配置里有冲突设置。路径中是否有空格或特殊字符尽量用纯英文路径避免Program Files这种带空格的目录。变量名拼写错误比如ZEPHYR_BASE写成ZEPHYR_BASE_PATH。6.2 编译阶段变量问题如果编译报错提到工具链或 SDK按这个顺序查运行west build -t run这个命令会打印详细的 CMake 变量和工具链检测结果比普通编译输出更全。检查build/CMakeCache.txt搜索CMAKE_C_COMPILER、ZEPHYR_TOOLCHAIN_VARIANT等关键词看实际生效的值是什么。手动指定工具链路径如果自动检测失败可以在west build时加参数west build -b stm32f103c8t6 -- -DCMAKE_C_COMPILER/path/to/arm-none-eabi-gcc6.3 生产环境下的变量管理如果要在多项目或多机器上使用建议用环境管理方式Windows用setx命令永久设置变量或写一个setup_env.bat脚本每次开发前执行。Linux把变量定义放在~/.zephyrrc文件里每次启动 shell 时自动 source。示例~/.zephyrrcexport ZEPHYR_BASE~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb export GNUARMEMB_TOOLCHAIN_PATH/usr/local/gcc-arm-13.2 export PATH$GNUARMEMB_TOOLCHAIN_PATH/bin:$PATH然后在~/.bashrc里加一行[ -f ~/.zephyrrc ] source ~/.zephyrrc7. 从环境变量延伸到项目配置环境变量配稳之后Zephyr 项目的可移植性就靠配置文件了。这里简单提几个和变量相关的配置点。7.1 板型配置中的工具链覆盖每个板型目录下的board.cmake可以覆盖全局工具链设置。例如如果某个板型必须用特定版本 GCC可以在板型配置里写set(TOOLCHAIN_ROOT /path/to/specific/toolchain)但一般情况下用全局环境变量就够了。7.2 应用项目中的变量使用在你的应用项目里可以通过CMakeLists.txt读取环境变量if(DEFINED ENV{MY_CUSTOM_VAR}) set(MY_CUSTOM_VAR $ENV{MY_CUSTOM_VAR}) endif()这在需要区分开发、测试、生产环境时有用。7.3 与 CI/CD 集成在 GitHub Actions 或 GitLab CI 中环境变量通过 YAML 配置env: ZEPHYR_BASE: ${{ github.workspace }}/zephyr ZEPHYR_TOOLCHAIN_VARIANT: gnuarmemb确保 CI 环境中的工具链路径和本地一致。环境变量看起来简单但却是 Zephyr 项目能跨平台编译的基础。实际项目中我建议把变量配置写成文档或脚本新成员加入时直接执行就能跑通环境减少手动配置带来的不一致问题。最稳妥的做法是先用最小示例验证环境变量和编译流程再开始正式项目开发。如果遇到问题先回退到 hello_world 示例确认基础环境没问题再排查项目特定配置。