zephyr-Linux环境下搭建步骤

目录

  [1. 基础嵌入式环境配置](#1. 基础嵌入式环境配置)

  [2. 环境最终验证](#2. 环境最终验证)

Zephyr RTOS 是一款开源、跨平台、轻量级、高安全性的嵌入式实时操作系统，全面适配 STM32、GD32、HC32 等主流及国产 MCU，是物联网、低功耗嵌入式设备开发的优选系统。

本教程基于 VMware + Ubuntu 22.04 LTS 搭建官方标准 Zephyr 开发环境，采用 pyenv + 虚拟环境 双层隔离方案，彻底解决 Zephyr 严格的依赖版本限制，杜绝多项目环境冲突，一次配置永久复用，适配日常开发、项目编译、固件烧录全流程。

环境说明：

• 主机系统：Windows 10/11
• 虚拟机：Ubuntu 22.04 LTS（桌面版）
• 搭建目标：搭建通用嵌入式工具链 + Zephyr 开发环境
• 核心优势：环境完全隔离、无依赖冲突、官方标准流程、一次配置永久生效

1. 基础嵌入式环境配置

1.1 系统更新与基础工具安装

进入Linux系统桌面，打开终端（快捷键 Ctrl+Alt+T），执行系统初始化配置：

# 更新软件源 && 升级系统软件
sudo apt update && sudo apt upgrade -y

# 安装解压工具
sudo apt install unzip -y

1.2 安装 Zephyr 系统级依赖

# 必备依赖，全局安装：
sudo apt install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-dev python3-pip python3-venv \
xz-utils file make gcc-multilib libsdl2-dev libmagic1 -y

# 验证依赖版本
cmake --version
dtc --version

1.3 安装和配置 pyenv

# pyenv：负责管理项目所需的 Python 解释器版本，例如为Zephyr项目锁定Python 3.8、3.9等特定版本
# venv：在选定Python解释器的基础上，负责为每个项目创建独立的依赖环境，隔离不同项目的Python包，避免版本冲突

# 1. 安装vpyenv 编译依赖
sudo apt install make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev software-properties-common -y

# 2. 安装并配置 pyenv
# 2.1 自动安装 pyenv
curl https://pyenv.run | bash

# 2.2 配置环境变量（永久生效，写入bashrc）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# 2.3 立即生效配置
source ~/.bashrc

# 2.4 验证 pyenv 安装成功
pyenv --version  # 显示版本号即成功

1.4 使用 pyenv 安装指定Python版本并创建 Zephyr 专用虚拟环境

# Zephyr v3.7+ 要求 Python ≥3.12，我们安装稳定版 3.12.7
# 为了演示升级Python版本，暂安装3.9.18版本；若不尝试该步骤，可直接安装3.12.7版本

pyenv install --list # 查看可安装的Python版本

# 1. 安装适配Zephyr的稳定Python版本
# pyenv install 3.12.7
pyenv install 3.9.18


# 2. 创建工作目录
mkdir -p ~/work/zephyrproject && cd ~/work/zephyrproject

# 3. 为当前Zephyr项目设置专属Python版本（局部生效 ）
pyenv local 3.9.18

# 4. 验证当前Python版本（必须显示3.9.18）
python --version

# 5. 在当前工作目录创建虚拟环境
python -m venv .env_zephyr


# 6. 激活虚拟环境（ 激活成功标志：终端前缀变为 (.env_zephyr)
source .env_zephyr/bin/activate

# 永久激活（开机自动生效，避免重复输入）
echo "source ~/work/zephyrproject/.env_zephyr/bin/activate" >> ~/.bashrc
source ~/.bashrc

# 升级 python的版本操作
# 若需要 升级 python的版本，按如下步骤操作：
# 1. 退出当前虚拟环境
deactivate  

# 2. 用 pyenv 安装 Python 3.12.0 新版本
pyenv install 3.12.0

# 3. 在项目目录中锁定本地 Python 版本为 3.12.0
cd ~/work/zephyrproject
pyenv local 3.12.0

# 4. 删除旧的虚拟环境目录
rm -rf .env_zephyr

# 5. 用新 Python 创建虚拟环境
python -m venv .env_zephyr

# 6. 激活新虚拟环境
source .env_zephyr/bin/activate

# 7. 若之前安装了 west 工具和配置了Zephyr环境，需要重新升级 pip和安装 Zephyr 依赖
pip install --upgrade pip
pip install west
pip install -r zephyr/scripts/requirements.txt

---

1.5 安装 west 工具（Zephyr 核心命令行工具）

# 在激活的环境中执行：
pyenv which python   # 确认当前 Python 路径， 确保 pip 是在正确的 Python 版本环境里进行操作

pip install --upgrade pip   # 升级虚拟环境内的 pip
pip install west

# 验证安装
west --version

1.6 初始化 Zephyr 工作区并拉取源码

# 在激活的环境中执行：

# 1. 进入工作目录
cd ~/work/zephyrproject

# 2. 初始化工作区
west init -m https://github.com/zephyrproject-rtos/zephyr --mr main

# west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.5.0   # 获取指定版本的源码


# 3. 拉取Zephyr源码与依赖（耗时较长，保持网络畅通）
west update

# 5. 导出CMake配置（官方必备步骤）
west zephyr-export

# 6. 安装Zephyr Python依赖
pip install -r zephyr/scripts/requirements.txt

# 或使用 .west packages
west packages pip --install


# 查看当前版本
west version

# 将 ZEPHYR_BASE 添加到 ~/.bashrc（永久生效）
echo 'export ZEPHYR_BASE=$HOME/work/zephyrproject/zephyr' >> ~/.bashrc
source ~/.bashrc

echo $ZEPHYR_BASE
# 应输出: work/zephyrproject/zephyr

1.7 安装 Zephyr SDK

SDK 是 ARM 编译工具链，指定安装到～/work/zephyrSDK：

# 1. 创建SDK目录
mkdir -m 777 ~/work/zephyrSDK
cd ~/work/zephyrSDK


#  2. 指定路径安装SDK  ,需要根据 zephyr 版本安装适配的SDK版本
#  本次安装的Zephyr version: 4.4.99， 对应 SDK版本为 1.0.0
#wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz
#wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.0/zephyr-sdk-1.0.0_linux-x86_64_gnu.tar.xz  # GNU 版

# 若下载太慢，就采用如下方式下载
# aria2 是一款支持多线程、断点续传的下载神器，可以显著提升下载速度
sudo apt install aria2 -y

# -x 16, aria2 会开启 16 个连接进行高速下载 ; 
aria2c -x 16 -s 16 https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.0/zephyr-sdk-1.0.0_linux-x86_64_gnu.tar.xz


#  2.1 解压 SDK
tar xvf zephyr-sdk-1.0.0_linux-x86_64_gnu.tar.xz

#  2.2 运行 setup.sh 脚本
cd zephyr-sdk-1.0.0
./setup.sh

# 安装过程全部输入 y 确认即可


#  3. 配置 SDK 环境变量（永久生效）
# 3.1 查询 arm-zephyr-eabi-gcc 位置
find ~/work/zephyrSDK -name "arm-zephyr-eabi-gcc" -type f 2>/dev/null

# 输出工具链的实际位置：
work/zephyrSDK/zephyr-sdk-1.0.0/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc

# 3.2 将 bin 目录永久加入 PATH
echo "export ZEPHYR_SDK_INSTALL_DIR=$HOME/work/zephyrSDK/zephyr-sdk-1.0.0" >> ~/.bashrc
echo 'export PATH=$PATH:$HOME/work/zephyrSDK/zephyr-sdk-1.0.0/gnu/arm-zephyr-eabi/bin' >> ~/.bashrc
echo 'export ZEPHYR_TOOLCHAIN_VARIANT=zephyr' >> ~/.bashrc
source ~/.bashrc

# 关闭终端重新打开，激活虚拟环境后验证工具链是否安装成功
arm-zephyr-eabi-gcc --version

# 编译时，会输出各工具的版本信息
west build -b nrf52840dk/nrf52840 . --pristine

# - west build: generating a build system
# Loading Zephyr default modules (Zephyr base).
# -- Application: /home/mm2/work/zephyrproject/project/prjBlueTest
# -- CMake version: 3.22.1
# -- Found Python3: /home/mm2/work/zephyrproject/.env_zephyr/bin/python (found suitable version "3.12.0", minimum required is "3.12") found components: Interpreter 
# -- Cache files will be written to: /home/mm2/.cache/zephyr
# -- Zephyr version: 4.4.99 (/home/mm2/work/zephyrproject/zephyr)
# -- Found west (found suitable version "1.5.0", minimum required is "0.14.0")
# -- Board: nrf52840dk, qualifiers: nrf52840
# Could not find a configuration file for package "Zephyr-sdk" that is
#   compatible with requested version "1.0".     #版本不兼容

# 若Zephyr SDK 不满足 Zephyr 内核有严格的版本对应关系，就进行如下升级 SDK的操作

# 1. 打开配置文件
gedit ~/.bashrc

#注释或删除以下两行旧配置
# export ZEPHYR_SDK_INSTALL_DIR=$HOME/work/zephyrSDK/zephyr-sdk-0.16.8
# export PATH=$PATH:$HOME/work/zephyrSDK/zephyr-sdk-0.16.8/arm-zephyr-eabi/bin

# 2. 删除旧 SDK 目录
rm -rf ~/work/zephyrSDK

# 3.  按安装步骤：1.7  安装 Zephyr SDK   重新加载新 SDK 

1.8 配置 Linux 硬件权限

配置USB设备权限，解决烧录、调试权限不足问题，同时安装J-Link驱动，适配主流调试器。

# 1. 安装官方 udev 规则（允许 ST-Link/J-Link/串口访问）
cd ~/work/zephyrSDK/zephyr-sdk-1.0.0
sudo ./setup.sh -u

# 2. 重启 udev 服务，使新的规则生效
sudo udevadm control --reload-rules
sudo udevadm trigger

# 3. 安装串口调试工具
sudo apt install picocom -y

#========== J-Link驱动安装 ==========
# 4. jlink 驱动安装
# 4.1 新建工具存放目录
mkdir -p ~/work/tool/jlink
cd ~/work/tool/jlink

# 4.2 进入官网下载J-Link驱动
https://www.segger.com/downloads/jlink/

# 4.3 选择 Linux版的 JLink_Linux_V938a_x86_64.deb  下载安装包
# 4.4 移动安装包到 /work/tool/jlink/
mv JLink_Linux_V938a_x86_64.deb ~/work/tool/jlink/

# 4.5 运行安装命令
sudo dpkg -i JLink_Linux_V938a_x86_64.deb

# sudo apt install -f   # 修复依赖（如有需要）

# 4.6 配置路径, 末尾添加 新路径行
gedit ~/.bashrc
export PATH=$PATH:/opt/SEGGER/JLink
source ~/.bashrc

# 4.7 检查 J-Link 软件是否安装成功
JLinkExe -v

#========== J-Link驱动安装结束 ==========

2. 环境最终验证

编译 STM32 示例程序，测试环境是否正常:

# 1. 进入源码目录
cd ~/work/zephyrproject/zephyr

# 2. 清理全部缓存, 在需要时可进行该指令操作
# west build -t pristine

# 3. 编译 STM32F4 点灯示例
west build -b stm32f4_disco samples/basic/blinky

# 出现 [100%] Built target zephyr → 环境搭建完成！

# 4. 烧录固件
west flash

#  west flash -r jlink # 指定 jlink 烧录


# 5. 串口调试
west debug   # 会复位并重新烧录程序

west attach # 仅连接到正在运行的目标，不会重新烧录和重启