搞嵌入式开发第一次接触 Zephyr 的人十有八九都会被它的环境搭建整到心态爆炸。这个东西本身要通过 west 去拉一堆仓库还要配工具链、配 Python 环境、装各种系统依赖每一步都可能卡住。尤其是在国内GitHub 的访问速度又不太给力几十 KB 的下载速度能让你从中午折腾到晚上。Ubuntu 24.04 又是个新系统官方文档很多还停留在旧版本假设上照着文档一步步走报错一个接一个。这篇文章就是记录我怎么在 Ubuntu 24.04 上用国内镜像把 Zephyr 开发环境搭建起来并且把整个流程里值得注意的坑都标出来。不管你是刚入坑 Zephyr 的新手还是已经被环境整到想摔键盘的老手这篇内容应该都能帮你少走几段弯路。1. 环境搭建的整体思路与前置准备1.1 为什么 Zephyr 环境搭建在 Ubuntu 24.04 上会“劝退”新人Zephyr 不是那种 clone 下来就能编译的普通 RTOS。官方推荐的 west 工作流会把整个项目拆成 zephyr、zephyr-workspace 和一堆 moduleshal、cmsis、openthread 等分散在不同的 Git 仓库里。这意味着环境搭建过程中真正耗时的地方不是写代码而是拉仓库和解决依赖关系。国内访问 GitHub 的延迟和速度问题在这套工作流里被放到了最大。第二个“重”在于工具链。Zephyr 支持非常多架构和厂商扩展官方建议直接用 Zephyr SDK 来搞定交叉编译、调试、烧录等全套工具。SDK 本身就有几个 GB 的体积如果下载通道不给力光是等这个就能让人崩溃。Ubuntu 24.04 上还会遇到系统自带的 CMake、Python 3 版本都比较新但 west 和部分模块可能对某个版本有兼容要求需要单独处理。这些事情叠加在一起就形成了一个很典型的“环境地狱”场景不是代码写不出来而是环境搭不起来。我见过很多人在群里问“为什么我编译 hello_world 都报错”一问多半是环境搭建时省了哪一步或者版本对不上。所以这篇文章会把前置准备、源替换、仓库同步、SDK 安装完整走一遍目标只有一个让任何一台全新 Ubuntu 24.04能在半小时以内跑起 Zephyr 编译。1.2 镜像加速的整体思路先解决“搬运”问题再解决“编译”问题我的优化思路可以总结成一句话先解决“搬运”问题再解决“编译”问题。很多人的误区是一开始就盯着编译器、CMake、Ninja 这些编译链路上的工具使劲折腾结果装好了还是拉不下代码整体速度没有任何提升。实际上 Zephyr 环境搭建里大部分时间都消耗在“把代码从远程仓库挪到本地”这件事上编译本身反而很快。所以我把整个流程拆成两个阶段。第一个阶段是“提速搬运”把 apt、pip、Git 仓库、SDK 下载这四条链路的源都指向国内可快速访问的镜像地址确保数据能快速落地。第二个阶段才是“正确编译”在代码和工具链都齐了之后按官方文档把 west 环境初始化好用匹配的 Zephyr SDK 编译 sample 工程。这样一来每一次操作的时间都被压得很短整体效率提升非常明显。我自己最直观的感受是优化之前在一台网速一般的机器上装 Zephyr从零到能编译 hello_world搞了将近两个小时其中一半时间都在等下载。优化之后同样的机器从换源到编译出第一个 bin 文件大约只花了 30 分钟。这个差距不是机器性能带来的而是下载路径选对了。2. 镜像加速的四条链路与方案对比2.1 四个卡点apt、pip、Git 仓库、SDK 下载Zephyr 环境搭建在国内通常卡在四个地方apt 系统依赖、pip 的 Python 包、GitHub 上的 west 仓库、以及 Zephyr SDK 这类大体积离线包。这四个卡点各有不同的加速方式我的建议是分开处理不要指望一个“万能加速工具”解决所有问题。第一个是 apt 源。Ubuntu 默认源指向 archive.ubuntu.com国内访问速度只能说能用但装几十个依赖包时会明显感觉到等待时间长。解决方案是换成阿里云、清华或中科大的 Ubuntu 源。第二个是 pip 源。Zephyr 的 west 工具和一堆 Python 依赖包都是从 PyPI 下载默认源在国外速度不稳定。解决方案是配置清华 PyPI 镜像或阿里云 PyPI 镜像。第三个是 Git 仓库。Zephyr 主仓库和各个 module 仓库都在 GitHub 上west update 时要逐个去 clone。这里最典型的问题是单个仓库比较大比如 hal_stm32、hal_nordic 这类 HAL 仓库动辄几百 MB连接不稳定就很容易中断。解决方案是用国内代码托管平台上的仓库镜像或者给 Git 配置合理的浅克隆参数。第四个是 Zephyr SDK。这是最大的一个下载项压缩包体积接近 1 GB解压后更大。官方地址是 GitHub Releases国内下载很慢。解决方案是找国内镜像站的 GitHub Release 镜像路径例如清华镜像站就有同步。这四个卡点全部处理完搭建过程才会顺畅。我遇到过不少人只换了 apt 源后面卡在 west update 上跑来问我为什么还是慢其实就是因为其他三条链路没有同步处理。2.2 仓库镜像选型选对路径才是真加速关于“国内镜像”这个词网上有太多说法。有些是第三方做的 GitHub 加速工具需要你把请求转发到他们的服务器这类工具有隐私和安全风险我不太推荐用在开发环境里。更稳妥的方案是直接用大型代码托管平台上的公开镜像仓库比如 Gitee、GitCode 上都有 Zephyr 项目的同步副本这些是真实仓库的镜像访问路径完全在国内速度快且安全。具体操作上west init 时可以指定 manifest 仓库的地址。官方默认是west init -m https://github.com/zephyrproject-rtos/zephyr.git在国内网络环境下可以把 zephyr 主仓库地址替换成镜像地址比如west init -m https://gitee.com/zephyrproject-rtos/zephyr.git或者用 GitCode 上的镜像地址。但注意主仓库镜像化以后west update 去拉 modules 时每个 module 的仓库地址仍然写在 manifest 文件里默认指向 GitHub。如果所有 module 都走国外地址还是会卡。我的做法是只把 zephyr 主仓库用镜像初始化然后利用 Git 配置和浅克隆参数来加速 module 的拉取。比如在 west 初始化完成后执行west config --global zephyr.base ~/zephyrproject/zephyr west update --fetch-optimize--fetch-optimize会让 west 在更新时尽量复用本地已有的 Git 对象而不是每个仓库都全量重新 clone。此外在全局 Git 配置里加上浅克隆相关参数可以显著减少大仓库的传输体积。浅克隆不是不要历史而是只取最新提交对大多数只关心当前代码的开发者来说完全没有影响。这里有一个界线要注意镜像仓库本质上还是代码副本不是官方服务。如果后续需要往 Zephyr 提交代码或者要拉取最新主干最好还是切回官方源或者直接用 GitHub 的 fork 流程。镜像只负责“读”不负责“写”。2.3 版本匹配为什么优化之后反而更容易踩版本坑镜像加速解决的是“下载速度”问题但版本匹配是另一个容易翻车的点。很多人在换源之后下载速度是快了却因为 Zephyr 主分支过新、SDK 版本过旧编译时报出一堆只有资深玩家才看得懂的错。Zephyr 项目迭代很快main 分支几乎每天都在更新但 Zephyr SDK 的版本迭代相对滞后。官方文档里会注明“当前 main 分支建议使用 Zephyr SDK 0.17”如果你的 zephyr 仓库停在某个 release 分支比如 v3.7那配套的 SDK 可能是 0.16。版本不对编译时就会出现工具链与内核源码 API 不匹配的问题比如某些结构体字段对不上、某个编译器版本不支持新的内建函数等等。所以我的建议是在初始化阶段就锁版本不要盲目追 main。最稳的路径是cd ~/zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr.git --mr v3.7.0 west update--mr指定 manifest 的 revision这样整个 workspace 都会跟着 v3.7.0 这个版本走不会出现“刚拉的代码还没更新完下一个 commit 又变了”的情况。SDK 方面也尽量用和这个版本匹配的官方 SDK 版本。版本一旦锁定后面所有编译行为都可以预期排错也容易很多。3. 实操过程与核心环节实现3.1 系统依赖安装换源是第一步但注意 24.04 的源格式Ubuntu 24.04 和旧版本有一个明显区别软件源配置文件不再是传统的/etc/apt/sources.list而是改成了 deb822 格式的/etc/apt/sources.list.d/ubuntu.sources。很多教程还沿用旧方法去改 sources.list改了之后 apt update 报错或者不生效就是没注意到这个格式变化。我的做法是直接编辑 ubuntu.sources 文件把里面的URIs: http://archive.ubuntu.com/ubuntu/替换成国内镜像地址比如阿里云sudo sed -i s|http://archive.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources替换完执行sudo apt update sudo apt upgrade速度会有非常明显的提升。这里有个小细节deb-src 行也要保留有些依赖包在构建时需要源码索引如果你把 deb-src 注释掉后面装某些软件或者自己编内核模块时会找不到源。然后安装 Zephyr 要求的系统依赖包。官方列了一长串我整理成一条命令方便一次性装完sudo apt install -y git cmake ninja-build gperf ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc gcc-multilib g-multilib libsdl2-dev libmagic1这些包各自都有用途简单解释一下cmake 和 ninja-build 是构建系统核心gperf 用来生成哈希查找表device-tree-compiler 负责编译设备树dfu-util 是烧录工具libsdl2-dev 和 libmagic1 是部分 host 工具运行时的依赖。少了任何一个都可能在中途编译某个模块或者跑某个脚本时报错。3.2 Python 虚拟环境与 west 安装少踩 PATH 和权限的坑Zephyr 官方推荐用 Python 虚拟环境隔离 west 工具链这个建议在 Ubuntu 24.04 上尤其重要因为系统自带的 Python 3.12 环境非常干净但也非常容易被破坏。如果把 west 直接 pip install 到系统环境很容易因为权限不够、依赖冲突或者 distutils 移除问题导致安装失败。我推荐按以下步骤操作python3 -m venv ~/zephyr-venv source ~/zephyr-venv/bin/activate pip install --upgrade pip pip install west之后每次开新终端需要用source ~/zephyr-venv/bin/activate激活虚拟环境再执行 west 命令。如果你嫌麻烦可以把激活命令加到~/.bashrc里echo source ~/zephyr-venv/bin/activate ~/.bashrc source ~/.bashrc这里有个高频问题明明提示 west 安装成功了但输入west --version却提示 command not found。这通常是两个原因之一一是当前 shell 没有激活虚拟环境二是在虚拟环境激活状态下 pip 把 west 装到了虚拟环境目录但 shell 的 PATH 没有包含~/zephyr-venv/bin。可以用which west检查一下路径是否正确如果真的是 PATH 问题手动把export PATH$HOME/zephyr-venv/bin:$PATH写进~/.bashrc就行。Python 虚拟环境的好处是以后你在同一台机器上做其他 Python 项目不会因为 Zephyr 的依赖把系统环境搞得一团糟。哪怕 Zephyr 版本升级要换 west 版本也只需要删掉这个虚拟环境重建一个五分钟就能搞定。3.3 初始化 Zephyr 项目manifest 仓库地址的镜像玩法这一步是整个环境搭建的核心。我在 2.2 节说了可以用镜像仓库做 west init但这里要补充一个重要细节manifest 仓库换镜像之后west 会按照 manifest 文件里的内容去拉取其他 module也就是说加速效果并不取决于你是否换了镜像而取决于你在 manifest 文件里如何描述仓库来源。最直接的办法是在 west init 时直接指定镜像 manifest 仓库地址。比如mkdir ~/zephyrproject cd ~/zephyrproject west init -m https://gitee.com/zephyrproject-rtos/zephyr.git --mr v3.7.0初始化完成后执行west update。如果某个 module 速度很慢可以用浅克隆的方式来减少传输量。浅克隆在 Git 中的配置方式是git config --global http.postBuffer 524288000 git config --global core.compression 9第一个参数是提高 Git 上传下载的缓冲大小避免大仓库数据传输时因为缓冲区不足而失败第二个参数是提高压缩级别能减少网络传输的数据量但会增加 CPU 占用。实测下来对 hal_stm32 这类大仓库很有帮助。west update结束后可以检查一下当前状态west status west topdirwest status会列出每个 module 的版本状态west topdir会显示当前 workspace 根目录确认所有仓库都就位了就行。如果中途有仓库失败可以单独重试比如west update hal_stm32只更新这一个模块不用从头再来。3.4 安装 Zephyr SDK大文件下载的正确姿势Zephyr SDK 可以从官方 GitHub Releases 下载也可以从国内镜像站下的对应副本下载。这里推荐清华镜像站的 GitHub Release 镜像路径形如wget https://mirrors.tuna.tsinghua.edu.cn/github-release/zephyrproject-rtos/zephyr/zephyr-sdk-0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz下载速度比直接访问 GitHub Releases 快很多且文件完整性和官方保持一致。下载完成后解压到合适目录sudo tar -xvf zephyr-sdk-0.16.8_linux-x86_64.tar.xz -C /opt然后进入 SDK 目录运行安装脚本cd /opt/zephyr-sdk-0.16.8 sudo ./setup.sh -c-c参数会自动安装 host tools包括 pyocd、openocd、jlink 等调试工具链。如果你只是做编译不调试这些工具也不是必须的但建议还是装上因为后续跑 qemu、连开发板调试都会用到。安装完成后需要把 SDK 的环境变量配置好。SDK 自带的env.sh可以帮你设置 PATHsource /opt/zephyr-sdk-0.16.8/env.sh这里有个血泪教训如果你忘记 source env.sh或者把它放到了.bashrc里但路径写错那么编译时会直接报arm-zephyr-eabi-gcc: No such file or directory看着像编译器没装成功实际上是环境变量 PATH 里找不到工具链。所以在跑编译之前先检查一下which arm-zephyr-eabi-gcc如果能输出路径说明环境没问题如果提示找不到就去检查 env.sh 有没有被正确 source。3.5 编译验证以 STM32 为例跑通 hello_world环境全部搭好之后一定要在本地编译一次官方示例确认整条链路没有问题。我自己最喜欢拿hello_world来验证它足够简单也能覆盖从源码编译到链接成可执行文件的完整流程。以 STM32F746G-DISCO 这块板子为例命令如下cd ~/zephyrproject/zephyr west build -b stm32f746g_disco samples/hello_world编译过程中west 会自动创建build目录并用 CMake 配置、Ninja 编译。第一次编译会多一点时间因为要生成一些工程配置但整体不会超过两分钟。编译结束后检查生成的镜像文件ls build/zephyr/zephyr.elf build/zephyr/zephyr.bin这两个文件分别是对应的 ELF 可执行文件和纯二进制文件。zephyr.bin 可以直接用 dfu-util、openocd、pyocd 等工具烧到板子上跑。看到这两个文件出现说明你的 Zephyr 开发环境已经可以正式服役了。如果你用的是其他开发板比如 Nordic 的 nRF54L15 这类新板子也可以先跑一遍 hello_world 做验证但注意确认 SDK 版本是否支持该 SoC 的编译配置。新板子通常对 SDK 版本要求更严格宁可先用官方支持的版本也不要盲目追新。4. 常见问题与排查技巧实录4.1 经典报错速查表我把搭建过程中真正出现频次最高的问题整理成一张表方便你随时对照排查现象可能原因解决办法west: command not found虚拟环境未激活或 PATH 未包含 west 路径重新 source ~/zephyr-venv/bin/activate检查 which westwest update中途卡住或超时个别 module 仓库下载慢用浅克隆配置重试west update 模块名编译报arm-zephyr-eabi-gcc: No such file or directorySDK env.sh 没有 source或 SDK 版本不匹配执行 source /opt/zephyr-sdk-0.16.x/env.shCMake 报错找不到 Zephyr 内核未在 zephyr 目录下执行 west build或 west base 未配置cd ~/zephyrproject/zephyr 后重试或 west config zephyr.base 指定路径ModuleNotFoundError: No module named elftoolsPython 依赖缺失在虚拟环境里执行pip install pyelftools编译时提示找不到libsdl2系统依赖没装全重新执行 apt install libsdl2-devGCC 版本太旧导致编译失败系统 GCC 与 Zephyr 要求不匹配用 Zephyr SDK 自带编译器不要用系统 gcc 交叉编译这些问题是新手最常遇到的其实大部分都不是代码问题而是环境路径、依赖缺失或者版本不一致导致的。4.2 实战体验从 2 小时到 30 分钟优化的核心是“预取”最后聊聊我个人的实战体会。第一次在没有优化的情况下搭建 Zephyr 环境我大概花了两个多小时其中很大一部分时间是在等下载。后来我把 apt、pip、Git 仓库、SDK 四条链路全部换成国内镜像又在 west init 时锁定了版本之后在另一台全新 Ubuntu 24.04 上重新搭建了一次从开始执行命令到编译出 hello_world 的 bin 文件只用了大概 30 分钟。这个时间差的本质其实就是一个字“预取”。优化并不是让网络速度变快了而是让所有数据都能从离我更近、带宽更大的路径上“预取”过来。相当于从每次都要跨过半个地球去取快递变成了货物已经在本地分拣中心只要跑一趟就能拿全。再分享一个小技巧如果你经常在多个目录下切换工作不要每次都重新跑 west init 和 west update。可以保留一个基础 workspace然后通过west build -d参数指定构建目录或者直接用west build和west flash的组合完成从编译到烧录的完整流程。这样既能省去重复初始化 workspace 的时间又能保持代码版本的稳定性。搭建 Zephyr 环境这件事说难也难说简单也简单。难在网络和不兼容简单在只要把下载路径选好、版本锁定后面基本就是一条命令走到底。我已经把踩过的坑都写出来了希望你这次能一次顺利。
Ubuntu 24.04搭建Zephyr开发环境：国内镜像加速实战
搞嵌入式开发第一次接触 Zephyr 的人十有八九都会被它的环境搭建整到心态爆炸。这个东西本身要通过 west 去拉一堆仓库还要配工具链、配 Python 环境、装各种系统依赖每一步都可能卡住。尤其是在国内GitHub 的访问速度又不太给力几十 KB 的下载速度能让你从中午折腾到晚上。Ubuntu 24.04 又是个新系统官方文档很多还停留在旧版本假设上照着文档一步步走报错一个接一个。这篇文章就是记录我怎么在 Ubuntu 24.04 上用国内镜像把 Zephyr 开发环境搭建起来并且把整个流程里值得注意的坑都标出来。不管你是刚入坑 Zephyr 的新手还是已经被环境整到想摔键盘的老手这篇内容应该都能帮你少走几段弯路。1. 环境搭建的整体思路与前置准备1.1 为什么 Zephyr 环境搭建在 Ubuntu 24.04 上会“劝退”新人Zephyr 不是那种 clone 下来就能编译的普通 RTOS。官方推荐的 west 工作流会把整个项目拆成 zephyr、zephyr-workspace 和一堆 moduleshal、cmsis、openthread 等分散在不同的 Git 仓库里。这意味着环境搭建过程中真正耗时的地方不是写代码而是拉仓库和解决依赖关系。国内访问 GitHub 的延迟和速度问题在这套工作流里被放到了最大。第二个“重”在于工具链。Zephyr 支持非常多架构和厂商扩展官方建议直接用 Zephyr SDK 来搞定交叉编译、调试、烧录等全套工具。SDK 本身就有几个 GB 的体积如果下载通道不给力光是等这个就能让人崩溃。Ubuntu 24.04 上还会遇到系统自带的 CMake、Python 3 版本都比较新但 west 和部分模块可能对某个版本有兼容要求需要单独处理。这些事情叠加在一起就形成了一个很典型的“环境地狱”场景不是代码写不出来而是环境搭不起来。我见过很多人在群里问“为什么我编译 hello_world 都报错”一问多半是环境搭建时省了哪一步或者版本对不上。所以这篇文章会把前置准备、源替换、仓库同步、SDK 安装完整走一遍目标只有一个让任何一台全新 Ubuntu 24.04能在半小时以内跑起 Zephyr 编译。1.2 镜像加速的整体思路先解决“搬运”问题再解决“编译”问题我的优化思路可以总结成一句话先解决“搬运”问题再解决“编译”问题。很多人的误区是一开始就盯着编译器、CMake、Ninja 这些编译链路上的工具使劲折腾结果装好了还是拉不下代码整体速度没有任何提升。实际上 Zephyr 环境搭建里大部分时间都消耗在“把代码从远程仓库挪到本地”这件事上编译本身反而很快。所以我把整个流程拆成两个阶段。第一个阶段是“提速搬运”把 apt、pip、Git 仓库、SDK 下载这四条链路的源都指向国内可快速访问的镜像地址确保数据能快速落地。第二个阶段才是“正确编译”在代码和工具链都齐了之后按官方文档把 west 环境初始化好用匹配的 Zephyr SDK 编译 sample 工程。这样一来每一次操作的时间都被压得很短整体效率提升非常明显。我自己最直观的感受是优化之前在一台网速一般的机器上装 Zephyr从零到能编译 hello_world搞了将近两个小时其中一半时间都在等下载。优化之后同样的机器从换源到编译出第一个 bin 文件大约只花了 30 分钟。这个差距不是机器性能带来的而是下载路径选对了。2. 镜像加速的四条链路与方案对比2.1 四个卡点apt、pip、Git 仓库、SDK 下载Zephyr 环境搭建在国内通常卡在四个地方apt 系统依赖、pip 的 Python 包、GitHub 上的 west 仓库、以及 Zephyr SDK 这类大体积离线包。这四个卡点各有不同的加速方式我的建议是分开处理不要指望一个“万能加速工具”解决所有问题。第一个是 apt 源。Ubuntu 默认源指向 archive.ubuntu.com国内访问速度只能说能用但装几十个依赖包时会明显感觉到等待时间长。解决方案是换成阿里云、清华或中科大的 Ubuntu 源。第二个是 pip 源。Zephyr 的 west 工具和一堆 Python 依赖包都是从 PyPI 下载默认源在国外速度不稳定。解决方案是配置清华 PyPI 镜像或阿里云 PyPI 镜像。第三个是 Git 仓库。Zephyr 主仓库和各个 module 仓库都在 GitHub 上west update 时要逐个去 clone。这里最典型的问题是单个仓库比较大比如 hal_stm32、hal_nordic 这类 HAL 仓库动辄几百 MB连接不稳定就很容易中断。解决方案是用国内代码托管平台上的仓库镜像或者给 Git 配置合理的浅克隆参数。第四个是 Zephyr SDK。这是最大的一个下载项压缩包体积接近 1 GB解压后更大。官方地址是 GitHub Releases国内下载很慢。解决方案是找国内镜像站的 GitHub Release 镜像路径例如清华镜像站就有同步。这四个卡点全部处理完搭建过程才会顺畅。我遇到过不少人只换了 apt 源后面卡在 west update 上跑来问我为什么还是慢其实就是因为其他三条链路没有同步处理。2.2 仓库镜像选型选对路径才是真加速关于“国内镜像”这个词网上有太多说法。有些是第三方做的 GitHub 加速工具需要你把请求转发到他们的服务器这类工具有隐私和安全风险我不太推荐用在开发环境里。更稳妥的方案是直接用大型代码托管平台上的公开镜像仓库比如 Gitee、GitCode 上都有 Zephyr 项目的同步副本这些是真实仓库的镜像访问路径完全在国内速度快且安全。具体操作上west init 时可以指定 manifest 仓库的地址。官方默认是west init -m https://github.com/zephyrproject-rtos/zephyr.git在国内网络环境下可以把 zephyr 主仓库地址替换成镜像地址比如west init -m https://gitee.com/zephyrproject-rtos/zephyr.git或者用 GitCode 上的镜像地址。但注意主仓库镜像化以后west update 去拉 modules 时每个 module 的仓库地址仍然写在 manifest 文件里默认指向 GitHub。如果所有 module 都走国外地址还是会卡。我的做法是只把 zephyr 主仓库用镜像初始化然后利用 Git 配置和浅克隆参数来加速 module 的拉取。比如在 west 初始化完成后执行west config --global zephyr.base ~/zephyrproject/zephyr west update --fetch-optimize--fetch-optimize会让 west 在更新时尽量复用本地已有的 Git 对象而不是每个仓库都全量重新 clone。此外在全局 Git 配置里加上浅克隆相关参数可以显著减少大仓库的传输体积。浅克隆不是不要历史而是只取最新提交对大多数只关心当前代码的开发者来说完全没有影响。这里有一个界线要注意镜像仓库本质上还是代码副本不是官方服务。如果后续需要往 Zephyr 提交代码或者要拉取最新主干最好还是切回官方源或者直接用 GitHub 的 fork 流程。镜像只负责“读”不负责“写”。2.3 版本匹配为什么优化之后反而更容易踩版本坑镜像加速解决的是“下载速度”问题但版本匹配是另一个容易翻车的点。很多人在换源之后下载速度是快了却因为 Zephyr 主分支过新、SDK 版本过旧编译时报出一堆只有资深玩家才看得懂的错。Zephyr 项目迭代很快main 分支几乎每天都在更新但 Zephyr SDK 的版本迭代相对滞后。官方文档里会注明“当前 main 分支建议使用 Zephyr SDK 0.17”如果你的 zephyr 仓库停在某个 release 分支比如 v3.7那配套的 SDK 可能是 0.16。版本不对编译时就会出现工具链与内核源码 API 不匹配的问题比如某些结构体字段对不上、某个编译器版本不支持新的内建函数等等。所以我的建议是在初始化阶段就锁版本不要盲目追 main。最稳的路径是cd ~/zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr.git --mr v3.7.0 west update--mr指定 manifest 的 revision这样整个 workspace 都会跟着 v3.7.0 这个版本走不会出现“刚拉的代码还没更新完下一个 commit 又变了”的情况。SDK 方面也尽量用和这个版本匹配的官方 SDK 版本。版本一旦锁定后面所有编译行为都可以预期排错也容易很多。3. 实操过程与核心环节实现3.1 系统依赖安装换源是第一步但注意 24.04 的源格式Ubuntu 24.04 和旧版本有一个明显区别软件源配置文件不再是传统的/etc/apt/sources.list而是改成了 deb822 格式的/etc/apt/sources.list.d/ubuntu.sources。很多教程还沿用旧方法去改 sources.list改了之后 apt update 报错或者不生效就是没注意到这个格式变化。我的做法是直接编辑 ubuntu.sources 文件把里面的URIs: http://archive.ubuntu.com/ubuntu/替换成国内镜像地址比如阿里云sudo sed -i s|http://archive.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com/ubuntu/|https://mirrors.aliyun.com/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources替换完执行sudo apt update sudo apt upgrade速度会有非常明显的提升。这里有个小细节deb-src 行也要保留有些依赖包在构建时需要源码索引如果你把 deb-src 注释掉后面装某些软件或者自己编内核模块时会找不到源。然后安装 Zephyr 要求的系统依赖包。官方列了一长串我整理成一条命令方便一次性装完sudo apt install -y git cmake ninja-build gperf ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc gcc-multilib g-multilib libsdl2-dev libmagic1这些包各自都有用途简单解释一下cmake 和 ninja-build 是构建系统核心gperf 用来生成哈希查找表device-tree-compiler 负责编译设备树dfu-util 是烧录工具libsdl2-dev 和 libmagic1 是部分 host 工具运行时的依赖。少了任何一个都可能在中途编译某个模块或者跑某个脚本时报错。3.2 Python 虚拟环境与 west 安装少踩 PATH 和权限的坑Zephyr 官方推荐用 Python 虚拟环境隔离 west 工具链这个建议在 Ubuntu 24.04 上尤其重要因为系统自带的 Python 3.12 环境非常干净但也非常容易被破坏。如果把 west 直接 pip install 到系统环境很容易因为权限不够、依赖冲突或者 distutils 移除问题导致安装失败。我推荐按以下步骤操作python3 -m venv ~/zephyr-venv source ~/zephyr-venv/bin/activate pip install --upgrade pip pip install west之后每次开新终端需要用source ~/zephyr-venv/bin/activate激活虚拟环境再执行 west 命令。如果你嫌麻烦可以把激活命令加到~/.bashrc里echo source ~/zephyr-venv/bin/activate ~/.bashrc source ~/.bashrc这里有个高频问题明明提示 west 安装成功了但输入west --version却提示 command not found。这通常是两个原因之一一是当前 shell 没有激活虚拟环境二是在虚拟环境激活状态下 pip 把 west 装到了虚拟环境目录但 shell 的 PATH 没有包含~/zephyr-venv/bin。可以用which west检查一下路径是否正确如果真的是 PATH 问题手动把export PATH$HOME/zephyr-venv/bin:$PATH写进~/.bashrc就行。Python 虚拟环境的好处是以后你在同一台机器上做其他 Python 项目不会因为 Zephyr 的依赖把系统环境搞得一团糟。哪怕 Zephyr 版本升级要换 west 版本也只需要删掉这个虚拟环境重建一个五分钟就能搞定。3.3 初始化 Zephyr 项目manifest 仓库地址的镜像玩法这一步是整个环境搭建的核心。我在 2.2 节说了可以用镜像仓库做 west init但这里要补充一个重要细节manifest 仓库换镜像之后west 会按照 manifest 文件里的内容去拉取其他 module也就是说加速效果并不取决于你是否换了镜像而取决于你在 manifest 文件里如何描述仓库来源。最直接的办法是在 west init 时直接指定镜像 manifest 仓库地址。比如mkdir ~/zephyrproject cd ~/zephyrproject west init -m https://gitee.com/zephyrproject-rtos/zephyr.git --mr v3.7.0初始化完成后执行west update。如果某个 module 速度很慢可以用浅克隆的方式来减少传输量。浅克隆在 Git 中的配置方式是git config --global http.postBuffer 524288000 git config --global core.compression 9第一个参数是提高 Git 上传下载的缓冲大小避免大仓库数据传输时因为缓冲区不足而失败第二个参数是提高压缩级别能减少网络传输的数据量但会增加 CPU 占用。实测下来对 hal_stm32 这类大仓库很有帮助。west update结束后可以检查一下当前状态west status west topdirwest status会列出每个 module 的版本状态west topdir会显示当前 workspace 根目录确认所有仓库都就位了就行。如果中途有仓库失败可以单独重试比如west update hal_stm32只更新这一个模块不用从头再来。3.4 安装 Zephyr SDK大文件下载的正确姿势Zephyr SDK 可以从官方 GitHub Releases 下载也可以从国内镜像站下的对应副本下载。这里推荐清华镜像站的 GitHub Release 镜像路径形如wget https://mirrors.tuna.tsinghua.edu.cn/github-release/zephyrproject-rtos/zephyr/zephyr-sdk-0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz下载速度比直接访问 GitHub Releases 快很多且文件完整性和官方保持一致。下载完成后解压到合适目录sudo tar -xvf zephyr-sdk-0.16.8_linux-x86_64.tar.xz -C /opt然后进入 SDK 目录运行安装脚本cd /opt/zephyr-sdk-0.16.8 sudo ./setup.sh -c-c参数会自动安装 host tools包括 pyocd、openocd、jlink 等调试工具链。如果你只是做编译不调试这些工具也不是必须的但建议还是装上因为后续跑 qemu、连开发板调试都会用到。安装完成后需要把 SDK 的环境变量配置好。SDK 自带的env.sh可以帮你设置 PATHsource /opt/zephyr-sdk-0.16.8/env.sh这里有个血泪教训如果你忘记 source env.sh或者把它放到了.bashrc里但路径写错那么编译时会直接报arm-zephyr-eabi-gcc: No such file or directory看着像编译器没装成功实际上是环境变量 PATH 里找不到工具链。所以在跑编译之前先检查一下which arm-zephyr-eabi-gcc如果能输出路径说明环境没问题如果提示找不到就去检查 env.sh 有没有被正确 source。3.5 编译验证以 STM32 为例跑通 hello_world环境全部搭好之后一定要在本地编译一次官方示例确认整条链路没有问题。我自己最喜欢拿hello_world来验证它足够简单也能覆盖从源码编译到链接成可执行文件的完整流程。以 STM32F746G-DISCO 这块板子为例命令如下cd ~/zephyrproject/zephyr west build -b stm32f746g_disco samples/hello_world编译过程中west 会自动创建build目录并用 CMake 配置、Ninja 编译。第一次编译会多一点时间因为要生成一些工程配置但整体不会超过两分钟。编译结束后检查生成的镜像文件ls build/zephyr/zephyr.elf build/zephyr/zephyr.bin这两个文件分别是对应的 ELF 可执行文件和纯二进制文件。zephyr.bin 可以直接用 dfu-util、openocd、pyocd 等工具烧到板子上跑。看到这两个文件出现说明你的 Zephyr 开发环境已经可以正式服役了。如果你用的是其他开发板比如 Nordic 的 nRF54L15 这类新板子也可以先跑一遍 hello_world 做验证但注意确认 SDK 版本是否支持该 SoC 的编译配置。新板子通常对 SDK 版本要求更严格宁可先用官方支持的版本也不要盲目追新。4. 常见问题与排查技巧实录4.1 经典报错速查表我把搭建过程中真正出现频次最高的问题整理成一张表方便你随时对照排查现象可能原因解决办法west: command not found虚拟环境未激活或 PATH 未包含 west 路径重新 source ~/zephyr-venv/bin/activate检查 which westwest update中途卡住或超时个别 module 仓库下载慢用浅克隆配置重试west update 模块名编译报arm-zephyr-eabi-gcc: No such file or directorySDK env.sh 没有 source或 SDK 版本不匹配执行 source /opt/zephyr-sdk-0.16.x/env.shCMake 报错找不到 Zephyr 内核未在 zephyr 目录下执行 west build或 west base 未配置cd ~/zephyrproject/zephyr 后重试或 west config zephyr.base 指定路径ModuleNotFoundError: No module named elftoolsPython 依赖缺失在虚拟环境里执行pip install pyelftools编译时提示找不到libsdl2系统依赖没装全重新执行 apt install libsdl2-devGCC 版本太旧导致编译失败系统 GCC 与 Zephyr 要求不匹配用 Zephyr SDK 自带编译器不要用系统 gcc 交叉编译这些问题是新手最常遇到的其实大部分都不是代码问题而是环境路径、依赖缺失或者版本不一致导致的。4.2 实战体验从 2 小时到 30 分钟优化的核心是“预取”最后聊聊我个人的实战体会。第一次在没有优化的情况下搭建 Zephyr 环境我大概花了两个多小时其中很大一部分时间是在等下载。后来我把 apt、pip、Git 仓库、SDK 四条链路全部换成国内镜像又在 west init 时锁定了版本之后在另一台全新 Ubuntu 24.04 上重新搭建了一次从开始执行命令到编译出 hello_world 的 bin 文件只用了大概 30 分钟。这个时间差的本质其实就是一个字“预取”。优化并不是让网络速度变快了而是让所有数据都能从离我更近、带宽更大的路径上“预取”过来。相当于从每次都要跨过半个地球去取快递变成了货物已经在本地分拣中心只要跑一趟就能拿全。再分享一个小技巧如果你经常在多个目录下切换工作不要每次都重新跑 west init 和 west update。可以保留一个基础 workspace然后通过west build -d参数指定构建目录或者直接用west build和west flash的组合完成从编译到烧录的完整流程。这样既能省去重复初始化 workspace 的时间又能保持代码版本的稳定性。搭建 Zephyr 环境这件事说难也难说简单也简单。难在网络和不兼容简单在只要把下载路径选好、版本锁定后面基本就是一条命令走到底。我已经把踩过的坑都写出来了希望你这次能一次顺利。
