Yocto 源码下载失败？掌握 MIRRORS、PREMIRRORS 与 EMIRRORS 三板斧，构建更稳定

原创于 2025-05-12 22:19:30 发布 · 1.3k 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#elasticsearch #大数据 #搜索引擎

Yocto 专栏收录该内容

137 篇文章

订阅专栏

📘 本文作者为《Yocto项目实战教程》作者，欢迎关注技术平台“嵌入式Jerry”（公众号、B站），了解 Yocto 开发干货与嵌入式系统定制技巧。

在使用 Yocto 项目构建嵌入式 Linux 镜像时，最令人头疼的问题之一，莫过于 源码下载失败。由于 Yocto 构建依赖的源文件来自全球各地的 Git 仓库、HTTP 镜像站、甚至稀有网站，一旦下载失败，整个构建流程便会中断。

幸运的是，BitBake 提供了一个强大的机制：MIRRORS、PREMIRRORS 与 EMIRRORS，它们共同组成了 Yocto 的多源下载策略系统，可以大大提高构建的稳定性与成功率。

本文将系统讲解这三个配置项的作用、区别与最佳实践，结合多个实际案例，让你从容应对 Yocto 中的网络不稳定与源站失效问题。

在这里插入图片描述

一、为什么需要镜像机制？

Yocto 中构建过程依赖于 SRC_URI 指定的源地址，如：

SRC_URI = "git://sourceware.org/git/glibc.git;branch=release/2.38/master"

这个源可能会遇到：

官方仓库长时间不可用；
服务器域名失效或 IP 被墙；
Git clone 或 HTTP 下载慢到超时；
CI/CD 构建环境无法联网。

⛔ 一旦下载失败，构建中断！

为此，Yocto 提供了多层级的 fallback 策略：先尝试本地缓存、然后依次尝试 PREMIRRORS、MIRRORS、EMIRRORS，最后才彻底失败。

二、镜像机制概览

1. `DL_DIR`：下载缓存目录

这是源码下载完成后存放的位置。默认在 build/downloads/ 下。例如：

DL_DIR = "${TOPDIR}/downloads"

下载成功一次后，未来所有构建都优先从这里读取，无需重新下载。

2. `PREMIRRORS`：优先替换源

这是最高优先级的替换规则，在尝试原始 URL 前，先用 PREMIRRORS 替换试一次。

示例：

PREMIRRORS += "git://.*/.* https://mirrors.mycompany.com/git2/"

含义：当你执行 git://sourceware.org/git/glibc.git 时，BitBake 会优先尝试：

https://mirrors.mycompany.com/git2/sourceware.org/git/glibc.git

✅ 适用于企业内网镜像、CI/CD 环境或自建 Git 镜像站。

3. `MIRRORS`：原始 URL 失败后尝试

当原始 URL 拉取失败时，BitBake 会尝试 MIRRORS 中定义的替代源。

示例：

MIRRORS += "https://.*/.* https://downloads.yoctoproject.org/mirror/sources/"

含义：如果 https://ftp.gnu.org/gnu/make/make-4.3.tar.gz 下载失败，BitBake 会尝试：

https://downloads.yoctoproject.org/mirror/sources/make-4.3.tar.gz

4. `EMIRRORS`：扩展镜像（Yocto 特有）

这是 Yocto 扩展的 fallback 机制，用于补全 BitBake 原生无法解析的 Git 地址。

示例：

EMIRRORS += "git://sourceware.org/git/glibc.git https://downloads.yoctoproject.org/mirror/sources/"

含义：如果你写了：

SRC_URI = "git://sourceware.org/git/glibc.git;branch=release/2.38/master"

Yocto 会尝试从：

https://downloads.yoctoproject.org/mirror/sources/glibc.git_*.tar.gz

中下载一个压缩包来代替 Git clone。

✅ 非常适用于那些 clone 特别慢、仓库不稳定的情况，比如 binutils-gdb、glibc 等大型源码。

三、三者优先级与流程关系

构建时源码下载的完整流程如下：

     ↓ 是否已在 DL_DIR？
     ↓ 是 → 直接使用
     ↓ 否
     ↓ 应用 PREMIRRORS（优先镜像）
     ↓ 原始 URL 下载
     ↓ 原始失败 → 应用 MIRRORS（备用镜像）
     ↓ 仍失败 → 尝试 EMIRRORS（扩展镜像）
     ↓ 全部失败 → 报错

✅ PREMIRRORS 是最先替代的，MIRRORS 是原始失败后的后备方案，EMIRRORS 是额外用于 Git 的“特殊救援机制”。

四、实战案例：glbic 拉取失败怎么破？

你可能遇到如下错误：

ERROR: glibc - Fetcher failure for URL: 'git://sourceware.org/git/glibc.git;branch=release/2.38/master'

使用 EMIRRORS 可缓解：

EMIRRORS += "git://sourceware.org/git/glibc.git https://downloads.yoctoproject.org/mirror/sources/"

加上这条配置后，Yocto 会去尝试：

https://downloads.yoctoproject.org/mirror/sources/glibc.git_*.tar.gz

这通常比直接 git clone 快几十倍！

五、如何配置更稳定的多源机制？

推荐在 conf/site.conf 或 local.conf 中统一添加以下配置：

DL_DIR ?= "${TOPDIR}/downloads"

PREMIRRORS += "\
git://.*/.* https://mirror.mycorp.com/git2/ \n \
https://.*/.* https://mirror.mycorp.com/tarballs/ \
"

MIRRORS += "\
git://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \n \
https://.*/.* https://downloads.yoctoproject.org/mirror/sources/ \
"

EMIRRORS += "\
git://sourceware.org/git/glibc.git https://downloads.yoctoproject.org/mirror/sources/ \n \
git://sourceware.org/git/binutils-gdb.git https://downloads.yoctoproject.org/mirror/sources/ \
"

✅ 如果你在公司环境中，建议运维搭建本地 Git 镜像 + tarball 镜像，更加稳健。

六、调试技巧与日志观察

你可以用如下方式观察实际使用了哪些 URL：

bitbake <target> -c fetch -v

关键日志：

NOTE: Trying PREMIRRORS
NOTE: Trying original URL
NOTE: Trying MIRRORS
NOTE: Trying EMIRRORS

七、遇到失败时的清理方法

如果之前失败过，Yocto 可能残留错误的 lock 文件或不完整的 tarball：

bitbake -c cleanall <recipe>
rm -rf downloads/<file>

重新触发构建：

bitbake <target>

八、镜像地址推荐清单

镜像类型	推荐地址	说明
Yocto 官方 tarball	https://downloads.yoctoproject.org/mirror/sources/	提供 tar.gz 压缩包
清华大学开源镜像站	https://mirrors.tuna.tsinghua.edu.cn/yocto/	国内高速
企业内网镜像	自建 Gitlab/Nexus/Artifactory	高速+稳定
GitHub 镜像	https://github.com.cnpmjs.org/	可替代部分 clone