Zephyr RTOS环境变量配置实战：STM32F103C8T6开发指南

如果你正在尝试把 Zephyr RTOS 跑在 STM32F103C8T6 这种常见的最小系统板上，环境变量配置往往是第一个实际门槛。很多人卡在这一步，不是因为 Zephyr 本身复杂，而是因为环境变量没配对，导致工具链找不到、编译报错、烧录失败。

这篇文章会直接带你走一遍我在实际项目里验证过的配置流程，重点不是讲 Zephyr 多强大，而是让你能在普通 Windows 或 Linux 环境下，把基础环境变量配对，顺利编译并烧录一个示例程序到 STM32F103C8T6 板上。

1. 先搞清楚 Zephyr 环境变量到底管什么

Zephyr 的环境变量核心是告诉系统三件事：工具链在哪、SDK 在哪、当前项目怎么找依赖。很多人一上来就照搬教程设置ZEPHYR_BASE，但经常忽略工具链路径和 CMake 变量，导致编译时找不到编译器或头文件。

1.1 关键变量清单

这几个变量必须设对，缺一不可：

• ZEPHYR_BASE: Zephyr 源码根目录路径，编译时 CMake 靠它定位内核和模块。
• ZEPHYR_TOOLCHAIN_VARIANT: 工具链类型，比如gnuarmemb（ARM 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_BASE（Linux/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 用户配置步骤

1. 右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
2. 在“系统变量”部分，新建或编辑以下变量：

3. 找到系统变量Path，双击编辑，在末尾添加：

   • %GNUARMEMB_TOOLCHAIN_PATH%\bin
   • %ZEPHYR_BASE%\scripts

4. 全部确认后，重新打开一个命令提示符，让变量生效。

3.2 Linux 用户配置步骤

把以下内容加到~/.bashrc或~/.zshrc（根据你用的 shell）：

export ZEPHYR_BASE=~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb 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 示例

进入示例目录，指定板型为stm32f103c8t6（Zephyr 内置支持这个板型）：

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 的 PA13（SWDIO）
• ST-Link 的 SWCLK 接 STM32 的 PA14（SWCLK）
• GND 接 GND，3.3V 接 3.3V

接好后，给板子上电，ST-Link 指示灯应该亮起。

5.2 烧录命令

在 hello_world 示例目录下执行：

west flash

如果一切正常，west 会自动检测 ST-Link 并烧录zephyr.hex或zephyr.bin文件。

5.3 验证输出

STM32F103C8T6 没有默认串口输出，但你可以接一个 USB 转 TTL 模块：

• PA9（TX）接 TTL 模块的 RX
• PA10（RX）接 TTL 模块的 TX
• GND 接 GND

用串口工具（如 PuTTY、minicom）打开对应串口，波特率设 115200，复位板子，应该能看到 "Hello World! stm32f103c8t6" 输出。

如果没输出，先检查接线，再看烧录时是否有错误提示。

6. 环境变量相关的深度排查

即使按照上面步骤走，有时还是会遇到环境变量导致的问题。这里把我自己排查时的顺序列出来。

6.1 变量未生效的排查顺序

1. 确认终端会话是新开的：修改环境变量后，必须新开终端窗口，否则老会话读不到新变量。
2. 检查变量值是否被覆盖：比如在~/.bashrc里设了，但~/.profile或系统级配置里有冲突设置。
3. 路径中是否有空格或特殊字符：尽量用纯英文路径，避免Program Files这种带空格的目录。
4. 变量名拼写错误：比如ZEPHYR_BASE写成ZEPHYR_BASE_PATH。

6.2 编译阶段变量问题

如果编译报错提到工具链或 SDK，按这个顺序查：

1. 运行west build -t run：这个命令会打印详细的 CMake 变量和工具链检测结果，比普通编译输出更全。
2. 检查build/CMakeCache.txt：搜索CMAKE_C_COMPILER、ZEPHYR_TOOLCHAIN_VARIANT等关键词，看实际生效的值是什么。
3. 手动指定工具链路径：如果自动检测失败，可以在west build时加参数：

   west build -b stm32f103c8t6 -- -DCMAKE_C_COMPILER=/path/to/arm-none-eabi-gcc

6.3 生产环境下的变量管理

如果要在多项目或多机器上使用，建议用环境管理方式：

• Windows：用setx命令永久设置变量，或写一个setup_env.bat脚本，每次开发前执行。
• Linux：把变量定义放在~/.zephyrrc文件里，每次启动 shell 时自动 source。

示例~/.zephyrrc：

export ZEPHYR_BASE=~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb export GNUARMEMB_TOOLCHAIN_PATH=/usr/local/gcc-arm-13.2 export PATH=$GNUARMEMB_TOOLCHAIN_PATH/bin:$PATH

然后在~/.bashrc里加一行：

[ -f ~/.zephyrrc ] && source ~/.zephyrrc

7. 从环境变量延伸到项目配置

环境变量配稳之后，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 示例确认基础环境没问题，再排查项目特定配置。