我第一次完整搭建 Zephyr 开发环境是在 Ubuntu 24.04 上原本以为照着官方文档敲一遍命令就行结果光是等依赖、拉源码、下载工具链就搭进去一个下午。真正卡住我的不是 Zephyr 本身的复杂性而是这套环境里有太多东西要从海外仓库拉取Python 包、Git 仓库、动辄几百 MB 的 SDK 压缩包。只要其中一个环节慢下来整体体验就非常难受。后来我系统性地把所有下载环节切到国内镜像和加速通道节奏一下就顺了。这篇文章打算把这套验证过的方案完整展开包括系统 apt 源、pip 源怎么换west 工具链和 Zephyr 源码仓库的 Git 拉取怎么做Zephyr SDK 怎么绕过 GitHub 慢速下载以及 Ubuntu 24.04 下最容易踩的 Python 环境坑。适合刚入门 Zephyr、又被网络问题劝退过的嵌入式开发者也适合想把开发环境一次搭干净、后续编译尽量少浪费时间的人。1. 在Ubuntu 24.04上搭Zephyr环境核心瓶颈到底在哪1.1 你的时间不是耗在编译上而是耗在下载上Zephyr 和传统单片机 SDK 最大的不同是它不是一个“装好就能用”的整体包而更像一个由 west 这个元工具管理的多仓库项目。第一次west init会克隆 Zephyr 主仓库紧接着west update会按照 west.yml 这份清单去拉取几十个依赖仓库其中包括各家芯片厂商的 HAL 库、CMSIS、mcuboot、OpenThread、TF-M 等第三方组件。这些仓库绝大多数都托管在 GitHub 上任何一个仓库拉取超时整个west update就会中断。再加上后续要用的 Zephyr SDK它是独立的交叉编译工具链压缩包体积通常在 500MB 到 1GB 左右同样挂在 GitHub Releases 下面。简单算一笔账系统 apt 依赖走国外源、pip 包走国外源、Git 仓库走国外源、SDK 大文件走国外源四层下载全部叠在一起网络稍微一抖动就让人崩溃。我在这一步得到的最大教训是不要试图逐条去等先把每一层下载入口都切到国内后面所有操作才有意义。1.2 Ubuntu 24.04 的新脾气Python 环境管理和依赖差异Ubuntu 24.04 的代号是 noble相比 22.04它把默认 Python 升到了 3.12CMake 版本也足够高这些对 Zephyr 都是利好因为 Zephyr 新版本对 CMake 最低版本的要求越来越高系统自带版本基本能满足。真正让人意外的是 Python 包管理的变化。24.04 默认启用了 PEP 668 的 externally-managed-environment 保护机制。换句话说你直接在系统 Python 里执行pip install west大概率会撞上一堵墙报错信息类似“error: externally-managed-environment”。这是系统在说这个 Python 环境由 apt 管理别用 pip 乱装东西。第一次遇到这个报错时我第一反应是去查 west 安装文档后来才意识到这是 Ubuntu 24.04 的普遍策略不是 west 特有。解决办法有几种但最干净的还是用 venv 虚拟环境既不会污染系统 Python后续升级依赖也方便。另外Ubuntu 24.04 的 apt 源配置方式也变了。传统印象里改/etc/apt/sources.list的做法在新装系统上不生效因为 24.04 默认使用 Neu 的 deb822 格式源配置放在/etc/apt/sources.list.d/ubuntu.sources文件里。如果还按老教程去改改了半天发现没有任何效果多半就是因为改错了文件。2. 系统级加速先行apt源和pip源一次换清楚2.1 选镜像站我最终固定下来的两套方案国内可用的 Linux 镜像站选择很多常用的有清华 TUNA、阿里云、中科大 USTC、华为云等。我的经验是apt 源用清华或阿里云pip 源用清华或中科大这两组组合在 Ubuntu 24.04 下都比较稳。清华 TUNA 的优势是同步快、学术机构维护缺点是高峰期带宽偶尔会紧张阿里云的优势是国内节点多、带宽大但某些小众包同步速度略慢。如果你在北方或对某个源不放心可以分别测一下速度再决定。测试方法很简单apt update apt-get download --print-uris cmake | head -1这一句能打印出实际下载地址看到域名是哪个镜像站再配合curl -o /dev/null -w %{speed_download}看看下载速率基本上几秒钟就能判断哪个源更快。2.2 apt源在24.04里改法和以前不一样先确认系统源文件位置ls -l /etc/apt/sources.list.d/ubuntu.sources如果存在这个文件说明是 deb822 格式。操作前先备份sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak然后执行替换把 archive.ubuntu.com 和 security.ubuntu.com 统一替换为清华源sudo sed -i -E s|https?://(archive\.ubuntu\.com|security\.ubuntu\.com)/ubuntu/|https://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g /etc/apt/sources.list.d/ubuntu.sources替换完成后用编辑器打开文件确认一下。完整内容看起来应该是这样的Types: deb URIs: https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ Suites: noble noble-updates noble-backports noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg这里有两个细节值得注意。第一URIs 必须指向镜像站的/ubuntu/路径不要把后面的斜杠省掉。第二默认配置里 Suites 往往没有noble-security建议手动补上否则安全更新源还是会走国外地址等于没换干净。补齐之后执行sudo apt update看到类似Hit:1 https://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease的输出就说明已经生效了。接下来顺手把基础依赖装上sudo apt install --no-install-recommends 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 libncurses-dev libpixman-1-dev libssl-dev libjansson-dev libyaml-dev如果你后续要跑 QEMU 或者想用 menuconfig 图形化配置内核这些包基本都能覆盖到不用再回头补装。2.3 pip源配置到用户级west安装直接用pip 源配置到当前用户级别就够了不需要改全局系统文件。执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn想验证是否生效可以执行pip config list输出里能看到 index-url 已经是清华的地址。如果你习惯用环境变量也可以把下面两行写进~/.bashrc效果等效export PIP_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simple export PIP_TRUSTED_HOSTpypi.tuna.tsinghua.edu.cnpip 源换好之后有一个连带好处后面 west 在构建过程中如果需要临时拉取一些 Python 依赖比如 pyelftools、pykwalify走的也是国内源省去很多麻烦。这一步虽然看起来不起眼但对全程体验影响很大值得在一开始就配好。3. west工具与源码仓库拉取Git层面的加速姿势3.1 先解决Python虚拟环境再接west前面提到 Ubuntu 24.04 对系统 Python 有一层保护直接pip install west会被拦下来。我的做法是专门给 Zephyr 建一个虚拟环境目录放在工作区里面方便管理和清理。假设工作区路径是~/zephyrproject操作如下mkdir -p ~/zephyrproject cd ~/zephyrproject python3 -m venv .venv source .venv/bin/activate pip install west之后只要进入新终端准备做 Zephyr 开发先执行source ~/zephyrproject/.venv/bin/activate就能保证west命令可用。这种做法的好处在于west 本身迭代很快以后要升级直接pip install -U west不会影响系统里其他 Python 项目。如果你不想每次手动激活可以把激活语句追加到~/.bashrc但要注意这会让终端一打开就进入虚拟环境有些人不喜欢这种体验看个人习惯。3.2 用Git insteadOf机制给github.com的克隆加速虚拟环境搞定后先初始化 Zephyr 主仓库cd ~/zephyrproject west init -m https://github.com/zephyrproject-rtos/zephyr.git --mr main这一步本身就会从 GitHub 克隆一个大仓库网络慢的话仍然可能卡住。我推荐提前用 Git 自带的 URL 替换机制把访问https://github.com/的请求自动转到一个公共的 Git 加速服务。在终端里执行git config --global url.https://gitclone.com/github.com/.insteadOf https://github.com/这条命令的意思是Git 在遇到以https://github.com/开头的地址时自动在前面拼接https://gitclone.com/github.com/。它是 Git 官方支持的配置逻辑不是歪门邪道对west init和west update都有效因为这两个命令底层调用的都是 git clone。配置完之后重新执行west init如果之前因为网络中断失败过可以先把已经拉了一半的目录清掉再重来避免 git 仓库状态混乱。正确命令是rm -rf zephyr west init -m https://github.com/zephyrproject-rtos/zephyr.git --mr main如果一切顺利west init会生成一个zephyr子目录。这时可以检查一下配置是否生效git config --global --list | grep insteadOf如果之后不想再用这个加速服务了撤销也很简单git config --global --unset url.https://gitclone.com/github.com/.insteadOf需要提醒的是这类公开加速服务的稳定性确实会变化有时候某个时段很流畅换一个时段又不行。万一遇到 clone 卡住先卸载 insteadOf 配置用官方源再试一次判断问题出在加速服务本身还是网络整体质量再决定要不要换别的加速入口。3.3 zephyr的多个module仓库拉取要点west init只是拉取了主仓库真正的大头在west update。执行west update这个命令会按照 west.yml 里定义的 manifest 去拉取所有依赖模块。由于前面已经配置了 insteadOf这些模块仓库的克隆请求同样会走加速服务整体速度会有明显改观。不过west update也并不是一次就能保证成功。我的经验是如果中间报错中断直接重新执行west update往往能续上因为已经成功拉取的仓库会被保留不会从头再来。有几个小技巧可以降低失败概率如果主仓库之前克隆不完整先执行west update -o --depth1注意这个参数不是官方标准用法不一定每一版都支持不要把它当成万能钥匙。更新前把终端代理相关变量清空避免 git 走了错误通道。如果某个模块仓库一直失败可以单独执行west update 模块名来定位问题虽然正常语法是west update project但这能帮你排除到底是哪一个仓库卡住。完成之后可以用west list查看所有模块的状态确认没有缺仓库。这一步跑通Zephyr 的源码环境就算立起来了一半。4. Zephyr SDK下载与安装体积最大的单点风险4.1 SDK版本选择和下载加速思路Zephyr SDK 是编译阶段最关键的交叉编译工具链集合它和系统 gcc 是两回事。SDK 里包含了针对多家架构的 toolchain、QEMU、host tools 等。版本选择上建议到 sdk-ng 项目的 GitHub Releases 页面看一眼最新稳定版通常写作类似v0.17.0的 tag。我当时的操作是下载完整 Linux x86_64 包cd ~/zephyrproject wget -c https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64.tar.xz由于这条链接最终还是指向 GitHub Releases在国内网络下依然可能很慢。常见的做法是把这段原始下载链接复制下来放到公共的 GitHub 资源加速服务前面给链接加上对应前缀再用 wget 下载。这里不绑定某一家服务因为这类网站变化太快我自己也会不定期换。判断标准很简单能在浏览器里用加速链接直接触发下载而且文件名和原始链接一致就说明可用。如果你不想折腾加速站还有一个思路是找已经装好 Zephyr 的同事或者朋友让他们把 SDK 压缩包直接传给你。SDK 本质上是可复现的静态工具链同一版本拷贝过去就能用只要架构一致这样做完全没问题。4.2 安装与验证setup.sh、环境变量、host tools下载完成后解压到$HOME目录不建议放在/root或带空格的路径下后面会解释原因tar xf zephyr-sdk-0.17.0_linux-x86_64.tar.xz -C ~/ cd ~/zephyr-sdk-0.17.0 ./setup.sh -t all -h-t all表示安装所有目标架构工具链-h表示同时安装 host tools。如果你明确知道自己只做 ARM 开发可以改成./setup.sh -t arm-zephyr-eabi -h少装一些用不上的工具链节省磁盘和安装时间。接着配置环境变量把下面内容追加到~/.bashrcexport ZEPHYR_TOOLCHAIN_VARIANTzephyr export ZEPHYR_SDK_INSTALL_DIR$HOME/zephyr-sdk-0.17.0注意第二行路径里的版本号要跟你实际解压出来的目录名保持一致。保存后执行source ~/.bashrc验证是否配置成功echo $ZEPHYR_SDK_INSTALL_DIR ls $ZEPHYR_SDK_INSTALL_DIR如果能看到目录内容SDK 部分基本完成了。另外一个容易忽略的点是Zephyr SDK 自带的 QEMU 运行需要 libpixman 和 SDL2 相关库前面 apt 安装依赖时已经覆盖所以这里不用再单独处理。5. 编译一个真实示例并让后续构建更快5.1 hello_world编译验证当源码和 SDK 都准备好后可以先编一个不依赖真实板卡的例子验证整个环境链条是否畅通。我推荐用qemu_cortex_m3因为它在 QEMU 里就能跑不需要接任何硬件。cd ~/zephyrproject source .venv/bin/activate west build -p auto -b qemu_cortex_m3 samples/hello_world-p auto的意思是构建前自动执行一遍 pristine 操作清理上一次构建产物避免缓存干扰。第一次构建需要一些时间输出最后看到hello_world的.elf文件和Finished之类的字样基本就成了。想直接跑起来看输出执行west build -t runQEMU 窗口里会出现Hello World!的日志。这一步跑通说明 apt、pip、Git 拉取、SDK、west 全链路都没有问题。如果你有自己的开发板比如 STM32 系列把-b qemu_cortex_m3换成对应的板卡名比如-b nucleo_f446re再执行west flash就能烧录。第一次烧录前先去 Zephyr 文档查一下这块板子的调试器类型有些板子需要额外安装 openocd 或 pyocd 才能自动识别。5.2 ccache和并行构建的提速实测全量编译一次 Zephyr 工程确实不快尤其是一些带复杂设备树和驱动适配的官方例程。有两个常规加速手段非常有效。第一个是 ccache前面的 apt 依赖里已经装了。ccache 会对编译单元做缓存同一份源码、同一个编译器、同样的配置参数再次构建时直接命中缓存省掉真正的编译过程。用之前先设置环境变量export ZEPHYR_CCACHE1west build 检测到 ccache 存在后会自动使用。我自己的体感是重复编译同一个 board 工程二次构建时间能缩短到第一次的零头这对调试时反复改代码特别有用。第二个是并行任务在west build命令末尾追加构建参数west build -p auto -b qemu_cortex_m3 samples/hello_world -- -j8-j8表示同时跑 8 个编译任务实际数值根据 CPU 核心数调整一般设为物理核心数或略高即可。需要留意的是不是所有工程都能无脑开高并行某些模块因为静态分析工具限制太高的并行度会偶发资源竞争如果遇到莫名失败可以调低-j再试。6. 国内网络环境下我踩过的6个坑与排查方法6.1 pip install west 被系统拦截现象安装 west 时报错error: externally-managed-environment提示“This environment is externally managed”。原因Ubuntu 24.04 启用了 PEP 668系统 Python 不允许 pip 直接安装全局包。解决使用 venv 虚拟环境。按前面第 3.1 节的方法执行python3 -m venv .venv然后source .venv/bin/activate即可。如果已经装错搞乱了环境最好删掉 venv 目录重建别在现有环境里继续折腾。6.2 west 命令找不到现象重新打开终端后执行west --version提示 command not found。原因最可能是没有激活 venv。如果是在非 venv 状态下使用pip install --user west装的命令可能落在~/.local/bin而该目录不在 PATH 中。解决检查which west如果输出为空先执行source ~/zephyrproject/.venv/bin/activate再测试。长期使用建议把source语句写进~/.bashrc。6.3 west init 或 west update 中途失败现象克隆过程中断报网络错误或fatal: early EOF。原因GitHub 连接不稳定大仓库下载被打断。解决先确认 insteadOf 加速配置是否生效再看加速服务是否可用。如果加速服务本身不稳可以换另一个公开加速地址或者暂时卸载 insteadOf 配置等到网络状态好的时候再拉。重复执行west update可以续传不要一失败就从头删掉重来。6.4 编译时提示找不到 DTC 或版本过低现象构建到 device tree 阶段报错Unable to find the DTC或类似信息。原因系统缺少 device-tree-compiler或者装了但版本过旧。解决在 Ubuntu 24.04 上直接执行sudo apt install device-tree-compiler。如果还是找不到用dtc --version确认版本Zephyr 对 DTC 有一定的最低版本要求24.04 源里的版本足够新一般不需要从源码编译。6.5 setup.sh 执行时报符号链接错误现象SDK 安装中途提示无法创建符号链接。原因SDK 被解压到不允许创建软链接的位置比如某些 Windows 挂载目录、带空格的中文路径或者权限不足的目录。解决把 SDK 解压到$HOME下确保当前用户有写权限。路径中不要出现中文和空格这是嵌入式工具链最容易忽略的隐藏雷点。6.6 menuconfig 打开异常或显示乱码现象执行west build -t menuconfig时终端界面错乱或者提示缺少 curses 库。原因menuconfig 依赖 ncurses 库部分精简版系统没有安装完整。解决sudo apt install libncurses-dev装好依赖。如果显示界面尺寸异常可以调整终端窗口大小后再启动menuconfig 对窗口尺寸有一定要求。表常见问题速查现象根因处理pip install west 报 externally-managedUbuntu 24.04 PEP 668 保护使用 venv 虚拟环境west 命令找不到venv 未激活或 PATH 不含 local/binsource .venv/bin/activatewest update 中途失败GitHub 仓库拉取超时检查加速服务重试 west update找不到 DTC缺少 device-tree-compilerapt 安装该包SDK 符号链接错误解压路径含中文/空格或权限不足解压到 $HOME 下menuconfig 界面错乱ncurses 库缺失安装 libncurses-dev搭过几轮 Zephyr 环境后我最大的体会是它本身并不复杂真正会拖住人的是每一条下载链路。先想清楚四件事——apt 走哪个镜像、pip 走哪个镜像、git 克隆走什么加速、SDK 从哪里拿——剩下的一切都是水到渠成。这套镜像加速的思路不仅适用于 Ubuntu 24.04以后换了新发行版、新 LTS 版本核心逻辑也完全一样无非是包名和源地址微调。关键是把这层“镜像思维”刻在习惯里而不是每次遇到慢速下载就临时抱佛脚。希望这篇能帮你今天晚上就顺利跑起Hello World。