企业官网建设流程全解析

Zephyr 离线开发环境完整指南：3 步在无网 Linux 机器上完成编译

【免费下载链接】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。如果你的开发机处在内网隔离实验室、军工或产线环境，连不上外网，那么west update、SDK 下载、pip install会全部失败。这篇文章教你把一整套 Zephyr 离线开发环境搬进无网机器：源码、模块、工具链、Python 依赖全部走本地，编译验证用 QEMU，不依赖任何硬件。

这套方案做完你能拿到什么

• 一台完全断网也能出固件的编译机：从cmake配置到生成zephyr.elf全程零网络请求
• 可复用的资源包：一个 workspace 压缩包 + 一个 pip 依赖目录 + 一个 SDK 安装包，以后换机器直接解压
• 两条路线：默认保留west工具（推荐），也讲不清理 west 的纯 CMake 路线，方便你按团队规范选择

准备工作：两台机器和四样资源

你需要一台有网的装配机（负责下载）和一台无网的目标机（Linux，最终编译用）。资源清单如下：

磁盘留 10GB 以上。workspace 里包含主仓库和几十个模块仓库，加上.git历史，体积不小。

核心思路：把所有"网络动作"换成"本地动作"

Zephyr 的构建依赖不止主仓库。清单文件 west.yml 把几十个模块仓库（HAL、驱动库、加密库等）的名称、路径、固定提交号全部钉死，west工具负责按这份清单批量克隆并切到对应版本。

zephyrproject/ ├── zephyr/ # 主仓库（含 west.yml 清单） ├── modules/ │ ├── hal/... # 各厂商 HAL │ ├── lib/... # 通用库 │ └── crypto/... # 加密模块 └── bootloader/ # 如 mcuboot

所谓"离线化"，本质上只做了两件事：把"从远程 URL 克隆"换成"从本地压缩包恢复"，以及把"pip 在线安装"换成--no-index本地安装。构建系统本身完全感知不到断网，只要模块目录在位、版本正确。

Zephyr 多仓库模型（主仓库与模块仓库的关系）：

六步搭好离线环境

第 1 步：在联网机上装配完整工作区

west init -m https://gitcode.com/GitHub_Trending/ze/zephyr zephyrproject cd zephyrproject west update # 按 west.yml 克隆全部模块并切到固定提交 west status # 确认输出为空，即全部模块与清单一致

west status必须为空再往下走。它不为空说明有模块版本漂移，带病打包后目标机上一定报错。

第 2 步：下载其余两件资源

# Python 依赖（注意把 west 本身也下载进同一目录） pip download west -r zephyrproject/zephyr/scripts/requirements-west.txt -d pip_offline # 整个工作区打包（.git 目录一并带走，模块靠它做版本校验） tar czf zephyrproject.tar.gz zephyrproject # SDK 离线包：下载 zephyr-sdk-1.0.1_linux-x86_64.tar.xz，版本号对照 SDK_VERSION 文件

pip download的机器最好与目标机使用相同 Python 大版本和 CPU 架构，否则离线安装时会出现 "No matching distribution"。

第 3 步：恢复工作区并装 Python 依赖（目标机）

tar xzf zephyrproject.tar.gz pip install --no-index --find-links=../pip_offline west -r zephyrproject/zephyr/scripts/requirements-west.txt cd zephyrproject

恢复后不要运行west update——它会尝试连网络。模块已就位且版本正确时，west不会主动发起任何网络请求。

第 4 步：安装 Zephyr SDK

mkdir -p ~/zephyr_sdk tar xf ~/zephyr_offline/zephyr-sdk-1.0.1_linux-x86_64.tar.xz -C ~/zephyr_sdk source ~/zephyr_sdk/zephyr-sdk-1.0.1_linux-x86_64/setup.sh # 把 SDK 的交叉编译器加入 PATH

setup.sh只作用于当前 shell，需要永久生效就追加到~/.bashrc。

第 5 步：编译 hello_world（保留 west 路线）

cd zephyrproject/zephyr west build -b qemu_x86_64 samples/hello_world

-b指定目标板，samples/hello_world 是最小的验证工程；qemu_x86_64是仓库自带的 QEMU 虚拟板（见 boards/qemu/），不需要真实硬件。

第 6 步（可选）：不装 west 的纯 CMake 路线

如果你的环境禁止安装west，可以直接调 CMake，但需要手动把所有模块路径喂给构建系统，通过-DZEPHYR_MODULES=路径1;路径2;...参数列出，模块清单仍对照 west.yml。官方对该路线的说明见 doc/develop/west/without-west.rst：

cmake -S samples/hello_world -B build \ -DBOARD=qemu_x86_64 \ -DZEPHYR_MODULES=/path/to/modules/hal/st;/path/to/modules/lib/picolibc ninja -C build

模块越多，这个分号列表越长。这也是官方建议新手保留west的原因：它替你自动维护ZEPHYR_MODULES。

怎么确认环境真的通了

两个可观测的成功标志：

west build -t run # 在 west build 之后执行，直接启动 QEMU

• 终端先打印*** Booting Zephyr OS ***，随后出现Hello World! qemu_x86_64—— 从 CMake 配置、编译、链接到运行全链路贯通
• 构建目录生成build/zephyr/zephyr.elf和zephyr.bin，ls -lh能看到非零大小的固件文件

看到Hello World! qemu_x86_64就代表无网编译已可用；之后只需把-b qemu_x86_64换成真实板卡名（如nrf52840dk/nrf52840），固件烧录方式参考 doc/develop/flash_debug/host-tools.rst。

三个高频报错的处理方法

现象 1：构建时提示要访问网络 / 克隆仓库失败

原因：工作区里有模块与清单版本不一致，工具想拉取远端同步。

处理：回到装配机重新west update并确认west status为空后重新打包；个别缺失模块可手动从本地副本克隆，再git checkout到 west.yml 里对应的revision提交号。

现象 2：CMake 报找不到 SDK 工具链或ZEPHYR_BASE未定义

原因：当前 shell 没执行过 SDK 的setup.sh，或 west 工作区路径没被识别。

处理：在当前 shell 先source ~/zephyr_sdk/zephyr-sdk-1.0.1_linux-x86_64/setup.sh；确认你在zephyrproject/zephyr目录内执行，且west topdir输出为zephyrproject。

现象 3：pip install --no-index提示找不到某个依赖

原因：pip_offline目录是用不同 Python 版本或不同 CPU 架构下载的，预编译包对不上。

处理：在与目标机同版本 Python、同架构的联网机上重新执行第 2 步的pip download，整个目录覆盖后再装。

日常维护与进阶

• 月度更新节奏：联网机执行west update && west status，确认干净后重新打包替换目标机上的 workspace，一次完成源码 + 模块 + 清单同步
• 版本基线纪律：模块提交号以 west.yml 为准，SDK 版本以 SDK_VERSION 为准，两者是配套发布的，不要拿旧 SDK 配新源码
• 按需裁剪：若项目只用少数模块（如只做 STM32 + UART），可按 west.yml 的path字段手工维护一份精简的-DZEPHYR_MODULES列表，显著缩小打包体积
• 想深入构建原理，从根目录 CMakeLists.txt 和 Kconfig 入手即可

下一步：把zephyrproject.tar.gz拷上你的无网机器，跑通west build -t run，在 QEMU 里看到那句Hello World!，离线开发环境就算正式交付了。

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