第2章开发环境搭建

2. 开发环境搭建：Zephyr SDK安装、west工具链配置、创建第一个Zephyr工程、编译与烧录

好，咱们正式开始动手了。这一章我带你把开发环境搭起来。说实话，很多初学者卡在这一步就放弃了——不是Zephyr有多难，而是环境配置确实有点绕。别急，我踩过的坑都帮你标记好了。

2.1 Zephyr SDK安装：别选错版本

Zephyr SDK不是普通的编译器，它包含了交叉编译工具链、调试器、QEMU模拟器等一系列工具。我个人习惯把SDK放在/opt目录下，这样所有用户都能用。

⚠️ 版本匹配很重要

Zephyr SDK的版本必须与Zephyr RTOS主版本匹配。比如你用Zephyr 3.5，就下载SDK 0.16.x。我曾经因为版本不匹配，编译出来的固件跑起来就死机，查了两天才发现是SDK版本问题。

安装步骤其实很简单：

从Zephyr官网下载对应系统的SDK安装包（Linux推荐.tar.gz格式）
解压到目标目录：sudo tar xvf zephyr-sdk-0.16.1_linux-x86_64.tar.gz -C /opt
运行安装脚本：cd /opt/zephyr-sdk-0.16.1 && sudo ./setup.sh
设置环境变量：在~/.bashrc或~/.zshrc中添加export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk-0.16.1

💡 小技巧

如果你用的是Ubuntu 22.04或更新版本，记得先安装依赖包：sudo apt install cmake ninja-build gperf python3-dev。少了这些，setup脚本会报错。

2.2 west工具链配置：Zephyr的瑞士军刀

west是Zephyr的元工具，说白了就是帮你管理代码、配置、编译、烧录的一站式工具。我第一次用west时觉得多此一举，后来发现没有它才真是寸步难行。

安装west很简单，用pip就行：

pip3 install west

然后初始化工作空间。我个人习惯这样操作：

mkdir zephyr_project
cd zephyr_project
west init
west update

这里有个坑——west init默认会从GitHub拉取Zephyr主仓库。如果你网络不好，可以指定国内镜像：

west init -m https://gitee.com/zephyrproject-rtos/zephyr

核心概念：west manifest

west使用manifest文件管理所有依赖仓库。你可以在zephyr_project/.west/config中看到配置。我建议初学者先别动这个文件，等熟悉了再定制。

2.3 创建第一个Zephyr工程

环境搭好了，咱们来写个经典的"Hello World"。不过Zephyr的Hello World不是打印到终端，而是通过串口输出。

先创建一个工程：

cd zephyr_project
west build -b qemu_x86 samples/hello_world

这条命令做了三件事：

-b qemu_x86：指定目标板为QEMU模拟的x86平台
samples/hello_world：使用官方示例
自动创建build目录并执行CMake配置和编译

编译成功后，你会看到类似这样的输出：

-- west build: generating a build system
-- west build: building
[1/100] Building C object zephyr/CMakeFiles/zephyr.dir...
...
[100/100] Linking C executable zephyr/zephyr.elf

💡 我的经验

第一次编译会比较慢，因为要下载依赖的模块。之后增量编译就快多了。我建议你第一次编译时泡杯咖啡，别盯着屏幕干等。

2.4 编译与烧录：从代码到硬件

编译完成后，怎么把程序烧到板子上？这取决于你用的硬件。我以最常见的STM32和nRF系列为例。

2.4.1 编译指定硬件

假设你用的是STM32F4 Discovery板：

west build -b stm32f4_disco samples/hello_world

Zephyr支持300多种开发板，你可以用west boards命令查看完整列表。

2.4.2 烧录到目标板

烧录命令也很直接：

west flash

west会自动检测你的调试器（J-Link、ST-Link、OpenOCD等）。不过要注意：

确保板子已连接并上电
检查驱动是否安装（特别是Windows系统）
如果使用J-Link，需要安装J-Link软件包

⚠️ 烧录失败怎么办？

我曾经遇到烧录时提示"无法连接调试器"，后来发现是USB线的问题——有些USB线只能充电不能传数据。换根数据线就好了。另外，检查一下板子的BOOT引脚设置，有些板子需要跳线才能进入烧录模式。

2.4.3 使用QEMU模拟运行

没有开发板？没关系，用QEMU模拟器一样能跑：

west build -b qemu_x86 samples/hello_world
west build -t run

你会看到一个QEMU窗口弹出来，里面打印着"Hello World! Zephyr!"。嗯，这一刻还是挺有成就感的。

2.5 避坑指南：我踩过的那些坑

最后分享几个我实际项目中遇到的坑，你遇到了可以直接对照排查：

问题	原因	解决方法
west update卡住	网络问题或GitHub被墙	使用代理或国内镜像
编译报错"Python版本过低"	Zephyr 3.x需要Python 3.8+	升级Python或使用pyenv管理版本
烧录后板子没反应	串口波特率不匹配	检查`prj.conf`中的`CONFIG_SERIAL_BAUD_RATE`
QEMU运行黑屏	缺少图形库或终端设置问题	安装`libsdl2-dev`或使用`-nographic`参数

环境搭建这块就这些内容。说白了，只要SDK版本对、west装好、板子选对，剩下的就是跑命令的事。下一章咱们深入Zephyr的工程结构，看看一个Zephyr项目到底长什么样。