1. 为什么值得花时间搭好这套开发环境嵌入式实时操作系统这个圈子Zephyr 这两年被讨论得越来越多。原因不复杂它不像某些老牌 RTOS 那样只给你一个调度器就撒手不管也不像某些大块头系统那样把资源吃得干干净净。Zephyr 的定位很讨巧它把内核、驱动、协议栈、构建系统全都打包好了同时又能把镜像压到几十 KB 级别跑在只有几十 KB RAM 的芯片上。这种既要又要的能力让它在物联网终端、可穿戴设备、工业传感器这些场景里越来越吃香。但问题也恰恰出在这里。Zephyr 的构建系统用的是 CMake 加 Kconfig 加 Devicetree 的组合拳这套东西在 Linux 内核社区是标配可对于习惯了 Keil、IAR 那种点几下鼠标就能编译下载的嵌入式开发者来说第一次接触 Zephyr 的构建流程大概率会一脸懵。我见过太多人在环境搭建这一步就卡了整整两天最后放弃。所以这个系列的第 0 篇我不讲内核调度、不讲内存管理就老老实实把开发环境这件事讲透。这篇文章适合谁看如果你手里有一块支持 Zephyr 的开发板想跑通第一个 hello world或者你打算系统学习 Zephyr 内核但不知道从哪下手那这篇就是给你写的。如果你已经是老手也可以看看我在工具选型和踩坑上的经验说不定能帮你省点时间。整篇内容我会围绕工具链安装、SDK 配置、构建系统理解、第一个工程跑通这几个核心环节展开每一步都告诉你为什么这么做而不只是复制粘贴命令。2. 整体思路与工具选型拆解2.1 先搞清楚 Zephyr 的构建体系长什么样很多人搭环境失败根本原因不是命令敲错了而是没搞明白 Zephyr 的构建体系到底由哪几块组成。我先把这张地图画清楚后面操作起来就不会迷路。Zephyr 的构建流程大致是这样一条链路你的应用代码加上 Zephyr 内核源码经过CMake配置生成构建文件CMake 在配置阶段会调用Kconfig来解析所有的配置选项比如你要不要开网络协议栈、用哪个调度算法同时通过Devicetree来描述硬件信息比如哪个引脚接了 LED、串口用哪个外设。配置完成后CMake 调用工具链编译器、链接器把代码编译成可执行文件最后通过west这个命令行工具把镜像烧录到开发板。这里面有几个关键角色需要你记住westZephyr 的元工具负责管理多个代码仓库、执行构建和烧录命令。你可以把它理解成一个专门为 Zephyr 定制的 git 和构建命令的封装。CMake构建系统的核心负责生成 Makefile 或 Ninja 构建文件。Kconfig配置系统决定哪些功能被编译进最终镜像。Devicetree硬件描述系统告诉系统板子上有什么外设、怎么连接的。工具链真正干活的编译器Zephyr 官方推荐用 Zephyr SDK。理解这条链路的意义在于当构建报错时你能快速判断是配置问题Kconfig、硬件描述问题Devicetree、还是编译问题工具链而不是盲目地重装环境。2.2 工具链选型官方 SDK 还是自己编译这是第一个要做的选择。Zephyr 官方提供了预编译好的Zephyr SDK里面包含了多个架构的交叉编译器ARM、RISC-V、x86、ARC 等下载解压就能用。另一条路是自己用系统包管理器装交叉编译器比如在 Ubuntu 上装gcc-arm-none-eabi。我的建议很明确新手一律用官方 SDK。原因有三点。第一官方 SDK 里的编译器版本是经过 Zephyr 社区验证的不会出现某个版本编译器优化导致内核跑飞的问题。第二官方 SDK 包含了所有支持的架构你换一块不同架构的板子不用重新折腾工具链。第三自己装交叉编译器很容易遇到版本不匹配、库缺失的问题排查起来非常耗时。当然如果你有特殊需求比如公司要求统一使用某个特定版本的编译器那自己编译工具链也是可以的但这属于进阶操作第 0 篇不展开。2.3 操作系统选择Linux 优先Windows 有坑Zephyr 的开发体验在 Linux 上是最好的这不是偏见是事实。构建系统里大量的脚本是 shell 脚本文件路径处理也是 Unix 风格在 Linux 上跑最顺畅。macOS 也可以但偶尔会遇到一些 Homebrew 包版本的问题。Windows 用户怎么办官方推荐用WSL2Windows Subsystem for Linux在 WSL2 里装一个 Ubuntu然后按照 Linux 的流程走。我不建议在原生 Windows 上用 cmd 或 PowerShell 搭 Zephyr 环境虽然理论上可行但路径分隔符、脚本兼容性、串口设备访问这些问题会让你怀疑人生。用 WSL2 的话唯一需要注意的是串口设备的访问需要额外配置一下 usbipd 把 USB 设备透传进 WSL2这个后面会讲。2.4 版本管理用 west 还是纯 gitZephyr 项目由多个仓库组成主仓库zephyr、工具仓库、以及一堆 HAL 层仓库比如hal_stm32、hal_nordic。早期大家都是手动 git clone 一堆仓库非常痛苦。现在官方主推west来管理这些仓库一条west update命令就能把所有依赖仓库拉到正确的版本。所以我的建议是用 west不要手动 git clone。west 不仅能管理仓库还能执行构建和烧录命令是 Zephyr 开发的标准工作流。你只需要记住几个核心命令west init、west update、west build、west flash。3. 核心细节解析与实操要点3.1 依赖包的安装一个都不能少在开始装 Zephyr 之前系统层面有一堆依赖包要装。这些包分几类构建工具CMake、Ninja、Python3、设备树编译器dtc、烧录工具OpenOCD、pyocd、以及一些辅助工具git、wget、xz-utils。在 Ubuntu 22.04 上我通常用这一条命令搞定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 gcc-multilib \ g-multilib libsdl2-dev libmagic1这里有几个包值得单独说明。ccache是编译缓存工具Zephyr 编译一次可能要几分钟有了 ccache 第二次编译能快很多强烈建议装。gperf是 Kconfig 解析需要的不装会报错。libsdl2-dev是给模拟器用的如果你想在 PC 上跑 Zephyr 的 native_sim 目标这个必须有。device-tree-compiler就是 dtc处理 Devicetree 文件用的。注意不同 Ubuntu 版本包名可能略有差异如果某个包找不到先apt search一下确认名字。另外Python 版本建议用 3.8 以上太老的版本 pip 装包会有问题。3.2 Python 虚拟环境强烈建议隔离Zephyr 的构建脚本依赖大量 Python 包比如pyelftools、pykwalify、west本身也是 Python 包。如果你直接往系统 Python 里装很容易和系统其他工具冲突。所以我的做法是给 Zephyr 单独建一个 Python 虚拟环境。python3 -m venv ~/zephyr-venv source ~/zephyr-venv/bin/activate pip install --upgrade pip pip install west建好之后每次开发前先source一下激活环境。这个习惯看起来麻烦但能帮你避免 90% 的 Python 包冲突问题。我踩过的坑是有一次系统里装了个老版本的pyelftools导致 Zephyr 构建时解析 ELF 文件出错排查了半天才发现是版本冲突。从那以后我就老老实实用虚拟环境了。3.3 获取 Zephyr 源码west init 的正确姿势装好 west 之后下一步是把 Zephyr 源码拉下来。这里有个关键概念叫workspace工作区它是一个目录里面包含 Zephyr 主仓库和所有依赖仓库。mkdir ~/zephyrproject cd ~/zephyrproject west init . west updatewest init .会在当前目录初始化工作区默认拉取 Zephyr 主仓库的最新主分支。如果你需要特定版本比如某个 LTS 版本可以加--mr参数指定west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.5.0 .west update会读取主仓库里的west.yml文件把所有依赖仓库拉到对应版本。这一步会下载不少东西网络不好的话可能要等一会儿。下载完成后你的zephyrproject目录下会多出一堆文件夹每个对应一个 HAL 或模块仓库。提示west update支持--narrow参数只拉取当前需要的仓库能省不少时间和磁盘空间。但如果你后面要换板子可能还得重新拉所以我一般不用这个参数。3.4 导出环境变量让构建系统找到工具源码拉下来之后还需要让 shell 知道 Zephyr 的位置。Zephyr 提供了一个脚本zephyr-env.shsource 一下就会设置好ZEPHYR_BASE等环境变量。source ~/zephyrproject/zephyr/zephyr-env.sh但每次开新终端都 source 太麻烦我通常把这几行加到~/.bashrc里export ZEPHYR_BASE~/zephyrproject/zephyr export PATH~/zephyrproject/.venv/bin:$PATH source ~/zephyrproject/zephyr/zephyr-env.sh这样每次开终端环境就自动就绪了。注意ZEPHYR_BASE这个变量很关键west 和 CMake 都靠它定位 Zephyr 源码。3.5 安装 Python 依赖requirements 文件Zephyr 主仓库里有个scripts/requirements.txt文件列出了构建所需的 Python 包。在虚拟环境激活的状态下执行pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt这一步会装pyelftools、pykwalify、packaging、PyYAML等一堆包。如果网络慢可以加个国内镜像源加速。装完之后建议验证一下west --version能正常输出版本号就说明 west 和 Python 环境都没问题。3.6 安装 Zephyr SDK最后一块拼图前面都是准备工作真正干活的编译器还没装。Zephyr SDK 的安装方式这几年变过几次现在官方推荐用west sdk install命令west sdk install这个命令会自动下载最新版 SDK 并安装到默认位置通常是~/zephyr-sdk-version。如果你想指定版本或安装路径west sdk install --version 0.16.5 --install-dir ~/zephyr-sdk安装完成后需要设置ZEPHYR_SDK_INSTALL_DIR环境变量指向 SDK 目录。同样加到~/.bashrc里export ZEPHYR_SDK_INSTALL_DIR~/zephyr-sdk-0.16.5注意SDK 版本和 Zephyr 版本之间有兼容性要求。比如 Zephyr 3.5 建议用 SDK 0.16.xZephyr 3.6 建议用 0.16.5 以上。版本不匹配可能编译报错具体对应关系可以查 Zephyr 官方文档的 release notes。4. 实操过程与核心环节实现4.1 从零到第一个 hello world 的完整流程前面把各个组件都装好了现在把它们串起来跑通第一个工程。我以一块常见的 ARM Cortex-M 开发板为例假设你手里有一块 STM32 的板子具体型号不重要流程通用。第一步创建应用目录。Zephyr 的应用可以放在工作区外面也可以放在里面。我习惯放在工作区外面保持源码目录干净mkdir ~/my-zephyr-apps cd ~/my-zephyr-apps mkdir hello_world cd hello_world第二步创建应用源文件main.c#include zephyr/kernel.h int main(void) { printk(Hello, Zephyr!\n); return 0; }第三步创建CMakeLists.txtcmake_minimum_required(VERSION 3.20.0) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(hello_world) target_sources(app PRIVATE src/main.c)注意这里target_sources里的路径是src/main.c所以你需要把main.c放到src子目录下。这个目录结构是 Zephyr 的约定虽然可以改但建议遵循约定省得给自己找麻烦。第四步创建prj.conf配置文件。对于最简单的 hello world这个文件可以是空的但为了演示我们加一行CONFIG_PRINTKy这个配置项控制printk功能是否启用。虽然默认就是启用的但显式写出来更清晰。第五步构建。假设你的板子是nucleo_f401re这是 Zephyr 支持的板子之一west build -b nucleo_f401re-b参数指定板子名称。第一次构建会花几分钟因为要编译整个内核和驱动。构建成功后会在build/zephyr目录下生成zephyr.elf和zephyr.bin等文件。第六步烧录west flash如果你的板子接了调试器比如 ST-Linkwest 会自动调用 OpenOCD 把镜像烧进去。烧录完成后板子复位运行通过串口就能看到 Hello, Zephyr! 的输出。4.2 构建目录结构解析build 文件夹里有什么很多人构建完就不管了其实build目录里藏着很多有用的信息。我挑几个关键的说说。build/zephyr/zephyr.elf是带调试信息的可执行文件用 GDB 调试时加载的就是它。build/zephyr/zephyr.bin是纯二进制镜像烧录用。build/zephyr/zephyr.map是链接映射文件当你想知道某个函数占了多少空间、代码段怎么分布的就看这个文件。build/zephyr/.config是最终生效的配置它是 Kconfig 解析所有配置源prj.conf、板子默认配置、内核默认配置之后合并出来的结果。如果你不确定某个配置项最终是什么值直接看这个文件最准。build/zephyr/include/generated/devicetree_generated.h是根据 Devicetree 生成的 C 头文件里面定义了各种硬件相关的宏。比如你想知道 LED 对应的 GPIO 引脚号可以在这里找到。实操心得调试构建问题时我经常用west build -t menuconfig打开一个图形化配置界面可以直观地看到所有配置项和它们的依赖关系。这个工具对理解 Kconfig 非常有帮助。4.3 换板子怎么操作一次构建 vs 重新构建Zephyr 的构建系统有个特点如果你已经构建过一次想换一块板子直接west build -b 新板子可能会报错因为 build 目录里缓存了旧板子的配置。正确的做法是加-p参数强制重新构建west build -b 新板子 -p always-p always表示每次都清理 build 目录重新构建。如果你只是改了应用代码不需要加这个参数west 会增量编译速度快很多。但如果你改了prj.conf或者换了板子建议加上-p always避免缓存导致的诡异问题。我踩过的坑有一次改了prj.conf里的一个配置项构建成功但行为没变折腾半天才发现是 build 目录缓存了旧的配置。从那以后只要动了配置文件我就习惯性加-p always。4.4 串口查看输出minicom 还是 screen板子跑起来之后怎么看printk的输出需要用一个串口终端工具。Linux 上常用的有minicom、screen、picocom。我个人偏好picocom因为它轻量、命令简单picocom -b 115200 /dev/ttyACM0-b指定波特率Zephyr 默认是 115200。/dev/ttyACM0是串口设备名具体是哪个可以用ls /dev/tty*查看插拔板子前后对比一下就知道。如果你在 WSL2 里开发串口设备不会自动出现在/dev下需要用 usbipd 把 USB 设备透传进去。具体步骤是在 Windows 端用usbipd list找到设备然后usbipd attach --wsl --busid busid之后 WSL2 里就能看到/dev/ttyACM0了。注意用 picocom 退出是CtrlA然后CtrlX不是CtrlC。第一次用的人经常按CtrlC发现退不出去其实是按错了。4.5 用 native_sim 在 PC 上跑 Zephyr如果你手头暂时没有开发板或者想快速验证一些不依赖硬件的代码逻辑可以用 Zephyr 的native_sim目标直接在 PC 上把 Zephyr 当普通程序跑。west build -b native_sim ./build/zephyr/zephyr.exenative_sim会把 Zephyr 编译成一个 Linux 可执行文件printk的输出直接打到终端。这个目标特别适合学习内核 API比如你想试试信号量、消息队列怎么用不用烧板子直接 PC 上跑就行。但要注意native_sim里没有真实硬件所有驱动相关的代码都跑不了。5. 常见问题与排查技巧实录5.1 构建报错速查表环境搭建和构建过程中遇到的问题八成集中在下面这几类。我整理成表格方便你对照排查。报错信息关键词可能原因解决方法ZEPHYR_BASE not set环境变量没导出source zephyr-env.sh 或检查 .bashrcCMake Error: could not find toolchainSDK 路径没设对检查 ZEPHYR_SDK_INSTALL_DIRNo such file: west.ymlwest init 没执行或目录不对确认在 workspace 根目录执行 west updateModuleNotFoundError: No module named westPython 虚拟环境没激活source venv/bin/activateundefined reference to __device_dts_ordDevicetree 配置和驱动不匹配检查板子 overlay 文件region FLASH overflowed镜像太大超出 Flash裁剪配置关掉不用的功能board not found板子名称拼错用 west boards 列出所有支持的板子5.2 几个我踩过的坑和独家技巧坑一west update 卡住不动。这通常是网络问题某个仓库拉不下来。解决办法是设置 git 的超时和重试或者手动进到卡住的仓库目录里git pull。另外west update支持--fetch-opt参数传递 git 参数比如--fetch-opt--depth1可以浅克隆速度快很多。坑二编译报错说找不到某个头文件。这种情况多半是某个 HAL 模块没拉下来。检查west.yml里有没有对应的模块然后重新west update。如果模块在但还报错可能是模块版本和 Zephyr 主仓库不匹配试试west update --narrow重新同步。坑三烧录成功但板子没反应。先确认串口波特率对不对Zephyr 默认 115200但有些板子可能不一样。然后确认串口设备选对了插拔板子对比/dev/tty*的变化。如果都没问题可能是板子需要手动复位或者烧录后没自动运行按一下复位键试试。技巧一用 ccache 加速编译。装好 ccache 后在~/.bashrc里加export CCACHE_DIR~/.ccache然后 CMake 会自动检测并使用 ccache。第一次编译还是慢但第二次改代码后编译能快好几倍。技巧二用west build -t guiconfig可视化配置。这个和 menuconfig 类似但是图形界面适合不习惯终端操作的人。配置完保存会自动写入prj.conf。技巧三保留多个 build 目录。如果你经常在几块板子之间切换可以给每块板子单独建一个 build 目录比如build-f401、build-nrf52构建时用-d参数指定west build -b nucleo_f401re -d build-f401这样切换板子不用重新构建省时间。5.3 环境验证清单搭完环境后建议按这个清单逐项验证确保每个环节都正常west --version能输出版本号echo $ZEPHYR_BASE指向正确的源码目录echo $ZEPHYR_SDK_INSTALL_DIR指向正确的 SDK 目录west boards能列出支持的板子列表west build -b native_sim能成功构建./build/zephyr/zephyr.exe能运行并输出这六项都过了说明环境基本没问题可以开始正式开发了。如果哪一项没过回到对应章节检查。5.4 关于版本选择的一点经验Zephyr 的版本节奏是主分支持续更新每季度发一个正式版每年有一个 LTS 版本。我的建议是学习和新项目用最新的 LTS 版本比如 3.7.0 这种。LTS 版本经过充分测试bug 少社区支持周期长。主分支虽然功能新但可能遇到各种未修复的问题不适合新手。如果你要跟进最新特性可以主分支和 LTS 各拉一份用 west 的--mr参数切换。但注意不同版本的 API 可能有变化代码不一定能直接迁移。6. 后续可以怎么扩展这套环境环境搭好只是第一步接下来你可能会想怎么调试怎么加自己的驱动怎么做单元测试这些都属于后续内容。就环境本身而言还有几个方向可以扩展。一是集成 IDE。虽然命令行构建是 Zephyr 的标准方式但很多人还是习惯用 IDE 写代码。VS Code 配合 Zephyr 的 CMake 插件可以做到代码补全和调试配置起来也不复杂。关键是让 VS Code 能找到compile_commands.json这个文件在 build 目录下west 构建时会自动生成。二是搭建 CI 流程。如果你在做团队项目可以把 Zephyr 构建集成到 CI 里每次提交自动编译测试。Zephyr 官方提供了 Docker 镜像里面环境都配好了用起来很方便。三是多板子管理。当你手头板子多了可以写个脚本自动切换板子、构建、烧录省得每次敲一长串命令。我自己写了个简单的 shell 脚本把常用板子的构建命令封装成函数用起来顺手很多。这套环境我前前后后在几台机器上搭过每次都会遇到一些小问题但整体流程是稳定的。关键是要理解每个组件的作用而不是死记命令。理解了构建链路遇到报错你就能快速定位是哪一环出了问题。环境这件事一次搭好后面就能安心写代码了。