手把手Zephyr开发环境：五步跑通第一个demo-平芜编程栈

手把手Zephyr开发环境：五步跑通第一个demo

【免费下载链接】zephyr-cnzephyr-cn is a collection of original work of SIG-Zephyr项目地址: https://gitcode.com/openeuler/zephyr-cn

在 Windows 上跑 Zephyr，常常卡在交叉工具链和 Linux 依赖上。我们用 zephyr-cn 提供的 Docker 路线，在 Windows 上配好 Zephyr 开发环境：五步走完，第一个示例就能在容器里编译并运行起来。

备齐 4 份文件：搭 Zephyr 开发环境前要先下载什么

为什么用 Docker？一句话：它是一个打包好、随手可用的"Linux 盒子"。盒子里已经装好编译器和构建工具，Windows 上不用再装 Linux，也不用自己配工具链。

你最后拿到的是一个容器，代码、编译、运行都在容器里完成。开工前先下载 4 份文件：

Zephyr 项目文件（sig_zephyr_v2.7.4.tar.gz）：基于 LTS 2.7.4 版本，按工程布局打包，解压即可用。
zephyr sdk（zephyr-sdk-0.13.1-linux-x86_64-setup.run）：提供编译器和 gdb，没有它编不了代码。
Docker Desktop（V4.18.0）：Windows 上跑容器的入口。
Windows Terminal：输入命令用的终端。

前两份稍后要放进容器，后两份装在 Windows 本机。

上图是 Zephyr 的整体架构，稍后搭好的容器就是这些组件运行的底座。

下载来源与文件版本的详细说明，见 Windows 下 Docker 开发环境搭建文档。

Zephyr Docker 配置：改两处，拉镜像快很多

先弄清两个词：镜像是模板，容器是跑起来的实例。zephyr-build 这个镜像里预装了编译器和构建工具，我们只要从它启动一个实例。Docker Desktop 默认把镜像存在 C 盘，镜像源又在国外，拉取前先改两处。

修改 Docker 镜像存储位置

打开 Docker Desktop 设置页，进入 Resources 选项卡，点 Advanced，把 "Disk image location" 改到空间充足的盘符。这一步是防止 C 盘被塞满。

配置国内镜像源

在 Docker 的配置文件（daemon.json）中加入以下内容：

{ "registry-mirrors": [ "https://registry.docker-cn.com", "https://mirror.aliyuncs.com" ] }

这两个镜像源用来加速拉取，保存后重启 Docker Desktop 生效。

拉取 zephyr-build 镜像

打开 Windows Terminal，用这条命令从镜像仓库拉取 Zephyr 官方构建镜像（体积超过 12GB，耗时看网速）：

docker pull zephyrprojectrtos/zephyr-build:latest

再用这条命令确认镜像已经下载到本地：

docker images

列表里能看到 zephyrprojectrtos/zephyr-build 一行，说明拉取成功。

Zephyr Docker 配置收尾：创建容器并挂载本地目录

这一步是 Docker 容器挂载的关键。完成后，本地文件夹和容器共享同一份文件，Windows 这边改，容器那边读。

一条命令创建容器

这条命令创建名为 SIG_Zephyr 的容器，并把本地目录 D:\Workspace\SIG_Zephyr 映射到容器内的 /workdir，命令执行完终端直接落在容器里：

docker run -it --name SIG_Zephyr -v /d/Workspace/SIG_Zephyr:/workdir zephyrprojectrtos/zephyr-build:latest

挂载的意思：两个位置指向同一份存储。你在 Windows 侧编辑的文件，容器里直接能读到，不用来回拷贝。

放项目文件

把下载的两份文件放进 D:\Workspace\SIG_Zephyr，容器里的 /workdir 就能看到它们。用这条命令解压项目：

tar -xvzf sig_zephyr_v2.7.4.tar.gz

解压后会多出 .west、zephyr、modules 等目录，这就是完整的 Zephyr 工程布局。再执行 west update 校验工程是否完整：

west update

west 是什么？它是 Zephyr 的项目管理工具，west update 会读取清单文件 west.yml，把清单里列出的子项目补齐到工作区。工作区结构和清单文件的更多概念，见 West 基本概念与工作区说明。

安装 zephyr sdk

给 sdk 文件加执行权限，然后运行安装：

chmod +x zephyr-sdk-0.13.1-linux-x86_64-setup.run ./zephyr-sdk-0.13.1-linux-x86_64-setup.run

按提示走完 zephyr sdk 安装即可，安装路径用默认值不用改，容器里的编译器就此就位。

从 west build 到 west run：你的第一个哲学家

环境齐了，跑第一个示例。进入 zephyr 目录，编译 philosophers 示例：

cd zephyr west build -p auto -b qemu_cortex_m3 samples/philosophers

参数不难：-p auto 自动判断是否需要清理后重新构建；-b qemu_cortex_m3 指定目标板，是 QEMU 里的虚拟板，不需要真实硬件；samples/philosophers 是示例路径。

编译进度会打在终端里，成功后产物放在 build 目录。这个示例模拟经典的"哲学家吃饭"并发场景，输出内容本身就是内核调度的一次演示。

接着启动 QEMU 仿真运行：

west build -t run

这条命令复用刚才的构建目录，不用重新编译。终端字符开始不停滚动，说明哲学家们开动了，按 Ctrl+C 可以停止。

打开 VSCode：Zephyr 插件与 compile_commands.json 配置

demo 跑通只是开始。写代码时你还会想要代码跳转和编译反馈，VSCode 配合这套环境分三步接上。

安装 VSCode Zephyr 插件组

在 VSCode 中安装 5 个插件：

C/C++：代码跳转与 IntelliSense
CMake：CMake 语言支持
kconfig：Kconfig 配置文件支持
nRF DeviceTree：Zephyr 设备树支持
Arm Assembly：ARM 汇编支持

multi-root 工作区布局

把下面四个目录作为一个工作区打开：

<zephyr_workspace> ├── zephyr # Zephyr 源码 ├── modules # Zephyr 模块 ├── app # 你的应用 └── build # 构建目录

build 目录建议单独放，避免构建产物污染 zephyr 的 git 仓库。

配置 compile_commands.json

Zephyr 代码量大，IntelliSense 默认配置覆盖不住。CMake 配置一次之后，构建目录会生成 compile_commands.json，记录每个文件的编译选项。先生成它：

cmake -DBOARD=qemu_cortex_m3 <你的应用路径>

再在工作区级设置里把 IntelliSense 指向它：

{ "C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json" }

这一行配好，zephyr 目录下的代码跳转就准了。同理，把 west build、menuconfig 等命令绑定成 VSCode 任务，把 gdb 配进调试配置，图形界面里就能完成编译和调试。工作区可以直接参考 zephyr code-workspace 工作区配置，插件与任务细节见 VSCode 进行 Zephyr 应用开发文档。

踩坑速查：常见报错与对策

⚠️ 卡住时对照下表查：

现象	原因	对策
west: command not found	west 不在 PATH 中	在容器里 cd 到 zephyr 目录后`source zephyr/zephyr-env.sh`
docker pull 极慢或超时	国内镜像源没配	回上节补上 registry-mirrors 并重启 Docker
C 盘空间被占满	镜像存储位置没改	修改 Disk image location 到其他盘符
容器里改的文件 Windows 侧看不到	挂载参数 -v 路径写错	核对本地目录与 /workdir 的映射
容器 exit 后以为"没了"	exit 只退出会话，容器还在	`docker start SIG_Zephyr`再`docker attach SIG_Zephyr`