企业官网建设流程全解析

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 应用，这篇文章给出了一条可落地的路径：提前把源码、模块仓库、SDK 与 Python 依赖搬到本地，再绕过west update手动指定构建参数。读完并照做后，你的内网机器应能完成离线构建，产出zephyr.elf等固件文件，并可通过手动烧录方式验证到板。

什么时候需要离线环境

以下三种情况比较典型：

• 临时断网：出差、高铁、展会现场，机器只能用蜂窝热点甚至没有网络，但需要继续改代码、出固件。
• 内网隔离：产线调试机、安全域内的开发机按制度不允许访问公网，west update、SDK 在线下载、pip 拉包都会被防火墙拦截。
• 弱网/限流环境：网络能通但极慢或不稳定，大仓库反复克隆、断点续传失败，提前准备本地镜像反而更省事。

需要说明一点："离线"依赖的是提前准备好的本地资源包，并不是机器本身不依赖任何外部资源。资源准备阶段（克隆仓库、下载 SDK 和 pip 包）通常仍需要一台能联网的机器完成。

离线资源怎么备：清单与数量

准备模块仓库时，west.yml 是唯一权威清单。每一项包含name（仓库名）、path（在工程内应放置的目录）和revision（应检出的提交号）。建议直接用脚本提取，避免手工抄漏：

# 在联网机器上，输出模块清单（示例：grep 快速浏览） grep -E 'name:|path:|revision:' west.yml | head -50

克隆时的对应关系是：git clone <仓库地址> <path字段值>，然后进入该目录git checkout <revision字段值>。主仓库可以从官方镜像获取，例如：

git clone https://gitcode.com/GitHub_Trending/ze/zephyr

环境装配路线：目录、SDK、依赖、构建参数

按"目录结构 → SDK 落盘 → Python 依赖 → 构建参数"四步走，每一步都有明确的完成标志。

1. 目录结构落位

在目标机器上先搭好骨架（以~/zephyrproject为工作区）：

mkdir -p ~/zephyrproject && cd ~/zephyrproject cp -r /path/to/local/zephyr . # 主仓库，放到 zephyrproject/zephyr mkdir -p modules/hal modules/lib bootloader tools # 按 west.yml 的 path 字段，把各模块仓库复制到对应子目录

完成后执行find . -maxdepth 2 -type d，应能看到zephyr、modules/hal/nordic之类的目录。目录名与west.yml的path不一致是后续"找不到模块"问题的最常见来源。

2. Zephyr SDK 离线落盘

把提前下载好的 SDK 压缩包拷到目标机器后解压、执行其自带的安装脚本：

mkdir -p ~/zephyr_sdk tar xf ~/zephyr_offline/zephyr-sdk-*.tar.xz -C ~/zephyr_sdk cd ~/zephyr_sdk && ./setup.sh # 脚本会把工具链放到对应版本子目录

脚本执行完成后，用ls ~/zephyr_sdk确认出现带版本号名的 SDK 目录。然后配置环境变量，让 CMake 使用 SDK 自带的交叉工具链：

# 仅当前会话生效 export ZEPHYR_TOOLCHAIN_VARIANT=zephyr export ZEPHYR_SDK_INSTALL_DIR=$HOME/zephyr_sdk/<实际SDK目录>

需要长期生效时，把上面两行追加到~/.bashrc（zsh 用户改为~/.zshrc）再source一下。执行which zephyr-env.sh能找到文件，说明路径配置正确。

3. Python 依赖离线安装

如果只用 CMake 直接构建（见下文），Python 依赖并不是硬门槛；但若你还要用 west 命令或构建文档，就需要离线安装。在联网机器上先拉包：

pip download -r doc/requirements.txt -d ~/zephyr_offline/pip_pkgs

再在目标机器建虚拟环境，只从本地目录安装：

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

--no-index的作用就是禁止访问 PyPI。执行结束应看到一系列Successfully installed ...；若报No matching distribution found，说明离线包里缺对应平台/版本的 wheel，需要回到联网机器补齐。west 自身的依赖以它仓库内的 requirements 清单为准，离线包中一并包含即可。

4. 模块路径替换方案（不依赖 west 的构建参数）

官方对"不使用 west 构建"的说明见 doc/develop/west/without-west.rst。核心思路是：west build平时会自动把模块目录汇总进ZEPHYR_MODULES变量，现在改为手动传：

cd ~/zephyrproject cmake -B build \ -S /path/to/your_app \ -DBOARD=nrf52840dk/nrf52840 \ -DZEPHYR_MODULES=$HOME/zephyrproject/modules/hal/nordic;$HOME/zephyrproject/modules/lib/picolibc ninja -C build

两个注意点：

• ZEPHYR_MODULES用分号分隔多个路径，bash 中建议整体加引号或用$展开变量；
• 列表按你的应用实际用到的模块裁剪，hal_*、picolibc、mbedtls等是最常见的几类，具体以 Kconfig 提示和构建报错为准。

最小构建验证：用 qemu_x86 或 hello_world 打通链路

环境是否可用，用一个最小样例来验证最直接。仓库自带 samples/hello_world/，配合qemu_x86板可以完全在软件上跑通，不依赖实体开发板：

cd ~/zephyrproject cmake -B build_qemu \ -S ~/zephyrproject/zephyr/samples/hello_world \ -DBOARD=qemu_x86 ninja -C build_qemu

hello_world 用到的内核与库都在主仓库内，多数情况下不需要额外模块路径即可编过；若报错提示缺少某个模块，再按前面第 4 小节的办法补充ZEPHYR_MODULES。

成功判断标准：构建结束无FAILED，且build_qemu/zephyr/下生成了zephyr.elf、zephyr.bin等产物。随后可选跑一次 QEMU 确认程序能打印输出。这一步通了，说明"源码 + 模块 + 工具链 + 构建参数"四件套在离线状态下是齐的，再换成真实板子目标（-DBOARD=...）做正式构建即可。

烧录与边界说明

验证到实体板上，手动烧录是最通用的方式。下面以 nRF52840 系列开发板 + J-Link 为例，命令为可直接执行的示例：

JLinkExe -device nrf52840_xxaa -if swd -speed 4000 -autoconnect 1 # 进入交互提示符后依次输入： # > loadbin build/zephyr/zephyr.bin 0x0 # > r # > q

不同开发板需要替换三处参数，否则可能连接失败或烧录错位：

OpenOCD、pyOCD 等工具同理，各板支持的工具与参数可在 doc/develop/flash_debug/host-tools.rst 和对应boards/<厂商>/<板子>/文档中查到。没有west flash时，这些宿主工具就是唯一的烧录入口，属于 west 替代方案的一部分。

故障定位：构建失败先查这里

排查顺序建议从下往上走：先确认 CMake 配置阶段能否找到 SDK 和模块，再看编译，最后才是链接与烧录。

资产维护建议

离线环境建好之后，还要能长期用下去：

• 本地镜像定期更新：约定每月（或每次主仓库升级时）在联网机器上对各仓库git fetch，把主仓库与模块仓库一起打包搬运。主仓库每次更新后，west.yml 中的revision都会变，模块仓库必须跟着重新git checkout，否则就是清单里的"版本不匹配"问题。
• 依赖版本化管理：pip_pkgs目录按用途分子目录存放，并记录每次打包对应的 requirements 清单和日期；换 Python 小版本前先确认离线包是否覆盖。
• 备份策略：源码、SDK、pip 包分三份存放，例如：

# 源码备份（排除 .git 可显著减小体积；需要保留历史就去掉 --exclude） tar czf zephyr_src_$(date +%Y%m%d).tar.gz --exclude=.git -C ~ zephyrproject # SDK 与依赖包同步到外部磁盘 rsync -av ~/zephyr_sdk ~/zephyr_offline /path/to/external/drive/

• 记录环境快照：把主仓库提交号、SDK 版本（对照 SDK_VERSION）、各模块 revision 写成一份简短笔记放在工作区，换机器复现环境时能一次对齐。

下一步

当离线链路稳定后，可以顺着 doc/develop/west/without-west.rst 理解手动构建的完整语义，再结合 samples/hello_world/ 的prj.conf学习 Kconfig 如何驱动构建。Windows 或不同工具链版本的机器上，路径分隔符与环境变量写法会有差异，命令执行前先按当前系统习惯做一次小范围验证。祝编译顺利。

【免费下载链接】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