企业官网建设流程全解析

摘要：本文面向第一次接触 Zephyr 的嵌入式开发者，介绍 Zephyr、Kconfig、设备树、west 和 Zephyr SDK 的作用，并严格参考官方入门流程，在 Ubuntu 上搭建开发环境。后半部分使用官方samples/basic/blinky示例和 Nucleo F401RE 开发板，演示编译、烧录、串口观察及常见问题排查。

标签：Zephyr、RTOS、嵌入式开发、STM32、Nucleo

如果你之前主要使用裸机、HAL 库或厂商 IDE，第一次打开 Zephyr 源码时，很容易被west、Kconfig、设备树和大量仓库目录绕晕。本文先把这些概念梳理清楚，再完全使用 Zephyr 官方自带的 Blinky 示例完成第一次编译和烧录。

本文选择 Nucleo F401RE 作为演示开发板，原因很简单：Zephyr 官方持续维护该板卡，板载用户 LED 已配置为led0，同时自带 ST-LINK/V2-1，不需要额外连接下载器。

一、Zephyr 是什么

Zephyr 是面向资源受限设备的开源实时操作系统，不只是一个普通的外设库。它提供线程调度、同步机制、内存管理、统一驱动模型、网络协议、USB、文件系统、电源管理等组件，并支持 ARM、RISC-V、x86 等多种架构。

传统单片机工程经常把时钟、GPIO、驱动和业务代码混在一起。Zephyr 更强调分层：

最值得先记住的一句话是：设备树描述硬件，Kconfig 选择功能，C/C++ 代码实现业务。

二、Zephyr 工作区为什么有很多目录

Zephyr 使用 west 管理多仓库工作区。执行west init和west update后，典型目录如下：

zephyrproject/ ├── .west/ # west 工作区配置 ├── .venv/ # Python 虚拟环境 ├── zephyr/ # Zephyr 主仓库和官方示例 ├── modules/ # 芯片厂商 HAL、协议栈和第三方模块 ├── bootloader/ # MCUboot 等启动程序 ├── tools/ # 部分辅助工具 └── ...

.west/所在目录是工作区根目录。Zephyr 主仓库中的west.yml是 manifest 文件，记录需要拉取的模块、路径和版本。west 会根据该文件让整个工作区保持一致。

常用命令可以先记住这几个：

west topdir# 显示工作区根目录west list# 显示工作区中的项目west update# 按 manifest 更新依赖west build# 编译应用west flash# 烧录应用west debug# 启动调试

三、Ubuntu 开发环境安装

Zephyr 最新官方入门文档以 Ubuntu 24.04 LTS 及以上版本为主要演示环境。当前文档列出的关键最低版本为：

如果使用 Ubuntu 22.04 或其他发行版，系统仓库中的 Python、CMake 可能偏旧，需要根据官方 Linux Host Dependencies 文档单独升级。

1. 更新系统

sudoaptupdatesudoaptupgrade

2. 安装主机依赖

以下命令来自 Zephyr 官方 Ubuntu 安装流程：

sudoaptinstall--no-install-recommends\gitcmake ninja-build gperf ccache dfu-util\device-tree-compilerwgetpython3-dev python3-venv python3-tk\xz-utilsfilemakegcc gcc-multilib g++-multilib\libsdl2-dev libmagic1

如果主机是 AArch64/ARM64，官方文档提示可能没有gcc-multilib和g++-multilib，此时可以从命令中移除这两个包。

安装后检查关键版本：

cmake--versionpython3--versiondtc--versionninja--version

不要跳过版本检查。很多“west 安装成功但 CMake 配置失败”的问题，本质上是 Ubuntu 版本较旧，系统自带 CMake 或 Python 不满足当前 Zephyr 要求。

四、创建 Python 虚拟环境

建议把 Zephyr 的 Python 包放进独立虚拟环境，避免和系统 Python 冲突：

mkdir-p~/zephyrproject python3-mvenv ~/zephyrproject/.venvsource~/zephyrproject/.venv/bin/activate python-mpipinstall--upgradepip pipinstallwest

激活后，终端提示符通常会出现(.venv)。检查 west：

west--version

以后每次打开新终端，都需要重新激活环境：

source~/zephyrproject/.venv/bin/activate

如果忘记这一步，可能出现west: command not found，或者误用另一套 Python 环境。

五、下载 Zephyr 源码和依赖

使用 Zephyr 官方仓库创建工作区：

west init-mhttps://github.com/zephyrproject-rtos/zephyr ~/zephyrprojectcd~/zephyrproject west update

west init主要完成两件事：创建.west/，并把 Zephyr 设置为 manifest 仓库。west update才会根据west.yml下载 HAL、库和其他模块，因此第一次执行会花费较长时间并占用较多磁盘空间。

安装与当前源码版本匹配的 Python 依赖：

west packages pip--install

再把当前 Zephyr 注册为 CMake package：

west zephyr-export

最后检查工作区：

west topdir west list zephyr

预期的工作区根目录是~/zephyrproject，Zephyr 主仓库位于~/zephyrproject/zephyr。

六、安装 Zephyr SDK

Zephyr SDK 提供目标架构对应的编译器和调试工具。进入 Zephyr 仓库后先查看可安装版本：

cd~/zephyrproject/zephyr west sdk list

本文只编译 ARM 开发板，可以只安装 ARM 工具链，减少下载量：

west sdkinstall--toolchainsarm-zephyr-eabi

如果准备同时开发其他架构，也可以直接安装默认 SDK：

west sdkinstall

安装后，正常执行west build时，CMake 会自动查找 Zephyr SDK。一般不需要手动写完整的 GCC 路径。

七、认识官方 Blinky 示例

本文使用的示例位于：

zephyr/samples/basic/blinky/ ├── CMakeLists.txt ├── README.rst ├── prj.conf └── src/main.c

Blinky 的功能非常简单：

1. 从设备树led0alias 获取 LED 的 GPIO 配置；
2. 把 GPIO 配置为输出；
3. 在循环中翻转电平，让 LED 持续闪烁；
4. 在控制台打印 LED 当前状态。

这个示例虽小，但同时验证了编译器、内核、设备树、GPIO 驱动、系统时钟、下载工具和目标板运行状态，很适合做环境验收。

官方示例要求开发板存在用户 LED，并且设备树已经定义led0。Nucleo F401RE 的板载用户灯 LD2 连接到 PA5，Zephyr 板卡定义已完成对应配置。

八、编译 Blinky 示例

确保虚拟环境已经激活，然后进入 Zephyr 根目录：

source~/zephyrproject/.venv/bin/activatecd~/zephyrproject/zephyr

先确认板卡名称：

west boards|grepnucleo_f401re

执行官方示例构建：

west build-palways-bnucleo_f401re samples/basic/blinky

参数含义如下：

• -p always：构建前清理旧缓存，适合第一次构建或切换开发板；
• -b nucleo_f401re：选择 Nucleo F401RE 板卡；
• samples/basic/blinky：应用源码目录。

成功后，默认构建目录为~/zephyrproject/zephyr/build。主要产物位于build/zephyr/：

可以查看镜像大小：

arm-zephyr-eabi-size build/zephyr/zephyr.elf

本文命令已使用 Zephyr 4.4.99、Zephyr SDK 1.0.1 实际构建通过，结果为：

FLASH: 18160 B / 512 KB（3.46%） RAM: 4544 B / 96 KB（4.62%）

后续只修改了少量源代码时，可以直接运行增量构建：

west build

如果切换板卡、修改设备树或遇到缓存异常，重新执行带-p always的完整命令。

九、使用 ST-LINK 烧录开发板

Nucleo F401RE 自带 ST-LINK/V2-1。使用板载 ST-LINK USB 接口连接电脑，不需要另外连接 SWDIO、SWCLK。

1. 查看可用 runner

west flash--context

Zephyr 官方板卡文档显示，该开发板默认 flash runner 是 STM32CubeProgrammer，同时也支持 OpenOCD 和 J-Link。

2. 使用默认 runner

安装 STM32CubeProgrammer 并确保STM32_Programmer_CLI位于PATH后执行：

west flash

west 会使用当前build/目录中的固件，烧录前默认还会检查是否需要重新编译。

3. 使用 OpenOCD

如果没有安装 STM32CubeProgrammer，可以尝试 Zephyr 板卡支持的 OpenOCD runner：

west flash--runneropenocd

也可以使用缩写：

west flash-ropenocd

需要指定其他构建目录时，使用-d：

west flash-dbuild-ropenocd

烧录成功后，开发板会复位并开始运行 Blinky，板载 LD2 应持续闪烁。

十、查看串口输出

Nucleo F401RE 的 Zephyr 默认控制台使用 UART2，并通过板载 ST-LINK 虚拟串口连接到主机，默认参数为 115200、8N1。

先查看设备节点：

ls-l/dev/ttyACM*

安装并打开串口工具：

sudoaptinstallminicom minicom-D/dev/ttyACM0-b115200

如果当前用户没有串口权限：

sudousermod-aGdialout"$USER"

执行后注销并重新登录，再打开串口。Blinky 运行时会输出 LED 状态信息，能够同时观察到“LED 闪烁”和“串口日志”，说明程序已经在目标板正常执行。

十一、常见问题排查

问题 1：west: command not found

先激活虚拟环境：

source~/zephyrproject/.venv/bin/activatewhichwest west--version

问题 2：CMake 或 Python 版本过低

重新检查：

cmake--versionpython3--version

当前官方入门文档要求 CMake 不低于 3.28.0、Python 不低于 3.12。旧版 Ubuntu 的系统包不一定满足要求，应先升级工具，而不是反复修改示例源码。

问题 3：提示未知板卡

Board not found: nucleo_f401re

检查当前目录是否位于正确的 west 工作区，并确认依赖已经更新：

cd~/zephyrproject west topdir west updatecdzephyr west boards|grepnucleo_f401re

问题 4：Blinky 提示没有led0

官方 Blinky 要求目标板存在用户 LED，并在设备树中定义led0alias。若换成其他开发板，先打开其 Zephyr 板卡文档确认是否满足要求；没有板载 LED 时需要添加 overlay，不能简单照抄 GPIO 编号。

问题 5：切换开发板后仍使用旧配置

删除旧缓存重新构建：

west build-palways-bnucleo_f401re samples/basic/blinky

也可以清理当前构建目录：

west build-tpristine

问题 6：找不到烧录 runner

先查看构建目录支持的 runner：

west flash--context

如果默认 STM32CubeProgrammer 不可用，可以安装该工具，或者明确选择 OpenOCD：

west flash-ropenocd

问题 7：普通用户无法访问 ST-LINK 或串口

先用lsusb和dmesg确认设备是否被主机识别：

lsusbsudodmesg|tail-50

如果使用sudo west flash才能烧录，说明通常是 udev 权限问题。应安装调试器对应的 udev 规则并重新插拔设备，不建议长期用 root 身份维护整个 Zephyr 工作区。

十二、从编译到运行的检查清单

第一次搭建环境时，可以按下面的顺序逐项确认：

主机工具版本满足要求 ↓ Python 虚拟环境已激活 ↓ west update 下载完成 ↓ Zephyr SDK 可被 CMake 找到 ↓ west boards 能找到目标板 ↓ west build 生成 zephyr.elf/hex/bin ↓ west flash 成功写入并复位 ↓ 板载 LED 闪烁，串口输出正常

不要把“编译成功”和“开发板运行正常”当作同一个检查点。编译只证明软件能够生成镜像；runner、USB 权限、调试器、供电和开发板配置仍需要分别验证。

总结

Zephyr 的入门主线可以归纳为五步：

# 1. 创建工作区west init-mhttps://github.com/zephyrproject-rtos/zephyr ~/zephyrproject# 2. 下载依赖cd~/zephyrproject west update west packages pip--install# 3. 安装 SDKcdzephyr west sdkinstall--toolchainsarm-zephyr-eabi# 4. 编译官方 Blinkywest build-palways-bnucleo_f401re samples/basic/blinky# 5. 烧录west flash

完成 Blinky 闭环后，再开始修改设备树、Kconfig 和业务代码，会比直接从复杂项目入手更容易定位问题。遇到报错时，优先判断它属于环境、构建、烧录还是运行阶段，排查思路会清晰很多。

参考资料

• Zephyr Getting Started Guide：https://docs.zephyrproject.org/latest/develop/getting_started/index.html
• Blinky 官方示例：https://docs.zephyrproject.org/latest/samples/basic/blinky/README.html
• Nucleo F401RE 板卡文档：https://docs.zephyrproject.org/latest/boards/st/nucleo_f401re/doc/index.html
• west 编译、烧录与调试：https://docs.zephyrproject.org/latest/develop/west/build-flash-debug.html