企业官网建设流程全解析

zephyr-cn 带你从零搭好 Zephyr 开发环境（Windows + Docker）

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

第一次搭 Zephyr 开发环境，最容易卡在没有 Linux 工具链。跟着 zephyr-cn 走一遍：Docker 把构建环境装进 Windows，源码和 SDK 落地，QEMU 里跑通第一个示例，VSCode 和 West 接管日常开发。走完这条线，你手里就有一条从开机到 philosophers 输出的完整可复现路径。

📦 备齐三样物料，把 Zephyr 工程与 SDK 摆上桌

先说原因：Zephyr 的构建链靠 west、CMake、Python 配合，Windows 上没有现成工具链，后面所有步骤都跑在 Linux 容器里，所以源码和 SDK 需要从 Windows 这边"带"进去。

需要准备的三份东西（下载入口见 doc/source/develop/windows_docker.rst 的准备阶段）：

• sig_zephyr_v2.7.4.tar.gz：基于 Zephyr LTS 2.7.4、按工程布局打包的源码包；
• zephyr-sdk-0.13.1-linux-x86_64-setup.run：SDK，即 arm-zephyr-eabi-gcc 等交叉编译工具链的安装包；
• Docker Desktop V4.18.0 和 Windows Terminal。

解压后顶层会看到五个目录：zephyr（主仓库）、modules（第三方模块）、.west（工作区标记）、tools、bootloader。你即将构建的，就是下图这套结构：

zephyr-cn 仓库里的 Zephyr 架构图；编译 philosophers 时，你实际构建的就是这套结构中的内核与子系统。

验证点：三个文件就位、下载说明读了一遍，剩下的只是搬运和装配。

🐳 三步把 Linux 构建环境搬进 Docker 容器

用现成的 Zephyr Project 官方构建镜像zephyrprojectrtos/zephyr-build，比装整台 Linux 虚拟机轻得多——镜像里已带 west、CMake、Python 工具链，这套流程就是 Windows Zephyr Docker 环境搭建的主体。

先改镜像存储位置，再配国内镜像加速

为什么要动这两处：镜像约 12GB，默认存 C 盘会很快被吃满；默认源在国内访问也不稳定。

在 Docker Desktop 的 Settings → Resources 里把 "Disk image location" 改到非 C 盘；再在 Docker Engine 配置里加上国内加速地址：

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

保存后重启 Docker Desktop 生效。

拉取 zephyr-build 官方镜像

打开 Windows Terminal，执行：

docker pull zephyrprojectrtos/zephyr-build:latest

做对长什么样：docker images列表里出现zephyrprojectrtos/zephyr-build latest，SIZE 一栏约 12.1GB：

docker pull zephyr-build 的终端截图：各层下载完成并显示 digest，确认镜像已就绪。

创建挂载容器，把 Windows 目录映射进 /workdir

为什么要挂载：源码和 SDK 要在 Windows 和容器之间来回传，把D:/Workspace/SIG_Zephyr挂到容器的/workdir，两边看到的是同一份文件：

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

做对长什么样：提示符切换成容器内的user@<id>:/workdir$，ls能直接看到 D 盘里放的两个文件：

docker run 创建 SIG_Zephyr 容器并挂载 /d/Workspace/SIG_Zephyr 到 /workdir 后的终端，确认已处于容器内。

⚙️ 解压源码装 SDK，用 west update 把依赖拉齐

先把sig_zephyr_v2.7.4.tar.gz和 SDK 安装包放进D:/Workspace/SIG_Zephyr，然后在容器里解压：

tar -xvzf sig_zephyr_v2.7.4.tar.gz

做对长什么样：ls -a多出.west、zephyr、modules、tools、bootloader，工程布局完整。

接着执行west update。它按zephyr仓库里的清单文件west.yml（相当于项目"购物清单"）把缺失的依赖仓库克隆到位、把已有的对齐版本，这一步同时就是对工程布局完整性的快速体检：

west update

做对长什么样：命令正常退出，清单里列出的项目仓库全部检出到指定版本。

最后安装 SDK（按 Zephyr 官方 Getting Started 的 Install a Toolchain 章节操作，下载步骤可跳过，因为安装包已经在你手里）：

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

🚀 编译 philosophers，在 QEMU 里看第一个示例跑起来

为什么要选它：哲学家例程是验证工具链全通的最短路径；目标板qemu_cortex_m3是纯软件仿真板，不依赖任何硬件。这也正是 Zephyr 示例应用 QEMU 运行的标准路径：

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

-p auto按构建目录状态决定要不要强制干净构建，-b指定目标板——Zephyr 里"板子"指 CPU + 外设 + 设备树的组合。

做对长什么样：CMake 配置阶段打印版本、编译器与板级信息，构建跑满 130/130，最后输出 FLASH/SRAM 占用和生成的zephyr/zephyr.elf：

west build 编译过程截图：CMake 配置信息与 130/130 构建完成，验证工具链、板级配置全部就位。

运行：

west build -t run

做对长什么样：终端持续刷出五位哲学家的 THINKING / EATING 状态，开头能看到*** Booting Zephyr OS build v2.7.4 ***。按Ctrl+C中止例程（或Ctrl+A再按x退出 QEMU）。

west build -t run 后的终端输出：哲学家状态持续刷新，验证内核线程与互斥锁按预期工作。

✨ 把日常写码搬进 VSCode：插件、工作区与 IntelliSense

Zephyr 社区的主流开发方式是"编辑器改码 + 命令行编译调试"。VSCode 插件体系把命令行这层皮包起来，构建核心还是 west + CMake，但浏览、构建、调试都图形化了。Zephyr VSCode 插件与 IntelliSense 配置的重点，就是这一节的四件事。

装齐五个 Zephyr 插件

C/C++（IntelliSense 与调试）、CMake、kconfig（Kconfig 配置支持，Kconfig 是 Zephyr 的编译期选项系统）、nRF DeviceTree（设备树支持）、Arm Assembly（ARM 汇编支持），另外可以加个 Trailing Spaces 高亮行尾多余空格。

用 multi-root 工作区布局打开整个工程

用 multi-root workspace（VSCode 把多个目录当同一个工程打开的能力）组织工程，建议布局：zephyr（OS 代码）、modules（按需加入的模块）、app（自定义应用，用自带例程可省）、build（单独存放，避免构建产物污染 zephyr 的 git 仓库）。仓库里有一份现成参考：vscode/zephyr.code-workspace，关键是 workspace 层级把C_Cpp.default.compileCommands指向构建目录的编译数据库。

生成 compile_commands.json，让 IntelliSense 看懂 Zephyr

为什么需要它：Zephyr 代码规模大，C/C++ IntelliSense 的默认配置覆盖不了，必须喂它编译数据库。CMake 每次配置后都会生成compile_commands.json，包含本次构建涉及的文件和全部编译选项。

做法：在 build 目录执行cmake -DBOARD=qemu_cortex_m3 samples/philosophers（或走下面的"Zephyr 配置"任务）先生成它，再在 workspace 设置里把C_Cpp.default.compileCommands指过去。注意它只覆盖本次构建用到的部分——构建没开网络功能时，subsys/net下的代码不会被索引，属正常现象。

用 tasks.json 与 launch.json 接上构建和调试

构建相关任务（build、menuconfig、clean 等）写进build/.vscode/tasks.json，之后在 VSCode 的 Run Task 菜单里选对应 Zephyr 任务即可；调试通过build/.vscode/launch.json的 launch 机制接上 gdb，断点、单步、看变量全部图形化。两份配置的参考实现在 doc/source/develop/vscode.rst。

用 Docker 插件直接 Attach 进容器写码

装 Docker 扩展，在 Containers 视图里找到运行中的SIG_Zephyr容器，点 "Attach to Container"，就得到一个容器内的完整开发会话，不用再切终端敲命令。

🧭 用 West 管好后续迭代：四个概念加一组命令

记住四个概念，West 就不难（详见 doc/source/develop/west/basic.rst）：

• 顶级目录：工作区根目录，比如我们解压出的那个顶层文件夹；
• .west目录：标记顶级目录的位置，west 从当前目录向上找.west，其父目录即顶级目录；
• 清单仓库：包含west.yml的 Git 仓库，对 Zephyr 来说就是zephyr目录；
• 项目：由 west 管理的 Git 仓库，在清单文件里定义（modules下那些仓库都是）；west build等命令则是 zephyr 仓库借扩展命令机制提供的。

日常命令速查：

出错先翻这一页：新手高频坑速查

• 退出容器后不知道怎么回去：exit退出；docker start SIG_Zephyr启动；docker attach SIG_Zephyr进入。
• 提示west: command not found：环境没加载，在顶级目录先执行source zephyr/zephyr-env.sh。
• VSCode 里看不到容器中的文件：装 Docker 扩展并 "Attach to Container"，别直接打开本地目录。
• QEMU 一直刷停不下来：Ctrl+C中止例程；Ctrl+A, x退出 QEMU。
• C 盘告警或拉镜像慢：回头检查镜像存储位置与国内加速源两项配置。

接下来你可以把 samples 里的例程换成自己的应用，用west build -t debug进 GDB 打上第一个断点；然后顺着开发者参考里的内核章节（互斥锁、信号量、线程通信）把环境吃透，再开始写业务逻辑。

• doc/source/develop/index.rst：开发者参考主页（内核、子系统、驱动）
• doc/source/develop/vscode.rst：VSCode 开发详细配置
• doc/source/develop/west/basic.rst：West 基本概念
• vscode/zephyr.code-workspace：参考工作区配置

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