Zephyr RTOS Windows 开发环境搭建指南

Zephyr RTOS Windows 开发环境搭建指南

纯 Windows CMD/PowerShell 方案，依赖：Git + Python + CMake + Ninja + Zephyr SDK + West
全程 Windows 原生工具，无需类 Unix 模拟层（如 MSYS2、Cygwin、WSL）

目录

1. 前置工具安装
2. Python 虚拟环境
3. 安装 West 工具
4. 配置国内镜像（可选）
5. 初始化 Zephyr 项目
6. 更新子模块
7. 安装 Python 依赖
8. 安装 Zephyr SDK
9. 验证编译
10. ESP32-S3 支持
11. 备份与恢复
12. VS Code 配置
13. 国内镜像源参考
14. 常用命令速查

1. 前置工具安装

使用winget（Windows 包管理器）一键安装所有依赖：

winget install Kitware.CMake Ninja-build.Ninja Python.Python.3.12 Git.Git oss-winget.dtc oss-winget.gperf 7zip.7zip

安装完成后重启终端，确保环境变量生效。

2. Python 虚拟环境

创建独立虚拟环境，避免污染系统 Python：

# 创建虚拟环境python-m venv venv-zephyr# 激活虚拟环境（PowerShell）.\venv-zephyr\Scripts\Activate.ps1

激活后终端提示符前会出现(venv-zephyr)标识。

3. 安装 West 工具

West 是 Zephyr 的元工具，管理多仓库项目：

# 确保虚拟环境已激活pip install west

4. 配置国内镜像（可选）

如果网络访问 GitHub 较慢，建议配置 Gitee 镜像加速。

4.1 清除旧凭据

git config--global credential.helper git credential-manager delete https://gitee.com git credential-manager clear

4.2 设置镜像重写

# GitHub 通用仓库 -> Gitee 镜像git config--global url."https://gitee.com/mirrors/".insteadOf"https://github.com/"# Zephyr 相关仓库 -> Gitee Zephyr 镜像git config--global url."https://gitee.com/zephyr-mirror/".insteadOf"https://github.com/zephyrproject-rtos/"

4.3 确认配置

git config--global--get-regexpurl

4.4 清理旧项目（可选）

如果之前初始化失败，删除重来：

rm-Recurse-Force zephyrproject-ErrorAction SilentlyContinue

5. 初始化 Zephyr 项目

5.1 从 GitHub 初始化（推荐）

west init--mr main-m https://github.com/zephyrproject-rtos/zephyr.git

5.2 从 Gitee 镜像初始化

⚠️ Gitee 镜像可能版本较旧，建议用 GitCode 镜像：

west init--mr main-m https://gitcode.com/GitHub_Trending/ze/zephyr.git

5.3 如果已有本地仓库

west init-l.

5.4 进入项目目录

cd zephyr

6. 更新子模块

6.1 完整更新

west update

6.2 浅克隆（仅主分支，节省空间）

west update--fetch-opt=--depth=1

6.3 指定分支 + 浅克隆

west update--fetch-opt="+refs/heads/main:refs/remotes/origin/main"--fetch-opt=--depth=1

6.4 只更新特定模块

west update hal_nordic

6.5 更新多个模块（浅克隆）

west update hal_nxp,percepio,trusted-firmware-m,uoscore-uedhoc--fetch-opt=--depth=1

6.6 镜像下载失败的解决方案

如果某些模块下载失败，先取消镜像重写，直连 GitHub：

# 查看当前 url 重写配置git config--global--get-regexpurl# 取消 Gitee 镜像重写git config--global--unset url."https://gitee.com/mirrors/".insteadOf git config--global--unset url."https://gitee.com/zephyr-mirror/".insteadOf

7. 安装 Python 依赖

pip install-r zephyr\scripts\requirements.txt

8. 安装 Zephyr SDK

8.1 下载 SDK

从 Zephyr SDK Releases 下载：

代理前缀：https://ghproxy.com/、https://gh.llkk.cc/、https://ghproxy.net/

8.2 解压 SDK

将zephyr-sdk-1.0.1解压到 Zephyr 项目目录下：

D:\zephyrproject\ ├─ zephyr/ ├─ .west/ └─ zephyr-sdk-1.0.1/ ├─ setup.cmd ├─ xtensa-espressif_esp32s3_zephyr-elf/ ├─ xtensa-espressif_esp32p4_zephyr-elf/ └─ riscv64-zephyr-elf/

8.3 运行安装脚本

.\zephyr-sdk-1.0.1\setup.cmd

8.4 注册 SDK 路径

west config sdk.path D:\zephyrproject\zephyr-sdk-1.0.1

写入配置文件后效果：

[sdk] path = D:\zephyrproject\zephyr-sdk-1.0.1

8.5 设置环境变量（临时生效）

$env:ZEPHYR_SDK_INSTALL_DIR="D:\zephyrproject\zephyr-sdk-1.0.1"$env:ZEPHYR_TOOLCHAIN_VARIANT="zephyr"# 验证echo$env:ZEPHYR_SDK_INSTALL_DIRecho$env:ZEPHYR_TOOLCHAIN_VARIANT

8.6 设置永久环境变量

验证（新终端）：

# PowerShellecho$env:ZEPHYR_SDK_INSTALL_DIR# CMDecho%ZEPHYR_SDK_INSTALL_DIR%

8.7 使用 West 安装工具链（推荐）

# 查看可用 SDK 版本west sdk list# 安装全部west sdk install 1.0.1# 指定下载源（如网络受限）west sdk install 1.0.1--base-url https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/# 安装指定工具链west sdk install--toolchain arm west sdk install--toolchain riscv west sdk install--toolchain arm,riscv# ESP32 工具链west sdk install--toolchain xtensa-espressif_esp32s3_zephyr-elf west sdk install--toolchain xtensa-espressif_esp32p4_zephyr-elf west sdk install--toolchain riscv64-zephyr-elf# 批量安装（带代理 base-url）west sdk install 1.0.1 `--base-url https://ghproxy.net/https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1 `--toolchain xtensa-espressif_esp32s3_zephyr-elf `--toolchain xtensa-espressif_esp32p4_zephyr-elf `--toolchain riscv64-zephyr-elf

9. 验证编译

9.1 激活环境

每次新开终端都需要：

# 激活虚拟环境.\venv-zephyr\Scripts\Activate.ps1# 设置 SDK 环境（如果未设永久变量）$env:ZEPHYR_SDK_INSTALL_DIR="D:\zephyrproject\zephyr-sdk-1.0.1"$env:ZEPHYR_TOOLCHAIN_VARIANT="zephyr"

9.2 编译 Hello World

# 进入项目根目录cd D:\zephyrproject# 编译 QEMU x86 目标（无需硬件）west build-b qemu_x86 zephyr/samples/hello_world# 编译 STM32F4 目标west build-b stm32f4_disco zephyr/samples/hello_world# 编译 ESP32-S3 目标west build-b esp32s3_devkitc/esp32s3/procpu zephyr/samples/hello_world

9.3 使用自定义项目目录

# 假设项目在 MyProj/00_hellowest build-b stm32f4_disco MyProj/00_hello# 或直接在项目目录内cd MyProj/00_hello west build-b stm32f4_disco.

10. ESP32-S3 支持

10.1 安装工具链

# 安装 ESP32-S3 工具链west sdk install--toolchain xtensa-espressif_esp32s3_zephyr-elf# 验证安装where xtensa-espressif_esp32s3_zephyr-elf-gcc

10.2 获取 ESP 二进制 Blob

west blobs fetch hal_espressif

10.3 安装烧录与监控工具

pip install esptool pyparsing

10.4 编译、烧录、监控

# 编译（必须加 --sysbuild）west build-b esp32s3_devkitc/esp32s3/procpu--sysbuild samples/hello_world# 烧录west flash# 串口监控west espressif monitor

11. 备份与恢复

11.1 完整备份

# 压缩整个 zephyrprojectCompress-Archive-Path D:\zephyrproject\*-DestinationPath D:\west_full_backup.zip

11.2 导出配置

west config--list > D:\west_config_backup.txt

11.3 仅备份 .west 目录（用于恢复）

# 备份Copy-Item-Recurse D:\zephyrproject\.west D:\west_dot_backup\# 恢复Copy-Item-Recurse D:\west_dot_backup\.west D:\zephyrproject\ cd D:\zephyrproject west init--local.west west update--local

12. VS Code 配置

在.vscode/settings.json中配置：

{// 使用系统默认 PowerShell 终端，不加载 MSYS2"terminal.integrated.defaultProfile.windows":"PowerShell",// CMake 工具配置 Zephyr 编译"cmake.generator":"Ninja",// Python 解释器指向本地虚拟环境"python.defaultInterpreterPath":"${workspaceFolder}/venv/Scripts/python.exe"}

13. 国内镜像源参考

13.1 Git 仓库镜像

13.2 取消镜像配置

git config--global--get-regexpurl git config--global--unset url."https://gitee.com/mirrors/".insteadOf git config--global--unset url."https://github.cnpmjs.org/".insteadOf

14. 常用命令速查

环境切换

# 激活虚拟环境（每次开终端都要执行）.\venv-zephyr\Scripts\Activate.ps1# 切换 Python 路径（不使用虚拟环境激活时）# CMDsetPATH=%CD%\venv-zephyr\Scripts;%PATH%# PowerShell$env:PATH="$PWD\venv-zephyr\Scripts;$env:PATH"

环境变量查看

# PowerShell$env:ZEPHYR_SDK_INSTALL_DIR$env:ZEPHYR_TOOLCHAIN_VARIANT# CMDecho%ZEPHYR_SDK_INSTALL_DIR%echo%ZEPHYR_TOOLCHAIN_VARIANT%# Linux/Macecho$ZEPHYR_SDK_INSTALL_DIR

参考：https://docs.zephyrproject.org/latest/develop/getting_started/index.html