本文是一篇面向新手的 Zephyr RTOS Windows 环境部署教学贴。
按照本文步骤操作，可以在 Windows 系统下完成 Zephyr 开发环境安装，并成功编译、烧录官方 blinky 示例程序。
目录
1. 教程目标
本文的目标是在 Windows 系统中完整搭建 Zephyr RTOS 开发环境。
完成本文后，你将可以：
在 Windows 上安装 Zephyr 所需工具链；
创建 Zephyr Python 虚拟环境；
安装并使用 west；
下载 Zephyr RTOS 源码；
安装 Zephyr SDK；
安装 ARM 嵌入式工具链；
查询 Zephyr 支持的开发板；
编译 Zephyr 官方 blinky 示例；
使用 west flash 烧录程序。
本文以 Renesas RA6E2 开发板为示例，开发板名称使用：
fpb_ra6e2
如果你使用其他开发板，只需要将编译命令中的开发板名称替换成自己的板卡名称即可。
2. 环境说明
推荐环境如下：
| 操作系统 | Windows 10 / Windows 11 |
| 终端 | Windows PowerShell |
| Python | Python 3.10 及以上，推荐 Python 3.12 |
| 构建工具 | CMake、Ninja |
| 版本管理 | Git |
| Zephyr 管理工具 | west |
| SDK | Zephyr SDK |
| 示例开发板 | fpb_ra6e2 |
本教程默认安装目录为：
D:\Zephyr
最终目录结构大致如下：
D:\Zephyr └── zephyrproject ├── .venv ├── .west ├── zephyr ├── modules ├── bootloader ├── tools └── ...
3. 参考资料
Zephyr 官方文档：
https://docs.zephyrproject.org/latest/develop/getting_started/index.html#select-and-update-os
Zephyr GitHub 地址：
https://github.com/zephyrproject-rtos/zephyr
DTC GitHub 地址：
https://github.com/dgibson/dtc/tags
4. 检查 PowerShell 是否为管理员权限
建议使用管理员权限打开 Windows PowerShell。
打开 PowerShell 后，输入下面命令：
if (([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { "管理员" } else { "非管理员" }如果输出：
管理员
说明当前 PowerShell 是管理员权限。
如果输出：
非管理员
说明当前 PowerShell 不是管理员权限。
建议关闭当前窗口，右键 PowerShell，选择：
以管理员身份运行
5. 安装必要工具
Zephyr 在 Windows 下需要安装一些基础工具，包括：
CMake
Ninja
gperf
Python
Git
DTC
wget
7-Zip
5.1 检查 winget 是否可用
在 PowerShell 中执行：
winget --version
如果输出类似：
v1.9.25200
说明 winget 可用。
如果提示找不到 winget，需要先安装或更新 Windows App Installer。
5.2 使用 winget 安装工具
执行下面命令：
winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf Python.Python.3.12 Git.Git oss-winget.dtc wget 7zip.7zip
这个命令会安装 Zephyr 所需的基础工具。
安装过程中如果提示是否同意协议，输入：
Y
然后回车即可。
5.3 检查基础工具是否安装成功
安装完成后，可以分别检查版本。
检查 CMake
cmake --version
检查 Ninja
ninja --version
检查 Python
python --version
检查 Git
git --version
检查 wget
wget --version
检查 7-Zip
7z
只要这些命令可以正常输出版本信息，就说明基础工具基本安装成功。
6. 安装和验证 DTC
DTC 全称是：
Devicetree Compiler
Zephyr 使用设备树描述硬件资源，所以 DTC 是 Zephyr 开发中非常重要的工具。
DTC 下载地址：
https://github.com/dgibson/dtc/tags
如果前面通过 winget 安装成功，一般已经可以直接使用。
6.1 验证 DTC 版本
执行：
dtc --version
正常输出示例：
Version: DTC 1.6.1
6.2 查看 DTC 安装路径
执行：
Get-Command dtc
示例输出：
CommandType Name Version Source ----------- ---- ------- ------ Application dtc.exe 1.0.0.0 C:\ProgramData\chocolatey\bin\dtc.exe
如果能看到 dtc.exe 路径，说明 DTC 已经正确加入系统环境变量。
7. 创建 Zephyr 工作目录
本教程使用：
D:\Zephyr
作为 Zephyr 根目录。
执行：
D: mkdir D:\Zephyr cd D:\Zephyr
如果目录已经存在，mkdir 报错可以忽略，直接进入目录即可：
cd D:\Zephyr
8. 创建 Python 虚拟环境
Zephyr 官方推荐使用 Python 虚拟环境管理依赖。
这样做的好处是：
不污染系统 Python；
不影响其他 Python 项目；
后期删除环境更方便；
依赖版本更容易管理。
在 D:\Zephyr 目录下执行：
python -m venv zephyrproject\.venv
执行完成后，会生成：
D:\Zephyr\zephyrproject\.venv
9. 激活 Python 虚拟环境
执行：
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1
激活成功后，PowerShell 命令行前面会出现：
(.venv)
例如：
(.venv) PS D:\Zephyr>
这说明你当前已经进入虚拟环境。
9.1 如果无法激活虚拟环境
如果执行激活命令时报错，例如：
无法加载文件 Activate.ps1，因为在此系统上禁止运行脚本
可以执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
然后输入：
Y
再重新执行：
zephyrproject\.venv\Scripts\Activate.ps1
10. 安装 west 工具
west 是 Zephyr 官方项目管理工具。
它可以用来：
初始化 Zephyr 工程；
更新 Zephyr 模块；
编译工程；
烧录程序；
安装 SDK；
查看开发板列表。
在虚拟环境激活状态下执行：
pip install west
安装完成后检查版本：
west --version
示例输出：
West version: v1.5.0
11. 初始化 Zephyr 工程
进入 Zephyr 工程目录：
cd D:\Zephyr\zephyrproject
如果之前初始化过 .west，可以先删除：
Remove-Item -Recurse -Force .west
然后执行初始化：
west init -m https://github.com/zephyrproject-rtos/zephyr --mr main
命令说明：
| west init | 初始化 west 工作区 |
| -m | 指定 manifest 仓库 |
| https://github.com/zephyrproject-rtos/zephyr | Zephyr 官方仓库 |
| --mr main | 使用 main 分支 |
12. 更新 Zephyr 工程依赖
初始化完成后，执行：
west update
这个过程会下载 Zephyr 相关模块，例如：
Zephyr 主仓库；
CMSIS；
HAL；
MCUboot；
LittleFS；
TinyCrypt；
mbedTLS；
其他第三方依赖。
这个步骤时间比较长，主要取决于网络环境。
如果网络不好，可能需要多执行几次：
west update
13. 导出 Zephyr CMake 包
执行：
west zephyr-export
作用是将 Zephyr 注册到 CMake 用户包注册表中。
这样 CMake 就能自动找到 Zephyr 的构建配置。
成功日志示例：
Zephyr (D:/Zephyr/zephyrproject/zephyr/share/zephyr-package/cmake) has been added to the user package registry in: HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\Zephyr ZephyrUnittest (D:/Zephyr/zephyrproject/zephyr/share/zephyrunittest-package/cmake) has been added to the user package registry in: HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\ZephyrUnittest
14. 安装 Zephyr Python 依赖
执行：
python -m pip install @((west packages pip) -split ' ')
这个命令会根据 Zephyr 工程需求安装 Python 依赖包。
如果安装过程很慢，可以考虑配置国内 PyPI 镜像源，例如清华源：
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
然后重新执行：
python -m pip install @((west packages pip) -split ' ')
15. 安装 Zephyr SDK
进入 Zephyr 源码目录：
cd D:\Zephyr\zephyrproject\zephyr
执行：
west sdk install
Zephyr 会自动读取下面文件：
D:\Zephyr\zephyrproject\zephyr\SDK_VERSION
然后安装对应版本的 Zephyr SDK。
例如示例中 SDK 版本为：
0.17.4
16. GitHub API 限制问题处理
16.1 常见报错
执行：
west sdk install
时，可能会报错：
fetch_releases API rate limit exceeded. Try executing install script with --personal-access-token argument or use a .netrc file
或者：
Exception: Failed to fetch: 403, {"message":"API rate limit exceeded"}这是 GitHub API 访问次数限制导致的。
16.2 使用 GitHub Token 解决
可以申请自己的 GitHub Personal Access Token。
然后执行：
west sdk install --personal-access-token YOUR_TOKEN_HERE
注意：
YOUR_TOKEN_HERE
需要替换成你自己的 GitHub Token。
16.3 指定 SDK 安装目录
如果希望安装到指定目录，例如：
D:\Zephyr\zephyr-sdk
可以执行：
west sdk install -d D:\Zephyr\zephyr-sdk --personal-access-token YOUR_TOKEN_HERE
16.4 注意不要泄露 Token
不要将真实 GitHub Token：
写进公开教程；
发到群聊；
提交到 GitHub；
放到截图中；
放到公开脚本中。
如果已经泄露，请立即到 GitHub 后台删除该 Token。
17. 只安装 ARM 工具链
默认安装 SDK 时，可能会尝试安装多个架构工具链。
对于大多数 ARM Cortex-M MCU，例如：
STM32；
Renesas RA；
Nordic nRF；
NXP i.MX RT；
GD32；
其他 Cortex-M 芯片；
只需要安装：
arm-zephyr-eabi
即可。
执行：
west sdk install --toolchain arm-zephyr-eabi
如果遇到 GitHub API 限制，则使用：
west sdk install --toolchain arm-zephyr-eabi --personal-access-token YOUR_TOKEN_HERE
17.1 ARM 工具链说明
arm-zephyr-eabi 是 Zephyr SDK 中用于 ARM 架构的交叉编译工具链。
它支持：
ARMv6-M；
ARMv7-M；
ARMv8-M；
Cortex-M0；
Cortex-M3；
Cortex-M4；
Cortex-M7；
Cortex-M23；
Cortex-M33；
Cortex-R 等。
17.2 安装成功日志示例
Installing 'arm-zephyr-eabi' toolchain ... toolchain_windows-x86_64_arm-zephyr-eabi.7z 100% Everything is Ok Folders: 521 Files: 4355 Size: 1162592180 Compressed: 85844046 Installing host tools ... SKIPPED: Windows host tools are not available yet. All done.
看到：
All done.
说明 ARM 工具链安装完成。
18. 查看 Zephyr 支持的开发板
进入 Zephyr 目录：
cd D:\Zephyr\zephyrproject\zephyr
执行：
west boards
该命令会列出当前 Zephyr 支持的所有开发板。
19. 查询指定开发板
19.1 搜索包含 fpb 的开发板
west boards | Where-Object { $_ -like "*fpb*" }示例输出：
fpb_ra4e1 fpb_ra6e1 fpb_ra6e2 fpb_rx261
19.2 搜索 RA6E2 开发板
west boards | Select-String -Pattern "RA6E2" -CaseSensitive:$false
示例输出：
ek_ra6e2 fpb_ra6e2
19.3 查看开发板数量
(west boards | Measure-Object).Count
示例输出：
921
20. 查看 Zephyr 版本信息
20.1 查看 Zephyr Git 版本
在 D:\Zephyr\zephyrproject 目录下执行：
git -C zephyr describe --tags
示例输出：
v4.3.0-2928-g23354f3cad3
20.2 查看最近的 Zephyr tag
git -C zephyr describe --tags --abbrev=0
示例输出：
v4.3.0
20.3 查看 west 版本
如果没有激活虚拟环境，先执行：
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1
然后执行：
west --version
示例输出：
West version: v1.5.0
20.4 查看 Zephyr SDK 版本
执行：
type D:\Zephyr\zephyrproject\zephyr\SDK_VERSION
示例输出：
0.17.4
20.5 查看当前 Windows 用户
whoami
示例输出：
desktop-cbifivc\administrator
21. 编译 Blinky 示例
进入 Zephyr 源码目录：
cd D:\Zephyr\zephyrproject\zephyr
执行：
west build -p always -b fpb_ra6e2 samples\basic\blinky
21.1 命令说明
west build -p always -b fpb_ra6e2 samples\basic\blinky
参数说明：
| west build | 使用 west 构建工程 |
| -p always | 每次都重新生成构建目录 |
| -b fpb_ra6e2 | 指定开发板 |
| samples\basic\blinky | Zephyr 官方 blinky 示例路径 |
21.2 如果你使用其他开发板
假设你的开发板名称是：
nucleo_f103rb
那么命令改成：
west build -p always -b nucleo_f103rb samples\basic\blinky
开发板名称可以通过：
west boards
查询。
21.3 编译成功日志示例
编译成功时，最后会看到类似内容：
[143/143] Linking C executable zephyr\zephyr.elf Memory region Used Size Region Size %age Used FLASH: 22400 B 256 KB 8.54% RAM: 4832 B 40 KB 11.80% Generating files from D:/Zephyr/zephyrproject/zephyr/build/zephyr/zephyr.elf for board: fpb_ra6e2
看到：
Linking C executable zephyr\zephyr.elf
并且没有报错，就说明编译成功。
21.4 编译输出文件
编译完成后，输出文件一般位于：
D:\Zephyr\zephyrproject\zephyr\build\zephyr
常见文件：
| zephyr.elf | ELF 可执行文件，包含符号信息 |
| zephyr.hex | Intel HEX 文件，常用于烧录 |
| zephyr.bin | 二进制固件 |
| zephyr.map | 链接映射文件 |
22. 烧录程序
通过 USB 或调试器连接开发板。
然后执行：
west flash
Zephyr 会自动根据开发板配置选择烧录工具。
例如 RA6E2 示例中使用的是 J-Link：
-- west flash: using runner jlink
22.1 未连接开发板时的失败示例
如果开发板没有连接，执行：
west flash
可能出现：
-- west flash: rebuilding ninja: no work to do. -- west flash: using runner jlink -- runners.jlink: reset after flashing requested -- runners.jlink: JLink version: 8.92 -- runners.jlink: Flashing file: D:\Zephyr\zephyrproject\zephyr\build\zephyr\zephyr.hex FATAL ERROR: command exited with status 1
这种情况一般不是编译问题，而是烧录连接问题。
22.2 烧录失败排查
请检查：
开发板是否已经插到电脑；
USB 线是否支持数据传输；
板子是否正常供电；
J-Link 驱动是否安装；
是否有其他软件正在占用 J-Link；
SWD 接线是否正确；
芯片型号是否和 Zephyr 板级配置匹配；
是否选择了正确的 Zephyr board 名称。
22.3 烧录成功日志示例
-- west flash: rebuilding ninja: no work to do. -- west flash: using runner jlink -- runners.jlink: reset after flashing requested -- runners.jlink: JLink version: 8.92 -- runners.jlink: Flashing file: D:\Zephyr\zephyrproject\zephyr\build\zephyr\zephyr.hex
如果后续没有报错，并且开发板 LED 开始闪烁，说明烧录成功。
23. 常见问题汇总
23.1 PowerShell 无法运行 Activate.ps1
问题：
无法加载文件 Activate.ps1，因为在此系统上禁止运行脚本
解决：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
然后重新激活：
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1
23.2 west 命令找不到
可能原因：
没有激活虚拟环境；
没有安装 west；
Python 环境不正确。
解决：
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1 pip install west west --version
23.3 dtc 命令找不到
检查：
dtc --version
如果提示找不到命令，再执行：
Get-Command dtc
如果仍然找不到，需要重新安装 DTC，或者把 dtc.exe 所在路径加入系统环境变量 PATH。
23.4 west update 很慢或失败
可能原因：
网络不稳定；
GitHub 访问慢；
仓库较大；
子模块较多。
可以多执行几次：
west update
如果一直失败，可以考虑配置 Git 代理。
23.5 Zephyr SDK 下载失败
如果出现 GitHub API 限制：
API rate limit exceeded
使用：
west sdk install --personal-access-token YOUR_TOKEN_HERE
如果只需要 ARM 工具链，推荐：
west sdk install --toolchain arm-zephyr-eabi --personal-access-token YOUR_TOKEN_HERE
23.6 编译时找不到工具链
重新安装 ARM 工具链：
cd D:\Zephyr\zephyrproject\zephyr west sdk install --toolchain arm-zephyr-eabi
如果 GitHub 受限：
west sdk install --toolchain arm-zephyr-eabi --personal-access-token YOUR_TOKEN_HERE
23.7 west flash 烧录失败
检查：
west flash
看输出中使用的 runner。
如果显示：
-- west flash: using runner jlink
需要确认：
已安装 SEGGER J-Link；
J-Link 能识别开发板；
目标芯片型号正确；
USB 线正常；
开发板没有被其他软件占用。
24. 常用命令汇总
24.1 激活虚拟环境
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1
24.2 进入 Zephyr 目录
cd D:\Zephyr\zephyrproject\zephyr
24.3 查看 west 版本
west --version
24.4 更新 Zephyr 模块
west update
24.5 导出 Zephyr CMake 包
west zephyr-export
24.6 安装 Zephyr Python 依赖
python -m pip install @((west packages pip) -split ' ')
24.7 安装 Zephyr SDK
west sdk install
24.8 安装 ARM 工具链
west sdk install --toolchain arm-zephyr-eabi
24.9 查看开发板列表
west boards
24.10 搜索开发板
west boards | Select-String -Pattern "RA6E2" -CaseSensitive:$false
24.11 编译 blinky 示例
west build -p always -b fpb_ra6e2 samples\basic\blinky
24.12 烧录程序
west flash
25. 一键流程总结
下面是从零开始的完整流程。
25.1 安装基础工具
winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf Python.Python.3.12 Git.Git oss-winget.dtc wget 7zip.7zip
25.2 创建目录和虚拟环境
D: mkdir D:\Zephyr cd D:\Zephyr python -m venv zephyrproject\.venv zephyrproject\.venv\Scripts\Activate.ps1
25.3 安装 west
pip install west west --version
25.4 初始化 Zephyr
cd D:\Zephyr\zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr --mr main west update
25.5 导出 CMake 包
west zephyr-export
25.6 安装 Python 依赖
python -m pip install @((west packages pip) -split ' ')
25.7 安装 ARM 工具链
cd D:\Zephyr\zephyrproject\zephyr west sdk install --toolchain arm-zephyr-eabi
如果遇到 GitHub API 限制：
west sdk install --toolchain arm-zephyr-eabi --personal-access-token YOUR_TOKEN_HERE
25.8 编译 blinky
west build -p always -b fpb_ra6e2 samples\basic\blinky
25.9 烧录
west flash
26. 结尾
到这里，Zephyr RTOS 的 Windows 开发环境已经部署完成。
本文完成了：
Windows 基础工具安装；
DTC 安装验证；
Python 虚拟环境创建；
west 安装；
Zephyr 源码初始化；
Zephyr 模块更新；
Zephyr CMake 包导出；
Zephyr Python 依赖安装；
Zephyr SDK 安装；
ARM 工具链安装；
开发板查询；
blinky 示例编译；
程序烧录。
如果你能够成功执行：
west build -p always -b fpb_ra6e2 samples\basic\blinky
并看到：
Linking C executable zephyr\zephyr.elf
说明编译环境已经正常。
如果继续执行：
west flash
后开发板 LED 正常闪烁，则说明 Zephyr 程序已经成功运行在开发板上。
至此，Zephyr RTOS + Windows 开发环境部署完成。
附录 A：本教程关键路径
| Zephyr 根目录 | D:\Zephyr |
| west 工作区 | D:\Zephyr\zephyrproject |
| Python 虚拟环境 | D:\Zephyr\zephyrproject\.venv |
| Zephyr 源码目录 | D:\Zephyr\zephyrproject\zephyr |
| blinky 示例 | D:\Zephyr\zephyrproject\zephyr\samples\basic\blinky |
| 构建目录 | D:\Zephyr\zephyrproject\zephyr\build |
| 固件输出目录 | D:\Zephyr\zephyrproject\zephyr\build\zephyr |
附录 B：GitHub Token 安全提醒
如果你使用了下面命令：
west sdk install --personal-access-token YOUR_TOKEN_HERE
一定要注意：
不要公开真实 Token；
不要把 Token 写到公开教程；
不要把 Token 提交到 GitHub；
不要截图泄露 Token；
如果 Token 泄露，请立即删除或重新生成。
正确的教程写法应该使用：
YOUR_TOKEN_HERE
作为占位符。
附录 C：推荐检查命令
环境搭建完成后，可以执行下面命令检查整体环境。
python --version pip --version west --version cmake --version ninja --version git --version dtc --version
如果以上命令都能正常输出版本信息，说明基础环境基本正常。
附录 D：重新打开 PowerShell 后如何继续开发
每次重新打开 PowerShell 后，都需要重新激活虚拟环境：
cd D:\Zephyr zephyrproject\.venv\Scripts\Activate.ps1
然后进入 Zephyr 目录：
cd D:\Zephyr\zephyrproject\zephyr
之后就可以继续编译：
west build -p always -b fpb_ra6e2 samples\basic\blinky
或者烧录：
west flash
附录 E：如果要切换开发板
先查询开发板名称：
west boards
或者关键词搜索：
west boards | Select-String -Pattern "你的关键词" -CaseSensitive:$false
然后将：
west build -p always -b fpb_ra6e2 samples\basic\blinky
中的：
fpb_ra6e2
替换成你的开发板名称。
例如：
west build -p always -b nucleo_f103rb samples\basic\blinky
附录 F：常见 Zephyr build 参数说明
west build -p always -b fpb_ra6e2 samples\basic\blinky
| west build | 执行构建 |
| -p always | 清理并重新生成构建系统 |
| -b | 指定开发板 |
| fpb_ra6e2 | 开发板名称 |
| samples\basic\blinky | 应用程序路径 |
如果不想每次全新构建，也可以使用：
west build -b fpb_ra6e2 samples\basic\blinky
但是新手建议使用：
-p always
可以减少缓存导致的问题。
附录 G：Zephyr 常见输出文件说明
编译完成后，在：
D:\Zephyr\zephyrproject\zephyr\build\zephyr
通常能看到：
zephyr.elf zephyr.hex zephyr.bin zephyr.map
| zephyr.elf | 带调试符号的可执行文件 |
| zephyr.hex | 常用于烧录 |
| zephyr.bin | 原始二进制固件 |
| zephyr.map | 内存和符号映射文件 |
附录 H：完整命令速查版
# 1. 安装工具 winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf Python.Python.3.12 Git.Git oss-winget.dtc wget 7zip.7zip # 2. 创建目录 D: mkdir D:\Zephyr cd D:\Zephyr # 3. 创建虚拟环境 python -m venv zephyrproject\.venv # 4. 激活虚拟环境 zephyrproject\.venv\Scripts\Activate.ps1 # 5. 安装 west pip install west # 6. 初始化 Zephyr cd D:\Zephyr\zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr --mr main # 7. 更新模块 west update # 8. 导出 CMake 包 west zephyr-export # 9. 安装 Python 依赖 python -m pip install @((west packages pip) -split ' ') # 10. 进入 Zephyr 目录 cd D:\Zephyr\zephyrproject\zephyr # 11. 安装 ARM 工具链 west sdk install --toolchain arm-zephyr-eabi # 12. 查看开发板 west boards # 13. 搜索 RA6E2 west boards | Select-String -Pattern "RA6E2" -CaseSensitive:$false # 14. 编译 blinky west build -p always -b fpb_ra6e2 samples\basic\blinky # 15. 烧录 west flash
完
我要赚赏金
STM32
MCU
通讯及无线技术
物联网技术
电子DIY
板卡试用
基础知识
软件与操作系统
我爱生活
小e食堂
