Zephyr RTOS 离线开发环境完整搭建指南：内网隔离也能编译烧录-平芜编程栈

Zephyr RTOS 离线开发环境完整搭建指南：内网隔离也能编译烧录

【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr

工厂内网的开发终端连着外网代理都打不开，安全审计又要求构建机彻底断网——在这种场景下，一套 Zephyr RTOS 离线开发环境不是锦上添花，而是开工的前提。原理并不复杂：把构建系统平时会在线请求的资源，全部提前在联网机器上备好，整体搬进内网，再用 CMake 直接驱动构建。

离线资源全景：离线编译环境到底要备齐什么

动手之前先看整体。Zephyr 的构建流程会在 5 类资源上产生网络需求，逐项对照准备：

资源	作用	联网环境下的获取方式	离线机落位
主源码	内核、驱动、构建系统	`git clone https://gitcode.com/GitHub_Trending/ze/zephyr`	`zephyrproject/zephyr`
west 模块	west.yml 中列出的 HAL、中间件	逐个仓库 clone 并 checkout 到指定 revision	`zephyrproject/modules/...`
Zephyr SDK	交叉编译工具链	官网下载与 SDK_VERSION 一致的`zephyr-sdk-*.tar.xz`	解压目录，如`~/zephyr_sdk`
Python 依赖	构建脚本与文档工具	`pip download -r doc/requirements.txt -d pip_pkgs`	`zephyr_offline/pip_pkgs`
烧录工具	将固件写入目标板	厂商官网下载（J-Link、pyocd 等）	本机安装

模块清单是最容易被低估的一项：west.yml里每个项目都带name、path、revision三行，注意带repo-path字段的条目其仓库名与项目名不同，克隆时别放错目录。可选组（如babblesim）的模块与目标板无关时可以直接跳过。

阶段一：资源收集——在联网机器上一次性完成

这一步的目标是把上表全部资源收进一个目录，之后整个目录经 U 盘或scp搬到内网机，后续操作不再需要任何网络。

mkdir -p ~/zephyr_offline && cd ~/zephyr_offline git clone https://gitcode.com/GitHub_Trending/ze/zephyr zephyr pip download -r zephyr/doc/requirements.txt -d pip_pkgs # 再下载 zephyr-sdk-*.tar.xz 放入同目录

模块仓库逐个 clone 进modules/子目录，命名与west.yml的path字段对齐。建议同时记录每个模块 checkout 的 commit，方便阶段三核对。

阶段二：环境组装——SDK 本地安装与依赖落位

在离线机（或联网机预演）上组装可运行环境。先装工具链：解压 SDK、执行其中的setup.sh，然后导出两个关键变量，写入~/.bashrc可长期生效。

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr export ZEPHYR_SDK_INSTALL_DIR=$HOME/zephyr_sdk

Python 依赖走"虚拟环境 + 本地包索引"，--no-index确保 pip 完全不碰网络：

python3 -m venv ~/zephyrproject/.venv . ~/zephyrproject/.venv/bin/activate pip install --no-index --find-links=~/zephyr_offline/pip_pkgs -r doc/requirements.txt

west 模块离线部署的最后一步是版本对齐：进入每个模块目录执行git checkout <west.yml 中的 revision>。版本不匹配不会在克隆时报错，而是等到编译某个具体功能时才暴露，所以这一步不能省。

阶段三：构建打通——无 west 直接用 cmake

没有 west 时，构建系统靠ZEPHYR_MODULES变量定位模块源码，等价于 west 自动生成的清单。官方对该流程有专门说明：不使用 west 构建。

cd samples/hello_world cmake -B build -DBOARD=qemu_x86 -DZEPHYR_MODULES=../../modules/hal_nordic;../../modules/hal ninja -C build

配置成功即生成build/zephyr/zephyr.elf。

烧录验证

编译通过只算完成一半。以 Adafruit Feather nRF52840 Express 为例，用 J-Link 走 SWD 烧录：

JLinkExe -device nRF52840_xxAA -if SWD -speed 4000 -AutoConnect 1 > loadbin build/zephyr/zephyr.bin 0x0 > r > q

串口收到Hello World!即闭环。各板级的探针与接线细节见烧录调试工具文档，板卡支持范围以 boards/ 目录为准。

验收清单：6 项逐项打勾再谈交付

每个模块目录的HEAD与west.yml中对应revision一致
echo $ZEPHYR_SDK_INSTALL_DIR指向已解压目录，且内含setup.sh
venv 内执行pip check无冲突输出
cmake配置阶段无 missing module、Could NOT find类告警
build/zephyr/zephyr.elf与zephyr.bin均已生成
目标板烧录后串口输出 hello world 内容

✅ 6 项全勾，环境即可纳入团队的内网基线镜像。

避坑速查：现象 / 原因 / 处理

现象	原因	处理
编译报某符号未定义、提示缺仓库	对应模块未克隆或 revision 没对齐	对照 west.yml 补克隆并`git checkout`指定提交
`cmake`提示找不到交叉编译器	工具链变量未导出或路径错误	检查`ZEPHYR_TOOLCHAIN_VARIANT`、`ZEPHYR_SDK_INSTALL_DIR`两变量
`pip install --no-index`找不到包	联网机与离线机 Python 版本或架构不同	用相同`python3`版本重新`pip download`
SDK 不支持目标板架构	SDK 版本落后于源码要求	按`SDK_VERSION`文件重下匹配的 SDK
`ninja`链接阶段报模块相关错误	`-DZEPHYR_MODULES`漏写该模块路径	补上对应`modules/xxx`路径后重新配置