做嵌入式这几年我最大的体会之一就是很多项目不是死在代码上而是死在环境搭建上。Zephyr这套开发环境尤其典型。Ubuntu 24.04 发布之后我第一时间把主力开发机升了上去顺手给两个新同事远程配 Zephyr 环境。结果不夸张地说光靠默认网络环境折腾下来一天都未必能把一个 hello_world 编译通过。问题出在哪不是 Zephyr 本身难装而是整套链路太长且每一步都在考验网络质量。这篇文章就围绕“用国内镜像加速 Ubuntu 24.04 下 Zephyr 开发环境搭建”这件事把我实际走的弯路、踩过的坑、最后稳定的方案完整梳理一遍。无论你是刚接触 Zephyr 的入门者还是已经被 west update 折磨过一遍的过来人照着这套思路做基本可以把环境搭建时间控制在半小时以内。1. 为什么 Ubuntu 24.04 上搭 Zephyr 环境总翻车1.1 Zephyr 环境搭建的完整链路有多长很多人以为搭 Zephyr 环境就是装个 west 然后编译其实完整链路比想象中长得多。一条流水线走下来是这样的系统依赖安装cmake、ninja、gperf、dfu-util、device-tree-compiler、python3-dev、libsdl2-dev 等一堆包安装 west 工具它是 Zephyr 的工作流管理工具负责拉代码、构建、烧录初始化 workspacewest init 会把 zephyr 主仓库以及包含所有模块清单的 west.yml 拉到本地west update这一步会依据 west.yml 把 HAL 库、各类 modules、工具链描述文件等几十个仓库全部拉下来安装 Python 依赖每个版本都有一份 requirements.txt里面包括 pyelftools、pykwalify、anytree 之类的包下载 Zephyr SDK里面是预编译的 toolchain用于编译目标架构代码配置环境变量并编译验证。每一步看起来都不难但问题在于这些操作大多要访问境外代码仓库和软件源。国内网络环境下系统 apt 源慢、pip 源慢、Git 仓库慢、SDK 下载经常中断。任何一个环节出问题后面全都没法继续。所以我一直强调一个观点Zephyr 环境搭建的真正瓶颈不是配置命令而是网络路径。1.2 三个最容易卡死的瓶颈第一个瓶颈是系统依赖。Ubuntu 默认官方源在国内的下载速度不稳定apt 更新会长时间卡住。第二个瓶颈是 west update。这是最让人头疼的一步。Zephyr 官方 manifest 里默认 remote 是指向境外代码托管平台的west update 会并行拉取 zephyr、hal_stm32、hal_nordic、mcuboot、mbedtls 等几十个仓库。如果每个仓库都走官方原文路径慢的一批甚至拉一半直接失败。拉失败之后 west 的状态就很尴尬重试又得从头开始。第三个瓶颈是 Zephyr SDK 下载。SDK 压缩包体积通常在几百 MB 级别官方发布地址在境外 Releases 页面浏览器直接下载很容易中断。而 SDK 又是编译必需项下不下来整个环境就废了。明白了这三只“拦路虎”解决方案其实就清晰了把源换掉、把仓库换成国内镜像、把 SDK 从国内云厂商镜像站下载。下面我会按步骤把这套方案完整写出来。2. 动手前的准备版本选型与镜像源规划2.1 先把版本对应关系搞清楚Zephyr 3.6、3.7、4.0 几个版本我都在 Ubuntu 24.04 上实际编译过。Ubuntu 24.04 默认仓库里的 cmake 是 3.28.xPython 是 3.12GCC 是 13.x这套组合对 Zephyr 官方要求来说完全满足不需要像旧版 Ubuntu 那样折腾 cmake 版本。但有一个细节要注意Zephyr SDK 要和 Zephyr 主版本保持兼容。我目前主力使用的组合是 Zephyr 3.7.0 Zephyr SDK 0.16.8这套配合很稳定。如果你跟的是 main 分支建议用对应版本页面里推荐的 SDK 版本不要混搭混搭经常会碰到编译器版本不匹配的报错。另外建议在 west init 时用--mr参数固定分支或标签不要默认拉 main。main 分支更新频繁有时候当天能编译的代码第二天就挂了固定版本能让你的环境在一个可控状态下排查问题时心里有底。2.2 三线镜像方案apt、pip、SDK 分开处理我的做法是把整个环境搭建按三条线拆开分别用不同的国内镜像加速互不干扰。系统依赖走 apt 国内软件源清华、阿里、中科大源任选我默认推荐清华源更新频率高稳定Python 包走 pip 国内镜像同样用清华 PyPI 镜像配置一次终身生效Zephyr 工程仓库走国内代码托管平台镜像在 Gitee 这类国内代码托管平台上有不少人维护了 Zephyr 全仓库镜像west init 和 west update 可以直接指向这些镜像地址Zephyr SDK 走云厂商开源镜像站华为云开源镜像站里长期同步了 zephyr-sdk 目录下载速度快支持断点续传。这四条线不要混在一起。有人问我能不能直接在配置文件里把 west 的 remote 全改成某个第三方 CDN当然可以但第三方 CDN 不保证覆盖所有仓库。最稳的方案还是“该国内容器走国内源该走官方版本信息的地方保留官方 manifest”只把网络路径换掉。提示镜像方案里的“镜像”仅指国内代码托管平台上的仓库同步副本、软件源镜像站这是完全合规的开发环境加速手段。务必从正规渠道选择镜像源。3. 完整环境搭建实操一步步照着做就行3.1 第一步把 apt 源换成国内软件源Ubuntu 24.04 的软件源配置文件位置和之前不太一样不再是 /etc/apt/sources.list而是 /etc/apt/sources.list.d/ubuntu.sources。换源之前先看看当前内容cat /etc/apt/sources.list.d/ubuntu.sources新版的格式是 deb822 格式里面 URIs 那一行通常是http://archive.ubuntu.com/ubuntu/或http://security.ubuntu.com/ubuntu/。我习惯备份后直接 sed 替换把这两处域名换成清华源。sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak sudo sed -i s|http://archive.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g /etc/apt/sources.list.d/ubuntu.sources sudo apt update如果你安装系统时选择的是中国区镜像URIs 可能是http://cn.archive.ubuntu.com/ubuntu/那把命令里的 archive 改成 cn.archive 即可。换源后apt update速度应该会明显提升。如果提示缺少公钥检查一下是否用了 https 而系统缺少对应传输插件一般新装系统不会遇到这个问题。确认 apt 源没问题后安装 Zephyr 官方文档里列出的系统依赖sudo apt install --yes \ 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如果你后续要开发 STM32 相关板子顺手把 stlink 和 openocd 也装上省得后面再补sudo apt install stlink-tools openocd这一步用国内 apt 源的话一两分钟内就能拉完几乎不会卡。3.2 第二步给 pip 换源并用 venv 安装 westUbuntu 24.04 的 Python 3.12 有个新特性很容易坑到新手直接用 pip 往系统环境装包会报 externally-managed-environment 错误。这是 PEP 668 的规定系统 Python 环境不让你随便往里面塞包。所以我强烈建议在 Zephyr workspace 里建一个独立虚拟环境所有 Python 工具都装在 venv 里干净、可控、不会污染系统环境。python3 -m venv ~/zephyrproject/.venv source ~/zephyrproject/.venv/bin/activate激活后先给 pip 换源。我通常写进全局 pip 配置这样后面不管装什么包都走清华源。mkdir -p ~/.config/pip cat ~/.config/pip/pip.conf EOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn EOF然后安装 westpip install -U pip pip install west这里有个使用习惯要养成以后每次打开新终端都要记得先激活虚拟环境再执行 west 命令。不然终端会报command not found: west这也是新手最容易范的错误之一。我一般会在 ~/.bashrc 末尾加一行注释提醒自己但不建议无脑自动 source因为有时候你打开的终端未必准备操作 Zephyr 项目。3.3 第三步初始化 Zephyr workspace 并切换镜像仓库先创建目录并初始化mkdir -p ~/zephyrproject cd ~/zephyrproject west init -m https://gitee.com/your-mirror/zephyr.git --mr v3.7.0这里的your-mirror需要替换成你实际使用的 Gitee 镜像仓库用户名。怎么找直接在 Gitee 上搜索 zephyr优先选择描述里写明“Zephyr 镜像”、“每日同步”、“全仓库镜像”的项目打开后看一下它的仓库更新时间太旧的不要用。然后看仓库根目录是否存在 west.yml有的话说明这个镜像至少覆盖了 Zephyr 主仓库和 manifest 清单。镜像用户名的选择是整个方案里最需要花点心思的地方。我验证镜像是否可用一般两步走git ls-remote https://gitee.com/your-mirror/zephyr.git | head -20能正常输出版本号列表说明仓库可达且允许匿名访问。然后查看镜像里是否同步了配套的 hal_stm32 或 hal_nordic 这类仓库方法是在浏览器地址栏直接打开https://gitee.com/your-mirror/hal_stm32如果 404 就换一个更完整的镜像。初始化完成后检查一下拉下来的 west.yml 的 remote 配置是否真的指向了镜像地址head -30 ~/zephyrproject/zephyr/west.yml如果里面 remote 的 url-fmt 还写着官方境外平台地址说明这个镜像只提供了 zephyr 主仓库没有整体替换模块仓库地址。这个时候要么换一个更完整的镜像要么用下面的命令手动替换cd ~/zephyrproject sed -i s|https://github.com/zephyrproject-rtos/|https://gitee.com/your-mirror/|g zephyr/west.yml替换后务必打开 west.yml 再确认一遍 URL 拼接是否正确不要出现gitee.com/your-mirror//hal_stm32.git这种双斜杠问题。注意直接把 manifest 里所有模块都硬切到同一个镜像用户前提是那个镜像用户确实同步了全部模块仓库。如果只同步了其中几个west update 会在缺失仓库上失败这时候要回退 west.yml 的改动换一个全量镜像。这也是我反复强调“先验证再 update”的原因。3.4 第四步west update 拉取全部模块确认 manifest 没问题后执行cd ~/zephyrproject west update用镜像仓库后这一步通常 10 到 30 分钟能完成视镜像速度和网络状况而定。默认情况下 west 会并行拉取速度已经比逐个仓库串行快不少。如果某个仓库拉取时网络中断导致失败west 会把状态标记为 inconsistent这时候不需要把整个目录删掉重来可以针对失败仓库单独重拉west update 仓库名如果失败仓库比较多或者反复失败可以加-f参数强制重新拉取west update -f这里再分享一组 git 配置对减小大仓库拉取失败率很有帮助git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 60postBuffer 调大能减少大对象推送时的缓冲问题lowSpeedLimit 和 lowSpeedTime 是让 git 在网速长时间极低时不至于立刻报错。这套配置不只是 Zephyr 用其他大型仓库同样受益。3.5 第五步安装 Zephyr 构建所需的 Python 依赖west update 完成后zephyr 仓库里会带一份 requirements.txt路径在~/zephyrproject/zephyr/scripts/requirements.txt激活 venv 后安装source ~/zephyrproject/.venv/bin/activate pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt这一步因为已经配置好清华 pip 源一般是秒级完成。装完后可以顺手验证一下关键工具版本west --version cmake --version ninja --versionwest 版本太旧的话后面西风某些特性可能不兼容建议安装 requirements 时一并升级到最新。3.6 第六步用云厂商镜像站下载 Zephyr SDKSDK 是编译的目标平台工具链里面包含了针对 ARM、RISC-V、x86 等架构的预编译工具。我建议直接去云厂商开源镜像站下载而不是去官方 Releases 页面。以华为云开源镜像站为例zephyr-sdk 的目录结构是版本号加文件名格式很规范。Zephyr 3.7.0 对应 SDK 0.16.8我使用的是 x86_64 平台下载命令如下cd ~ wget https://mirrors.huaweicloud.com/zephyr-sdk/0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz如果你的机器是其他架构把文件名里的 x86_64 替换为对应的架构标识即可。下载完解压并运行 setup 脚本tar xf zephyr-sdk-0.16.8_linux-x86_64.tar.xz -C ~/ cd ~/zephyr-sdk-0.16.8 ./setup.shsetup 脚本运行过程中会询问是否设置 udev 规则。这里一定要输入 y否则后面 west flash 连接开发板时会因为缺少权限而失败。如果之前忘了配置也可以后续手动执行但代价是排查权限问题会花掉不少时间。然后设置环境变量。我推荐写进 ~/.bashrc避免每次开终端都要 exportecho export ZEPHYR_SDK_INSTALL_DIR~/zephyr-sdk-0.16.8 ~/.bashrc source ~/.bashrcSDK 版本号要根据你实际下载的目录名来写不要照抄。如果系统里没有其他交叉编译链通常还需要显式指定使用 Zephyr 自带的工具链echo export ZEPHYR_TOOLCHAIN_VARIANTzephyr ~/.bashrc source ~/.bashrc3.7 第七步编译 blinky 验证整套环境环境搭完不能算完一定要跑一个实际例子验证。我用得最多的验证项目是 hello_world 或 blinky。以一块常见的 STM32F401RE 开发板为例source ~/zephyrproject/.venv/bin/activate cd ~/zephyrproject west build -p always -b nucleo_f401re samples/hello_world-p always 表示每次构建前先 pristine强制清理之前的构建产物。对于验证性构建这个参数能避免增量编译带来的各种奇怪问题。第一次编译需要生成各类配置头文件、链接脚本大概一两分钟能完成。如果 board 名写错west 会给出支持该架构的 board 列表提示可以根据列表确认具体名字。编译成功后在 build 目录下会生成 zephyr.elf 和 zephyr.bin。如果手头有板子可以直接烧录west flash对于 STM32 系列west flash 默认会调用 openocd 或 stlink 工具。如果你用的是其他品牌调试器可能要提前装好对应工具并在 board 的配置里指定烧录器这是另一个话题这里不展开。4. 常见问题与排查技巧实录4.1 典型崩溃现场一PEP 668 拦截 pip 安装报错一般长这样error: externally-managed-environment这是 Ubuntu 24.04 的 Python 3.12 默认策略阻止 pip 全局安装。解决办法就是前面说的 venv 方案不要试图加--break-system-packages强行绕过那样很容易把系统 Python 环境弄坏。把 venv 建在 zephyrproject 目录下激活后所有 pip 命令都正常。4.2 典型崩溃现场二west update 卡死或反复失败west update 时如果一直卡在 Fetching 阶段甚至单个仓库反复失败先检查 west.yml 里的 URL 是否真的指向国内镜像地址。不要只看 init 时候用了国内地址就说“我换成镜像了”很多镜像只覆盖主仓库west.yml 里的模块地址仍然是官方。这是最隐蔽的坑。另外west 的更新状态存储在 ~/zephyrproject/.west 目录下。如果 manifest 文件改坏了或者状态文件乱了最稳妥的还原方式是把 .west 目录删掉重新 init而不是手动去改一堆 git 状态rm -rf ~/zephyrproject/.west cd ~/zephyrproject west init -m https://gitee.com/your-mirror/zephyr.git --mr v3.7.0 west update这个操作只重建 west 元数据不会影响已经下载成功的仓库比把整个目录删掉重来要快得多。4.3 典型崩溃现场三编译时提示找不到编译器编译报错里如果出现 arm-zephyr-eabi-gcc 找不到这类信息一般有三个原因ZEPHYR_SDK_INSTALL_DIR 没设置或者路径不对SDK 解压目录不存在检查 ~/zephyr-sdk-0.16.8 这个路径是否存在ZEPHYR_TOOLCHAIN_VARIANT 没有设置为 zephyr或者设置了别的工具链。解决办法就是逐项确认echo $ZEPHYR_SDK_INSTALL_DIR echo $ZEPHYR_TOOLCHAIN_VARIANT ls ~/zephyr-sdk-0.16.8如果环境变量没生效重新 source 一下 ~/.bashrc。环境变量这种问题看起来是玄学其实九成都是没重开终端或者没 source。4.4 典型崩溃现场四烧录时权限不足或串口被占用连上开发板执行 west flash有时会报 open 设备失败或者 permission denied。大多数情况是当前用户不在 dialout 组sudo usermod -a -G dialout $USER改完用户组后要重新登录或者重启终端才会生效。还有一种很气人的情况是 Ubuntu 自带的 ModemManager 服务把 /dev/ttyACM0 识别成了调制解调器导致烧录工具打不开串口。临时停掉这个服务就好sudo systemctl stop ModemManager如果之前 setup.sh 里没设置 udev 规则也会遇到类似权限问题回看 3.6 节重新跑一遍 setup.sh输入 y 确认生成规则即可。5. 提速效果对比与避坑清单5.1 实测耗时对比我在同一台机器、同一个网络环境下分别用默认方案和镜像方案测试过差异可以说是天壤之别。下表是估算参考值不同网络环境会有波动但量级很有代表性阶段默认方案镜像方案apt 系统依赖10-30 分钟经常超时1-3 分钟pip 安装 west 及依赖不确定慢则十几分钟1 分钟以内west init不稳定视网络而定1 分钟左右west update2-6 小时失败率高10-30 分钟SDK 下载经常中断重试2-10 分钟首次编译验证不受网络影响不受网络影响整体看下来默认方案运气好也要折腾半天镜像方案半天变成一个小时以内整个体验完全不同。5.2 十条避坑清单换 apt 源之前先备份路径是 /etc/apt/sources.list.d/ubuntu.sources不是老版本的 sources.list一定用 venv不要往系统 Python 里直接装 westPEP 668 会拦截你west init 用国内代码托管平台上的全量镜像仓库不要只镜像了主仓库的那种初始化后检查 west.yml 里的远程地址确认模块仓库也指向了镜像west update 失败不要慌先单独重拉失败仓库不行再删 .west 目录重建Zephyr SDK 版本要和 Zephyr 版本对应别混搭setup.sh 执行时对 udev 规则要选 y否则烧录权限异常当前用户记得加 dialout 组加完要重登环境变量写进 ~/.bashrc 并 source不要每次手动 export每次构建推荐加 -p always 参数避免增量状态混乱。最后再分享一个小技巧如果公司内网或实验室网段对某些镜像站访问慢可以让团队内几个人共享同一份 SDK 压缩包或者在内网搭一个 apt 缓存服务。Zephyr 工程仓库也可以用 git bundle 方式在局域网内分发虽然前期准备成本高但多人协作时能省下大量重复下载时间。我个人在实际搭建环境后的体会是Zephyr 本身的设计很有条理west 工具链的思想也很超前但环境搭建的门槛确实劝退了不少人。与其说它难不如说它对网络环境要求太高。把 apt、pip、Git 仓库、SDK 这四大流量入口全部切到国内镜像这个项目就成功了一半。剩下的一半其实就是按部就班地等编译完成。希望这篇记录能帮你少走这些弯路。