在实际嵌入式开发中Zephyr RTOS 因其高度模块化、跨平台特性和对多种硬件架构的广泛支持正成为越来越多开发者的选择。但很多初学者在搭建 Zephyr 开发环境时往往卡在环境变量配置这一步尤其是结合特定硬件如 STM32F103C8T6 最小系统板时更容易因环境问题导致编译失败、烧录异常。本文将以 STM32F103C8T6 最小系统板为目标硬件完整演示如何在 Windows 或 Linux 环境下正确配置 Zephyr 所需的开发环境变量并运行一个基础示例项目帮助读者理解环境变量在 Zephyr 开发链路中的具体作用。1. 理解 Zephyr 环境变量的作用与必要性Zephyr 项目依赖一系列环境变量来定位工具链、源码路径、硬件支持包和构建配置。如果这些变量未正确设置会导致 CMake 无法找到编译器、找不到目标板定义、无法生成正确的镜像文件等一连串问题。1.1 核心环境变量及其职责在 Zephyr 开发中以下几个环境变量最为关键ZEPHYR_BASE指向 Zephyr 源码根目录构建系统通过它来定位内核源码、板级支持包BSP、设备树和各类配置文件。ZEPHYR_TOOLCHAIN_VARIANT指定使用的工具链类型常见值包括gnuarmembGNU Arm Embedded、zephyrZephyr SDK、xtoolsXilinx 工具链等。GNUARMEMB_TOOLCHAIN_PATH当选择gnuarmemb工具链时此变量需指向 GNU Arm Embedded Toolchain 的安装路径。除了上述三个还有ZEPHYR_SDK_INSTALL_DIRZephyr SDK 路径、ESP_IDF_PATHESP32 开发框架路径等但针对 STM32F103C8T6 这类 ARM Cortex-M3 内核芯片主要关注前三个即可。1.2 为什么不能只靠 IDE 或项目配置有些集成环境如 Zephyr 的 VS Code 扩展可以自动管理部分环境变量但在以下场景中手动配置环境变量仍是必要的命令行编译和调试持续集成CI环境多项目并行开发时避免路径冲突使用自定义工具链或修改核心源码理解每个变量的作用有助于在出现路径相关错误时快速定位问题。2. 环境准备工具链与源码获取在配置环境变量前需要先准备好必要的软件和源码。以下步骤以 Windows 为例Linux 类似主要差异在路径格式和包管理工具。2.1 安装 GNU Arm Embedded ToolchainSTM32F103C8T6 使用 ARM Cortex-M3 内核因此需要 ARM 架构的交叉编译工具链。推荐使用 GNU Arm Embedded Toolchain。访问 ARM 官方下载页面 选择适合操作系统的版本例如gcc-arm-none-eabi-10.3-2021.10-win32.exe。安装时建议选择不含空格的路径如C:\gnuarmemb。避免使用Program Files这类路径可减少因空格引发的解析问题。记录安装路径后续配置环境变量时会用到。2.2 获取 Zephyr 源码Zephyr 源码可以通过 Git 克隆建议选择稳定版本以避免兼容性问题。# 打开命令行Windows 可用 Git Bash 或 PowerShell git clone https://github.com/zephyrproject-rtos/zephyr cd zephyr # 切换到稳定分支例如 v3.4.0 git checkout v3.4.0同样建议将源码放在无空格路径下如C:\zephyrproject。2.3 安装 Python 依赖Zephyr 的构建系统依赖 Python 3.8 或更高版本以及若干 Python 包。# 进入 Zephyr 源码目录 cd zephyr # 使用 pip 安装依赖建议使用虚拟环境 pip install -r scripts/requirements.txt2.4 确认 STM32F103C8T6 支持Zephyr 主线已包含 STM32F103C8T6 的最小系统板定义对应板级配置文件为boards/arm/stm32f103c8t6。可通过以下命令确认ls boards/arm/stm32f103c8t6应看到board.cmake、Kconfig.board、Kconfig.defconfig等文件。3. 配置环境变量环境变量配置方式因操作系统而异下面分别说明 Windows 和 Linux 下的配置方法。3.1 Windows 系统配置在 Windows 中可以通过系统属性图形界面或命令行设置环境变量。通过图形界面设置永久生效右键“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”部分点击“新建”添加以下变量变量名变量值说明ZEPHYR_BASEC:\zephyrproject\zephyr指向 Zephyr 源码根目录ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb指定使用 GNU Arm Embedded 工具链GNUARMEMB_TOOLCHAIN_PATHC:\gnuarmemb指向 GNU Arm Embedded 工具链安装目录找到系统变量Path双击编辑在末尾添加工具链的bin目录路径C:\gnuarmemb\bin。通过命令行临时设置仅当前会话有效set ZEPHYR_BASEC:\zephyrproject\zephyr set ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb set GNUARMEMB_TOOLCHAIN_PATHC:\gnuarmemb set PATH%GNUARMEMB_TOOLCHAIN_PATH%\bin;%PATH%3.2 Linux 系统配置在 Linux 中通常将环境变量添加到 shell 配置文件中如~/.bashrc或~/.zshrc。# 编辑 ~/.bashrc nano ~/.bashrc # 在文件末尾添加以下行 export ZEPHYR_BASE~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb export GNUARMEMB_TOOLCHAIN_PATH/opt/gnuarmemb export PATH$GNUARMEMB_TOOLCHAIN_PATH/bin:$PATH # 使配置生效 source ~/.bashrc3.3 验证环境变量配置配置完成后打开新的命令行窗口执行以下命令验证# 检查 ZEPHYR_BASE echo %ZEPHYR_BASE% # Windows echo $ZEPHYR_BASE # Linux # 检查工具链是否在 PATH 中 arm-none-eabi-gcc --version正常应输出 GCC 版本信息如gcc version 10.3.1 20210824 (release)。4. 构建与烧录示例项目环境变量配置正确后可以尝试构建一个简单示例来验证整个工具链。4.1 构建 Blinky 示例Zephyr 提供了丰富的示例项目其中blinky是最简单的 LED 闪烁程序适合验证基础功能。# 进入示例目录 cd %ZEPHYR_BASE%\samples\basic\blinky # Windows cd $ZEPHYR_BASE/samples/basic/blinky # Linux # 创建构建目录并生成构建文件 mkdir build cd build cmake -DBOARDstm32f103c8t6 .. # 开始编译 make编译成功后会在build\zephyr目录下生成zephyr.bin、zephyr.hex等文件。4.2 关键构建参数说明在 CMake 配置阶段-DBOARDstm32f103c8t6指定了目标硬件板。Zephyr 会根据该名称在boards/目录下查找对应的板级配置。如果编译过程中出现工具链找不到或路径错误通常是因为环境变量未正确设置或未在新命令行窗口中生效。常见的错误信息包括-- The C compiler identification is unknown CMake Error at CMakeLists.txt:5 (project): No toolchain specified.4.3 烧录到 STM32F103C8T6 最小系统板STM32F103C8T6 最小系统板通常通过串口或 ST-Link 进行烧录。以下以常用的 ST-Link 为例安装 OpenOCD开源片上调试工具# Windows 可下载预编译版本Linux 通过包管理器安装 # Ubuntu/Debian sudo apt install openocd # 或使用 Zephyr SDK 自带的 OpenOCD使用 west 工具烧录Zephyr 推荐# 在构建目录下执行 west flashwest是 Zephyr 的项目管理工具它会自动根据板级配置选择适当的烧录方式和参数。手动使用 OpenOCD 烧录openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c program build/zephyr/zephyr.hex verify reset exit4.4 验证运行结果烧录完成后STM32F103C8T6 最小系统板上的 LED通常连接在 PC13 引脚应开始闪烁。如果板载无 LED可通过逻辑分析仪或示波器测量 PC13 引脚信号确认。5. 常见环境变量相关问题排查即使按照上述步骤配置实际项目中仍可能遇到各种环境问题。下面列出几个典型问题及解决方案。5.1 工具链找不到或版本不匹配问题现象可能原因检查方式解决建议arm-none-eabi-gcc: command not foundPATH 未设置或设置错误echo %PATH%或echo $PATH确认工具链 bin 目录已加入 PATH并重新打开命令行unsupported GCC version工具链版本过旧或过新arm-none-eabi-gcc --versionZephyr 对工具链版本有要求查看文档选择兼容版本5.2 板级配置找不到问题现象可能原因检查方式解决建议Unknown board: stm32f103c8t6板级定义不存在或 ZEPHYR_BASE 错误ls %ZEPHYR_BASE%/boards/arm/确认 ZEPHYR_BASE 指向正确板级名称拼写正确5.3 权限问题Linux问题现象可能原因检查方式解决建议permission deniedwhen flashing用户无访问调试设备权限ls -l /dev/ttyUSB*或ls -l /dev/stlink*将用户加入 dialout 或 plugdev 组sudo usermod -a -G dialout $USER5.4 多环境变量冲突当系统存在多个工具链或多个 Zephyr 版本时可能因环境变量冲突导致构建失败。解决方案使用虚拟环境或容器隔离不同项目环境在项目目录下使用.env文件局部设置环境变量在构建脚本中显式设置路径而非依赖全局环境变量6. 生产环境下的最佳实践在个人学习环境基础上团队协作或生产环境还需要考虑以下因素。6.1 环境版本固化为避免因工具链或 Zephyr 版本更新引入的不兼容建议固化关键组件的版本使用特定版本的 GNU Arm Embedded Toolchain如 10.3.2021.10锁定 Zephyr 版本通过 Git Tag 或特定提交记录依赖版本号便于新成员快速搭建一致环境6.2 自动化环境配置对于团队项目建议提供自动化配置脚本Windows 批处理示例setup_env.batecho off set ZEPHYR_BASEC:\zephyrproject\zephyr set ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb set GNUARMEMB_TOOLCHAIN_PATHC:\gnuarmemb set PATH%GNUARMEMB_TOOLCHAIN_PATH%\bin;%PATH% echo Environment variables set for Zephyr development.Linux Shell 脚本示例setup_env.sh#!/bin/bash export ZEPHYR_BASE~/zephyrproject/zephyr export ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb export GNUARMEMB_TOOLCHAIN_PATH/opt/gnuarmemb export PATH$GNUARMEMB_TOOLCHAIN_PATH/bin:$PATH echo Environment variables set for Zephyr development.6.3 持续集成环境配置在 CI 环境中如 GitHub Actions、GitLab CI需要在流水线中正确设置环境变量# GitHub Actions 示例 jobs: build: runs-on: ubuntu-latest steps: - name: Set up environment run: | echo ZEPHYR_BASE$GITHUB_WORKSPACE/zephyr $GITHUB_ENV echo ZEPHYR_TOOLCHAIN_VARIANTgnuarmemb $GITHUB_ENV echo GNUARMEMB_TOOLCHAIN_PATH/opt/gnuarmemb $GITHUB_ENV echo /opt/gnuarmemb/bin $GITHUB_PATH6.4 环境健康检查清单在开始新项目或接手现有项目时建议按以下清单验证环境配置[ ] ZEPHYR_BASE 指向正确的 Zephyr 源码目录[ ] ZEPHYR_TOOLCHAIN_VARIANT 与实际使用的工具链匹配[ ] 工具链路径变量如 GNUARMEMB_TOOLCHAIN_PATH已设置且路径存在[ ] 工具链 bin 目录已加入 PATH[ ] Python 依赖已安装可通过pip list检查[ ] 目标板级定义存在于 Zephyr 源码中[ ] 烧录工具OpenOCD、pyOCD 等已安装且版本兼容[ ] 调试器硬件ST-Link、J-Link 等可被系统识别7. 扩展学习方向掌握基础环境配置后可以进一步探索 Zephyr 的更高级功能学习使用 west 工具管理多仓库项目了解 Zephyr 的设备树DTS配置自定义硬件引脚功能研究 Kconfig 系统掌握内核配置和模块化编译尝试为 Zephyr 添加新的板级支持包BSP探索 Zephyr 的电源管理、网络协议栈等高级功能对于 STM32F103C8T6 specifically可以结合具体外设如 UART、I2C、SPI、ADC深入学习 Zephyr 的设备驱动模型编写实际应用代码。环境变量配置虽是 Zephyr 开发中的基础环节但正确理解其作用机制能为后续开发节省大量排查时间。建议在初次配置成功后保留一份环境记录便于后续重装系统或切换设备时快速恢复工作环境。