Zephyr 开发环境搭建保姆级教程（Windows/Linux/macOS 全平台 + blinky 点灯 + 踩坑排错）

硬核嵌入式
35 阅读13分钟

本文是「Zephyr 内核从入门到精通」系列第 03 篇。上一篇讲了架构，这一篇把开发环境从零装好，并亲手点亮第一颗 LED。

每一条命令都标清楚 在哪个目录、敲哪条命令、应该看到什么输出，照着抄就能跑通。没有开发板也没关系，文末有 QEMU 仿真方案。

建议先点赞收藏，开一个终端窗口跟着做，不踩坑。

目录

  • 一、先搞懂：Zephyr 开发环境的组成
  • 二、动手前的准备（必读）
  • 三、Linux / macOS 搭建步骤（逐条带预期输出）
  • 四、Windows 搭建步骤（逐条带预期输出）
  • 五、编译并点亮第一个 blinky（含自建最小工程）
  • 六、没有开发板？用 QEMU 仿真跑通
  • 七、west 核心命令速查
  • 八、高频报错排查表（加强版，14 条）
  • 九、总结

一、先搞懂：Zephyr 开发环境的组成

很多人搭环境失败，是因为 不知道自己在装什么，报错了无从下手。先看这张图建立全局认知：

在这里插入图片描述

Zephyr 环境分两大块，你装的所有东西都能归到这两类里：

① Host 工具（运行在你这台电脑上）

  • Python 3 + venv：west 是 Python 写的，构建脚本也依赖它。venv 是 Python 的「虚拟环境」，相当于给 Zephyr 单独开一个干净的小房间，不污染系统 Python。
  • West：Zephyr 官方的「元工具」（meta-tool），既能管理十几个 Git 仓库，又封装了 build/flash/debug 等命令。你可以把它理解成 Zephyr 世界的「总指挥」。
  • CMake（≥ 3.20）：构建系统生成器，把工程描述翻译成实际的编译指令。
  • Ninja：真正执行编译的高速引擎，比传统 make 快很多。
  • Git：用来拉取 Zephyr 主仓库及其几十个 modules（外设驱动、HAL、第三方库等）。

② Zephyr SDK（交叉编译工具链）

给目标 MCU 用的编译器（如 arm-zephyr-eabi-gcc）+ OpenOCD 等烧录调试工具。

关键理解：你电脑上的 gcc 是给 PC 编译程序的；SDK 里的 gcc 是给单片机编译程序的。 两套编译器，分工不同，互不替代。这就是「交叉编译」——在 A 平台上编译出 B 平台能跑的程序。

记住这个分层，后面排错时只要先判断「问题出在 Host 工具 / 源码网络 / SDK 硬件 哪一层」，就能少走 90% 弯路。

二、动手前的准备（必读）

正式开始前，先确认三件事，能帮你省下大量回头返工的时间。

1）确认 Python 和 CMake 版本达标

打开终端（Windows 用 PowerShell），分别敲：

python3 --version
cmake --version

预期输出（版本号 ≥ 要求即可）：

Python 3.11.6
cmake version 3.27.7
  • Python 必须 ≥ 3.10，CMake 必须 ≥ 3.20。低于这个版本，后面 west build 会直接报错。
  • 如果命令提示「找不到」，说明还没装或没加进 PATH，先在第三/四节里把依赖装上。

2）准备好网络（国内重点）

west update 要从 GitHub 拉十几个仓库，几百 MB 起步。国内网络很容易卡死或超时，强烈建议提前挂好代理，否则会卡在这一步反复失败。

3）规划目录

我们统一把工程放在用户主目录下的 zephyrproject 文件夹。整个搭建流程如下图，建议照着这个顺序走：

> 【插入图 2：02_Zephyr环境搭建流程】

下面分平台讲。Linux/macOS 看第三节，Windows 看第四节，按需跳转即可。

三、Linux / macOS 搭建步骤（逐条带预期输出）

3.1 安装系统依赖

操作位置：任意终端，目录无所谓。

Ubuntu / Debian：

sudo apt update
sudo apt install --no-install-recommends \
     git cmake ninja-build gperf ccache dfu-util device-tree-compiler \
     python3-dev python3-pip python3-venv python3-tk wget xz-utils file

这一步在做什么： 装齐 Host 工具（git、cmake、ninja 等）和一些编译期会用到的小工具。--no-install-recommends 表示只装必需包，不装一堆推荐附属包。

macOS（用 Homebrew）：

brew install cmake ninja gperf python3 ccache qemu dtc git

预期输出： 一长串下载/安装日志，最后没有 error 字样即成功。装完用第二节的命令复查一下 cmake / python 版本是否达标。

3.2 创建虚拟环境并安装 west

操作位置：任意终端。这一步会在 ~/zephyrproject 下建一个 .venv 目录。

python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
pip install west

逐条拆解：

  • 第 1 行：在 ~/zephyrproject/.venv 创建虚拟环境（那个干净的「小房间」）。
  • 第 2 行：source ... activate 是「进入小房间」。成功后你的命令行提示符前面会多出一个 (.venv) 前缀。
  • 第 3 行：在房间里装 west。

预期输出（关键看最后一行）：

(.venv) Successfully installed west-1.2.0

⚠️ 划重点：之后 每次开新终端 都要先执行 source ~/zephyrproject/.venv/bin/activate，否则 west 命令会提示找不到。看到提示符没有 (.venv) 前缀，就说明忘激活了。这是新手最高频的「假报错」。

验证 west 装好了：

west --version

预期输出：

West version: v1.2.0

3.3 获取 Zephyr 源码

操作位置：终端，确保已激活 venv（提示符有 (.venv)）。

west init ~/zephyrproject
cd ~/zephyrproject
west update

逐条拆解：

  • west init：初始化工作区，会创建 .west/ 配置目录并下载主清单仓库。这一步很快。
  • cd ~/zephyrproject：进入工作区目录。后续 west 命令都在这里或其子目录里执行。
  • west update：按清单拉取所有 modules（十几个仓库）。这一步最慢、最吃网络。

west update 预期输出（会滚动很久）：

=== updating hal_nordic (modules/hal/nordic):
--- hal_nordic: initializing
Receiving objects: 100% (12345/12345), 45.67 MiB | 2.10 MiB/s, done.
=== updating cmsis (modules/hal/cmsis):
...
=== updating zephyr ...

看到一个个 === updating xxx 滚过去，最后回到命令行提示符且无 error，就成功了。

国内卡在这里很常见。如果某个仓库反复超时，先确认代理生效，再重新执行 west update（它支持断点续传，已下好的不会重下）。

3.4 安装 Python 依赖

操作位置：~/zephyrproject 目录，venv 已激活。

west packages pip --install

这一步在做什么： Zephyr 的构建/测试脚本依赖一批 Python 包（如 pyelftools、pykwalify 等），这条命令一次性把它们装进当前 venv。

预期输出：

Collecting pyelftools>=0.29
...
Successfully installed pyelftools-0.31 pykwalify-1.8.0 ...

3.5 安装 Zephyr SDK（交叉编译工具链）

操作位置：~/zephyrproject 目录，venv 已激活。

west sdk install

这一步在做什么： 自动下载并安装与当前 Zephyr 版本匹配的 SDK（给单片机用的交叉编译器 + OpenOCD 等）。SDK 体积较大（1～2 GB），耐心等。

预期输出：

Installing SDK 0.16.x to /home/you/zephyr-sdk-0.16.x
Downloading ...  100%
Verifying SHA256 ... OK
Successfully installed Zephyr SDK

若网络受限下载失败，可去 GitHub 的 zephyr-sdk Releases 页手动下载压缩包，解压后运行包内的 setup.sh 注册即可，效果等价。

至此，Linux/macOS 环境搭建完成。下面 Windows 用户看第四节，已完成的可直接跳到 第五节点灯。

四、Windows 搭建步骤（逐条带预期输出）

Windows 的思路与 Linux 完全一致，区别只在「依赖怎么装」和「venv 怎么激活」。全程用 PowerShell（建议以管理员身份打开）。

4.1 安装依赖（推荐 Chocolatey）

操作位置：管理员 PowerShell。

先安装 Chocolatey（去官网复制那条安装命令执行），然后：

choco install cmake ninja gperf python git wget unzip dtc-msys2 -y

这一步在做什么： 用包管理器一次装齐所有 Host 工具。-y 表示全部自动确认。

预期输出（结尾出现类似字样即成功）：

Chocolatey installed 8/8 packages.

不想用 Chocolatey 也行，可以用 winget 逐个装：winget install Kitware.CMake、winget install Ninja-build.Ninja、winget install Python.Python.3.11、winget install Git.Git。

装完 关闭并重开 一个 PowerShell（让 PATH 生效），用第二节命令复查 python --version / cmake --version 是否达标。

4.2 创建虚拟环境 + 安装 west

操作位置：PowerShell，会在 %USERPROFILE%\zephyrproject 下建 .venv。

python -m venv $HOME\zephyrproject\.venv
$HOME\zephyrproject\.venv\Scripts\Activate.ps1
pip install west

预期输出： 激活成功后，提示符前面会出现 (.venv)；最后一行：

(.venv) Successfully installed west-1.2.0

如果第 2 行报错「无法加载文件 ... 因为在此系统上禁止运行脚本」，先执行下面这条放开 PowerShell 脚本权限，再重试激活：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

同样，Windows 上每次开新 PowerShell 也要先跑一遍 Activate.ps1 才能用 west。

4.3 拉源码 + 装依赖 + 装 SDK

操作位置：PowerShell，venv 已激活。

west init $HOME\zephyrproject
cd $HOME\zephyrproject
west update
west packages pip --install
west sdk install

含义与 Linux 第 3.3～3.5 节完全相同，预期输出也一致（=== updating xxx 滚屏、Successfully installed、Successfully installed Zephyr SDK）。

Windows 烧录真实硬件还需安装调试器驱动（ST-Link / J-Link）。如果烧录时识别不到设备，用 Zadig 给对应 USB 设备安装 WinUSB 驱动即可。

五、编译并点亮第一个 blinky

环境装好了，现在来点灯。先用官方现成例子，再给你一份「自己从零搭的最小工程」，两种都讲。

> 【插入图 3：03_west工作流命令速查】

5.1 方案 A：直接用官方 samples/basic/blinky

操作位置：~/zephyrproject/zephyr 目录（Windows 为 $HOME\zephyrproject\zephyr），venv 已激活。

cd ~/zephyrproject/zephyr
west build -b nrf52840dk/nrf52840 samples/basic/blinky
west flash

逐条拆解：

  • cd ... /zephyr：进入 Zephyr 主仓目录，官方 samples 就在这下面。
  • west build -b <board> <app路径>：编译。-b 后面是 板子标识，samples/basic/blinky 是要编译的工程路径。
  • west flash：把编译产物烧进开发板。

关于板名（重点）： 新版 Zephyr 采用 Hardware Model v2，板名带斜杠，格式是 板子/SoC[/核]。常见例子：

  • Nordic：nrf52840dk/nrf52840
  • ESP32：esp32_devkitc_wroom/esp32/procpu
  • ST：nucleo_f401re

不确定自己板子叫什么，用下面命令查（以 nrf52840 为例）：

west boards | grep nrf52840

west build 预期输出（重点看结尾的 Memory region 用量）：

-- west build: building application
[1/150] Preparing syscall dependency handling
...
[150/150] Linking C executable zephyr/zephyr.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       24576 B         1 MB      2.34%
             RAM:        4096 B       256 KB      1.56%
        IDT_LIST:          0 GB        32 KB      0.00%

看到 Memory region 这张表 + 没有 error，就代表 编译成功，产物在 build/zephyr/zephyr.elf（及 .hex、.bin）。

west flash 预期输出：

-- west flash: using runner nrfjprog
Flashing build/zephyr/zephyr.hex
Programming ... OK
Verifying ... OK
-- runner nrfjprog: Board with serial number xxxxxx flashed successfully.

看到 flashed successfully，去看开发板——板载 LED 开始一秒一闪，点灯成功！ 🎉

5.2 方案 B：自己从零搭一个最小 blinky 工程

理解工程结构比直接抄例子更重要。一个最小 Zephyr 应用只需要 3 个文件：

my_blinky/
├── CMakeLists.txt     ← 告诉构建系统：源文件是哪些
├── prj.conf           ← 应用级配置（开哪些功能）
└── src/
    └── main.c         ← 你的业务代码

操作位置：在 ~/zephyrproject 下新建 my_blinky 目录。

CMakeLists.txt：

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_blinky)

target_sources(app PRIVATE src/main.c)

说明：find_package(Zephyr ...) 把整个 Zephyr 构建系统拉进来；target_sources(app ...) 声明你的源文件。app 是 Zephyr 约定的目标名，照写即可。

prj.conf：

CONFIG_GPIO=y

说明：blinky 要操作 GPIO，所以开启 CONFIG_GPIO。prj.conf 就是「功能开关清单」，需要什么子系统就在这里打开。

src/main.c：

#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

/* 从设备树取板载 LED（别名 led0），具体引脚由设备树决定，代码不用关心引脚号 */
#define LED0_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);

#define SLEEP_TIME_MS 1000

int main(void)
{
    if (!gpio_is_ready_dt(&led)) {
        return 0;
    }

    /* 配置为输出，初始电平为「点亮」 */
    gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);

    while (1) {
        gpio_pin_toggle_dt(&led);   /* 翻转电平：亮->灭->亮... */
        k_msleep(SLEEP_TIME_MS);    /* 睡 1 秒 */
    }
    return 0;
}

注意看：代码里 没有任何引脚号，全靠设备树的 led0 别名。「它怎么知道点哪颗灯？」——这正是下一篇《设备树》要讲的核心，先埋个伏笔。

编译并烧录自建工程：

操作位置：~/zephyrproject 目录，venv 已激活。

cd ~/zephyrproject
west build -b nrf52840dk/nrf52840 my_blinky
west flash

预期输出与方案 A 一样：先看到 Memory region 用量表，再看到 flashed successfully，LED 开始闪烁。

💡 改了 prj.conf 或加了设备树 overlay 后，一定要用 全新构建，否则旧缓存会让你的改动「不生效」：

west build -p always -b nrf52840dk/nrf52840 my_blinky

-p always 表示 pristine（每次都从零干净构建）。新手遇到「我明明改了配置怎么没反应」，九成是忘了加 -p always。

5.3 看 LED 闪烁日志（可选）

如果想在串口看日志，给 prj.conf 加上：

CONFIG_GPIO=y
CONFIG_LOG=y

并在代码里用 LOG_INF("LED state: %d", val); 打印。连好串口（115200 8N1）后用串口工具能看到类似：

*** Booting Zephyr OS build v3.x.x ***
[00:00:01.000] <inf> main: LED state: 1
[00:00:02.000] <inf> main: LED state: 0
[00:00:03.000] <inf> main: LED state: 1

每秒一行、状态在 0/1 之间翻转，和 LED 的明灭节奏一致。

六、没有开发板？用 QEMU 仿真跑通

没有硬件也能学。QEMU 能仿真一块 Cortex-M3 板子，让你在纯软件里把整条工具链跑通。

操作位置：~/zephyrproject/zephyr 目录，venv 已激活。

先跑个最稳的 hello_world 验证工具链：

cd ~/zephyrproject/zephyr
west build -b qemu_cortex_m3 samples/hello_world
west build -t run

逐条拆解：

  • -b qemu_cortex_m3：目标板换成 QEMU 仿真板。
  • west build -t run：-t run 是「构建并在 QEMU 里直接运行」的目标。

预期输出（直接在终端打印）：

-- west build: running target run
*** Booting Zephyr OS build v3.x.x ***
Hello World! qemu_cortex_m3

看到 Hello World!，说明 Host 工具 + SDK 这条链路完全打通。按 Ctrl + A 然后按 X 退出 QEMU。

新手强烈建议：先用 QEMU 把流程跑顺，再上真实硬件。这样一旦真机出问题，你能确定「不是环境的锅」，排错范围立刻缩小一半。

七、west 核心命令速查

# 构建（首次 / 常规）
west build -b <board> <app_path>

# 全新构建（改了 prj.conf / overlay 后必加 -p always）
west build -p always -b <board> <app_path>

# 图形化配置
west build -t menuconfig      # 文本菜单
west build -t guiconfig       # 图形窗口

# QEMU 里直接运行
west build -t run

# 烧录 / 调试
west flash
west debug

# 查板子 / 更新源码
west boards
west update

八、高频报错排查表（加强版，14 条）

#报错现象根本原因解决办法
1west: command not found / 无法将"west"识别为...没激活 venv（提示符没有 (.venv)）Linux/mac：source ~/zephyrproject/.venv/bin/activate；Win：.venv\Scripts\Activate.ps1
2PowerShell 报「禁止运行脚本」激活失败执行策略限制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 后重试
3west update 卡死 / 反复超时拉 GitHub 网络问题挂代理后重跑（支持断点续传）；或换镜像源
4CMake 3.x or higher is required. You are running 3.16CMake 版本 < 3.20升级 CMake，再 cmake --version 复查
5Python 3.10+ required 或包装不上Python < 3.10 或没用 venv升级 Python；务必在 venv 内 west packages pip --install
6改了 prj.conf / overlay 但「不生效」CMake 缓存未刷新用全新构建：west build -p always -b <board> <app>
7Board <xxx> not found用了旧板名写法（无斜杠）改 HW Model v2 斜杠格式，如 nrf52840dk/nrf52840；west boards 查准确名
8west sdk install 下载失败 / 校验不过网络中断或文件损坏重跑；或去 GitHub Releases 手动下 zephyr-sdk，解压后跑 setup.sh
9flash 提示找不到设备 / No device foundUSB 驱动或权限问题Linux 装 udev 规则并重新插拔；Windows 用 Zadig 装 WinUSB 驱动
10pip install 报包冲突 / 依赖打架污染了系统 Python，没用 venv删掉旧环境重建 venv，全部操作在 venv 内做
11ZEPHYR_BASE 相关报错 / find_package(Zephyr) 失败没在工作区内执行 / 环境变量缺失在 ~/zephyrproject 下执行；必要时 source zephyr/zephyr-env.sh
12error: 'led0' undeclared / 设备树别名找不到该板没有 led0 别名换有 LED 别名的板；或自己写 overlay 补 aliases { led0 = ...; }（下一篇讲）
13west build 报 Ninja not foundNinja 没装或没进 PATH重装 Ninja，重开终端让 PATH 生效
14QEMU 卡住不动 / 退不出来不知道退出快捷键退出 QEMU：先按 Ctrl + A，松手再按 X

排错心法：先判断报错属于 Host 工具 / 源码网络 / SDK 硬件 哪一层，再针对性处理，比盲目复制报错去搜高效得多。表里第 1、3、6、7、9 条占了新手 90% 的坑，遇事先看这几条。

九、总结

  1. Zephyr 环境 = Host 工具（含 West）+ Zephyr SDK，分层理解是排错的前提；
  2. 务必用 venv 隔离 Python，避免依赖冲突；记住每开新终端都要先激活；
  3. 标准六步：系统依赖 → 建 venv 装 west → west init/update → west packages pip --install → west sdk install → 编译点灯；
  4. 最小工程只要 CMakeLists.txt + prj.conf + src/main.c 三个文件；
  5. 改配置后记得 -p always 全新构建；没硬件用 QEMU 仿真 照样学；
  6. 90% 报错集中在：没激活 venv、网络、没 pristine 重建、USB 驱动、板名写法。

下一篇《Zephyr 设备树（Devicetree）》，揭开本篇埋的伏笔：blinky 代码里没有引脚号，它怎么知道该点哪颗灯？答案就在设备树。

如果帮到你，点赞 + 收藏 + 关注三连支持，是我持续更新的动力。搭环境遇到的报错，欢迎贴在评论区，我帮你定位。

avatar
文章
阅读
粉丝