i.MX95 Yocto BSP 构建指南 · Docker 容器篇
# i.MX95 Yocto BSP 构建指南 · Docker 容器篇**版本**：LF6.18.2-1.0.0 | Yocto 5.3 Whinlatter
**目标平台**：imx95-15x15-lpddr4x-frdm
**宿主环境**：Docker Engine on Ubuntu 22.04 LTS / Windows / macOS
**官方仓库**：https://github.com/nxp-imx/imx-docker
---
◆
## 概述
NXP 官方维护 `<span leaf="">imx-docker</span>` 仓库，提供开箱即用的 Dockerfile 与构建脚本，用于在 Docker 容器内执行 i.MX Yocto BSP 构建。该方案将 Yocto 所需的全部依赖、工具链及配置封装在镜像内，通过 Volume 挂载将源码、下载包、缓存及构建产物持久化至宿主机，实现环境隔离与数据复用。
与裸机构建相比，Docker 方案的核心差异在于**数据持久化策略**。容器销毁后内部数据全部丢失，必须通过 Volume 将 `<span leaf="">DL_DIR</span>`、`<span leaf="">SSTATE_DIR</span>`、源码目录及构建输出挂载到宿主机。同时，容器内用户需与宿主机用户 UID/GID 匹配，以避免构建产物在宿主机上出现权限混乱。
**前置条件**：宿主机磁盘剩余空间不低于 400 GB；Docker Engine 已安装且守护进程正常运行。
---
◆
## 一、Docker 宿主机准备
### 1.1 安装 Docker Engine
Ubuntu 22.04 安装 Docker：
```
sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
验证安装：
```
docker --version
docker run hello-world
```
### 1.2 配置国内镜像加速（可选）
国内网络环境下，Docker Hub 拉取基础镜像缓慢。在 `<span leaf="">/etc/docker/daemon.json</span>` 中配置镜像加速：
```
{
"registry-mirrors": [
"https://docker.mirrors.ustc.edu.cn",
"https://hub-mirror.c.163.com",
"https://mirror.baidubce.com"
]
}
```
重启 Docker 守护进程：
```
sudo systemctl restart docker
```
### 1.3 将当前用户加入 docker 组
避免每次执行 `<span leaf="">docker</span>` 命令均需 `<span leaf="">sudo</span>`：
```
sudo usermod -aG docker $USER
newgrp docker
```
---
◆
## 二、克隆 imx-docker 仓库
NXP 官方仓库地址：
```
cd ~
git clone https://github.com/nxp-imx/imx-docker.git
cd imx-docker
```
仓库结构：
```
.
├── Dockerfile-Ubuntu-18.04
├── Dockerfile-Ubuntu-20.04
├── Dockerfile-Ubuntu-22.04
├── README.md
├── docker-build.sh
├── docker-run.sh
├── env.sh -> imx-6.6.3-1.0.0/env.sh
└── imx-6.6.3-1.0.0
├── env.sh
└── yocto-build.sh
```
> 注：`<span leaf="">env.sh</span>` 为符号链接，指向对应 BSP 版本的目录。后续需根据实际 i.MX95 版本调整。
---
◆
## 三、配置构建环境变量
imx-docker 使用 `<span leaf="">env.sh</span>` 定义构建参数。在仓库根目录编辑或创建 `<span leaf="">env.sh</span>`：
```
cd ~/imx-docker
# 若 env.sh 指向旧版本，重新链接到当前工作目录
cp imx-6.6.3-1.0.0/env.sh env.sh
vim env.sh
```
关键变量说明：
| 变量 | 说明 | 建议值 |
| ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------- |
| `DOCKER_WORKDIR` | 宿主机主工作目录 | `/mnt/yocto-disk`或`~/yocto-disk` |
| `IMX_RELEASE` | BSP 版本目录名 | `imx-6.18.2-1.0.0`（根据实际版本调整） |
| `USER` | 宿主机用户名 | 自动检测 |
| `HOME` | 宿主机 home 目录 | 自动检测 |
`<span leaf="">env.sh</span>` 示例：
```
export DOCKER_WORKDIR=/mnt/yocto-disk
export IMX_RELEASE=imx-6.18.2-1.0.0
export USER=$(whoami)
export HOME=$HOME
```
确保 `<span leaf="">DOCKER_WORKDIR</span>` 所在分区剩余空间不低于 400 GB，且目录归属当前用户：
```
mkdir -p /mnt/yocto-disk
sudo chown $(id -u):$(id -g) /mnt/yocto-disk
```
---
◆
## 四、构建 Docker 镜像
imx-docker 提供 `<span leaf="">docker-build.sh</span>` 脚本，根据指定的 Dockerfile 自动构建镜像。脚本内部会处理 UID/GID 匹配，确保容器内用户与宿主机一致。
### 4.1 使用官方 Dockerfile-Ubuntu-22.04
```
cd ~/imx-docker
./docker-build.sh Dockerfile-Ubuntu-22.04
```
脚本执行流程：
1. 读取 `<span leaf="">env.sh</span>` 获取环境变量
2. 检测宿主机 UID/GID，作为构建参数传入 Dockerfile
3. 构建镜像并打标签，格式为 `<span leaf="">imx-yocto-<os>:<version></span>`
构建完成后验证：
```
docker images | grep imx-yocto
```
### 4.2 Dockerfile 说明（可选阅读）
`<span leaf="">Dockerfile-Ubuntu-22.04</span>` 内容概要：
* 基础镜像：`<span leaf="">ubuntu:22.04</span>`
* 预装 Yocto 构建所需的全部依赖包（与裸机 Ubuntu 一致）
* 配置 `<span leaf="">en_US.UTF-8</span>` locale
* 安装 repo 工具至 `<span leaf="">/usr/local/bin/repo</span>`
* 创建与宿主机 UID/GID 一致的用户，避免 Volume 挂载后权限混乱
* 设置文件描述符上限 `<span leaf="">ulimit -n 65536</span>`
无需手动修改 Dockerfile，除非需要添加自定义依赖或更换 repo 下载源。
---
◆
## 五、数据卷规划
`<span leaf="">docker-run.sh</span>` 启动容器时会自动挂载以下 Volume：
| 宿主机路径 | 容器内路径 | 用途 |
| ------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
| `${DOCKER_WORKDIR}` | `/workdir` | 主工作区，存放源码、构建目录 |
| `${DOCKER_WORKDIR}/${IMX_RELEASE}` | `/workdir/${IMX_RELEASE}` | Yocto 构建脚本与配置 |
| `${HOME}` | `/home/${USER}` | 用户主目录，用于 SSH 密钥、git 配置、代理脚本等 |
> 容器内构建目录（`<span leaf="">TMPDIR</span>`）位于 `<span leaf="">/workdir/.../build-*/tmp</span>`，处于容器 Overlay 文件系统内，不单独挂载到宿主机。Yocto 编译对随机 I/O 性能敏感，Overlay 的性能优于通过 volume 挂载的 bind mount。
在宿主机预先创建目录：
```
mkdir -p /mnt/yocto-disk/imx-6.18.2-1.0.0
```
---
◆
## 六、运行容器并执行构建
### 6.1 使用 docker-run.sh 启动容器
`<span leaf="">docker-run.sh</span>` 封装了容器启动参数，包括 Volume 挂载、网络模式、特权模式及环境变量传递：
```
cd ~/imx-docker
./docker-run.sh
```
脚本内部等价于：
```
docker run -itd \
--name imx-yocto-build \
--hostname yocto-builder \
--privileged \
--network host \
-v ${DOCKER_WORKDIR}:/workdir \
-v ${DOCKER_WORKDIR}/${IMX_RELEASE}:/workdir/${IMX_RELEASE} \
-v ${HOME}:/home/${USER} \
-e USER=${USER} \
-e HOME=/home/${USER} \
imx-yocto-ubuntu-22.04:latest \
/bin/bash
```
参数说明：
* `<span leaf="">--privileged</span>`：Yocto 生成 WIC 镜像时需要挂载 loop 设备，必须开启特权模式
* `<span leaf="">--network host</span>`：容器直接使用宿主机网络栈，代理配置与裸机一致
* `<span leaf="">-v</span>`：按官方策略挂载三个目录
### 6.2 进入容器
```
docker exec -it imx-yocto-build /bin/bash
```
进入后提示符显示为 `<span leaf="">yocto@yocto-builder:/workdir$</span>`（或 Dockerfile 中定义的用户名）。
### 6.3 容器生命周期管理
| 操作 | 命令 |
| ---------- | ---------------------------------------------------------------------- |
| 停止容器 | `docker stop imx-yocto-build` |
| 启动容器 | `docker start imx-yocto-build` |
| 重新进入 | `docker exec -it imx-yocto-build /bin/bash` |
| 删除容器 | `docker rm -f imx-yocto-build` |
| 查看日志 | `docker logs imx-yocto-build` |
构建过程中不建议删除容器，否则容器内未保存至 volume 的数据（如 `<span leaf="">TMPDIR</span>` 中的中间文件）将丢失。
---
◆
## 七、Repo 工具与代码同步
### 7.1 Repo 安装
容器镜像构建时已预装 repo 工具至 `<span leaf="">/usr/local/bin/repo</span>`。若需更新或重新安装，提供三个源：
**方案一：清华大学开源软件镜像站（国内网络推荐）**
```
curl -o /usr/local/bin/repo https://mirrors.tuna.tsinghua.edu.cn/git/git-repo
chmod a+x /usr/local/bin/repo
repo --version # >= v2.52
```
**方案二：中国科学技术大学镜像站（国内网络备选）**
```
curl -o /usr/local/bin/repo https://mirrors.ustc.edu.cn/git/git-repo
chmod a+x /usr/local/bin/repo
repo --version
```
**方案三：Google 官方源（海外网络或代理通畅时使用）**
```
curl -o /usr/local/bin/repo https://gerrit.googlesource.com/git-repo/repo
chmod a+x /usr/local/bin/repo
repo --version
```
> 国内网络环境下，若直接访问 Google 源，大概率出现 `<span leaf="">Connection timed out</span>`。建议先测试 `<span leaf="">curl -I https://gerrit.googlesource.com</span>`，若返回正常再选用方案三。
### 7.2 仓库初始化与同步
在容器内执行，工作目录位于 Volume 挂载点 `<span leaf="">/workdir</span>`，数据持久化至宿主机：
```
cd /workdir
# 国内网络（清华大学镜像）
repo init \
--repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo \
-u https://github.com/nxp-imx/imx-manifest \
-b imx-linux-whinlatter \
-m imx-6.18.2-1.0.0.xml
# 国内网络（中科大镜像）
# repo init \
# --repo-url=https://mirrors.ustc.edu.cn/git/git-repo \
# -u https://github.com/nxp-imx/imx-manifest \
# -b imx-linux-whinlatter \
# -m imx-6.18.2-1.0.0.xml
# 海外网络（Google 官方源）
# repo init \
# --repo-url=https://gerrit.googlesource.com/git-repo \
# -u https://github.com/nxp-imx/imx-manifest \
# -b imx-linux-whinlatter \
# -m imx-6.18.2-1.0.0.xml
```
参数说明：
* `<span leaf="">--repo-url</span>`：repo 工具本身的下载源，需与 7.1 节选用的安装源保持一致
* `<span leaf="">-u https://github.com/nxp-imx/imx-manifest</span>`：NXP i.MX 官方 manifest 仓库地址
* `<span leaf="">-b imx-linux-whinlatter</span>`：Yocto 5.3 Whinlatter 分支
* `<span leaf="">-m imx-6.18.2-1.0.0.xml</span>`：BSP LF6.18.2-1.0.0 版本 manifest 文件
执行代码同步：
```
repo sync -c -j$(nproc) # 网络不稳时降至 -j2
```
---
◆
## 八、构建环境初始化
`<span leaf="">repo sync</span>` 完成后，进入 BSP 根目录并执行 NXP 特有的环境初始化脚本 `<span leaf="">imx-setup-release.sh</span>`：
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
```
参数说明：
* `<span leaf="">MACHINE=imx95-15x15-lpddr4x-frdm</span>`：目标硬件平台，对应 FRDM-IMX95 开发板
* `<span leaf="">DISTRO=fsl-imx-xwayland</span>`：发行版配置，启用 XWayland 图形栈
* `<span leaf="">-b build-imx95-xwayland-15x15-lpddr4x-frdm</span>`：指定构建输出目录名
执行后提示符将显示 `<span leaf="">$</span>`，表示已进入 BitBake 构建环境。
**注意**：每次新开终端或重新进入容器，均需重新执行上述 `<span leaf="">source</span>` 命令进入构建环境，否则 `<span leaf="">bitbake</span>` 命令不可用。
---
◆
## 九、代理环境配置
### 9.1 网络访问现状
Yocto 构建需访问的外部仓库及其国内可用性：
* `<span leaf="">github.com</span>`：大量软件包源码，国内访问受限
* `<span leaf="">android.googlesource.com</span>`：`<span leaf="">gfxstream</span>` 等组件依赖
* `<span leaf="">gitlab.freedesktop.org</span>`：`<span leaf="">shared-mime-info</span>` 等包
* `<span leaf="">crates.io</span>`：Rust 生态 crate 仓库，下载量大且速度慢
直接全局代理会导致 Yocto 官方镜像源（`<span leaf="">mirrors.edge.kernel.org</span>`、`<span leaf="">ftpmirror.gnu.org</span>`）SSL 握手异常。应采用**分流代理**：外部受限源走代理，官方镜像源直接连接。
### 9.2 代理工具
本地部署 Xray 作为代理入口，监听：
* HTTP 代理：`<span leaf="">127.0.0.1:7890</span>`
* SOCKS5 代理：`<span leaf="">127.0.0.1:1080</span>`
针对 Yocto 构建场景整理的开源配置（含 `<span leaf="">xray-config.json</span>`、`<span leaf="">proxy.sh</span>` 管理脚本及优化 `<span leaf="">no_proxy</span>` 绕过列表）：
**https://github.com/fafactx/vpn-for-yocto**
建议克隆至宿主机 `<span leaf="">~/yocto-disk/vpn-for-yocto</span>`（已通过 Volume 挂载至容器内 `<span leaf="">/home/${USER}/yocto-disk/vpn-for-yocto</span>`）：
```
cd ~
git clone https://github.com/fafactx/vpn-for-yocto.git
```
### 9.3 启动与验证
在容器内执行：
```
cd /home/${USER}/yocto-disk/vpn-for-yocto
./proxy.sh start
./proxy.sh test
```
手动验证：
```
curl -I --connect-timeout 15 -x http://127.0.0.1:7890 https://github.com
curl -I --connect-timeout 15 -x http://127.0.0.1:7890 https://android.googlesource.com
```
确认返回 HTTP 200 后再进入构建阶段。
### 9.4 构建环境变量
进入 Yocto 构建环境后导出代理变量：
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,.local,.internal,192.168.0.0/16,10.0.0.0/8,*.tuna.tsinghua.edu.cn,mirrors.edge.kernel.org,ftpmirror.gnu.org,*.yoctoproject.org"
export NO_PROXY="${no_proxy}"
```
`<span leaf="">no_proxy</span>` 必须包含 `<span leaf="">mirrors.edge.kernel.org</span>` 及 `<span leaf="">*.yoctoproject.org</span>`。遗漏将导致构建过程中出现 `<span leaf="">OpenSSL: error:0A000126:SSL routines::unexpected eof while reading</span>` 错误，该错误与网络代理相关，而非源码本身问题。
### 9.5 Fetch 工作流（分阶段迭代）
不建议直接执行 `<span leaf="">bitbake imx-image-full</span>` 启动完整构建。应先通过多轮迭代将全部源码包 fetch 至本地，确认无网络缺失后再进入编译阶段。
**第一轮：无代理摸底**
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full --runall=fetch
```
约 70%\~80% 的包从官方镜像源成功下载，剩余因网络受限失败，典型报错为 `<span leaf="">exit code 128</span>`、`<span leaf="">Connection timed out</span>`。
**第二轮：定位失败包**
```
grep -r "Fetcher failure" tmp/log/cooker/*/console-latest.log | head -20
grep -r "exit code 128" tmp/work/*/temp/log.do_fetch | head -20
```
常见失败包：
| 源码仓库 | 典型失败包 |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `github.com` | `matter-idl-native`,`imx-gpu-sdk`,`meta-imx`组件 |
| `android.googlesource.com` | `gfxstream` |
| `gitlab.freedesktop.org` | `shared-mime-info` |
| `crates.io` | `python3-maturin-native`及 cargo 依赖 |
**第三轮：代理补包**
启动代理后，重新进入构建环境，仅对失败包设置代理并重新 fetch：
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,..."
bitbake matter-idl-native gfxstream shared-mime-info python3-maturin-native --runall=fetch
```
**第四轮：验证**
关闭代理，重新进入构建环境，再次执行全量 fetch：
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
bitbake imx-image-full --runall=fetch
```
若仍有失败，重复第二轮至第三轮，直至连续两次无报错通过。
**第五轮：编译**
全部缓存至 `<span leaf="">DL_DIR</span>` 后，重新进入构建环境并编译：
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full
```
典型耗时与裸机相近（8\~12 小时），容器化开销主要来自 Volume 挂载的 I/O 延迟，对编译阶段影响有限。
编译期间建议保持代理可用，或在 `<span leaf="">local.conf</span>` 中设置 `<span leaf="">BB_NO_NETWORK = "1"</span>`（前提是 fetch 阶段已完全通过）。
---
◆
## 十、磁盘空间优化
Yocto 完整构建默认峰值可达 500 GB+。以下配置应组合使用，整体追加至 `<span leaf="">build-*/conf/local.conf</span>`：
```
# ===== 最小化空间配置 =====
INHERIT += "rm_work"
IMAGE_FSTYPES = "wic"
PACKAGE_CLASSES = "package_ipk"
DL_DIR = "/workdir/downloads"
SSTATE_DIR = "/workdir/sstate-cache"
IMAGE_GEN_DEBUGFS = "0"
# ==========================
```
* `<span leaf="">rm_work</span>`：编译完成后删除中间文件，节省 60%\~70% 空间
* `<span leaf="">wic</span>` 单格式：禁用体积较大的 tarball 输出
* `<span leaf="">ipk</span>`：包格式体积优于 deb/rpm
* `<span leaf="">DL_DIR</span>` / `<span leaf="">SSTATE_DIR</span>` 外置：通过 Volume 挂载至宿主机，容器内仅保留编译中间态
启用后峰值约 150\~200 GB（容器内 Overlay），配合外置缓存，总空间需求约 250\~300 GB。
如需保留特定包用于调试：
```
INHERIT += "rm_work"
RM_WORK_EXCLUDE += "linux-imx u-boot-imx"
```
---
◆
## 十一、镜像构建与输出
### 11.1 执行构建
```
cd /workdir/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full
```
### 11.2 构建产物
构建成功后，关键输出位于容器内：
```
/workdir/imx-yocto-bsp/build-imx95-xwayland-15x15-lpddr4x-frdm/tmp/deploy/images/imx95-15x15-lpddr4x-frdm/
```
| 文件 | 说明 |
| --------------------------------------------------------- | -------------------------- |
| `imx-image-full-*.wic` | 完整磁盘镜像，可直接烧录 |
| `imx-boot-*-sd.bin-flash` | SD 卡启动引导程序 |
| `Image` | Linux 内核镜像 |
| `imx95-15x15-lpddr4x-frdm.dtb` | 设备树二进制 |
由于 `<span leaf="">/workdir</span>` 已通过 Volume 挂载至宿主机 `<span leaf="">${DOCKER_WORKDIR}</span>`，构建产物在宿主机上可直接访问，无需从容器内复制。
### 11.3 SD 卡烧录
在宿主机使用 `<span leaf="">dd</span>` 命令写入 WIC 镜像。操作前务必通过 `<span leaf="">lsblk</span>` 确认目标设备，避免误写系统盘：
```
sudo dd if=/mnt/yocto-disk/imx-yocto-bsp/build-*/tmp/deploy/images/imx95-15x15-lpddr4x-frdm/imx-image-full-*.wic of=/dev/sdX bs=1M status=progress
sync
```
---
◆
## 十二、常见问题与解决
**Q1：容器内构建产物在宿主机上显示为 `<span leaf="">unknown user</span>` 或数字 UID**
`<span leaf="">docker-build.sh</span>` 构建时未正确传入 UID/GID。删除现有镜像并重新执行 `<span leaf="">docker-build.sh</span>`：
```
docker rmi imx-yocto-ubuntu-22.04:latest
cd ~/imx-docker
./docker-build.sh Dockerfile-Ubuntu-22.04
```
**Q2：构建中报 `<span leaf="">No space left on device</span>`，但宿主机磁盘充足**
Docker 使用 overlay2 存储驱动时，容器可写层受限于 Docker 数据目录（默认 `<span leaf="">/var/lib/docker</span>`）所在分区的剩余空间。若该分区不足，需迁移 Docker 数据目录或清理无用镜像：
```
# 查看 Docker 磁盘使用
docker system df
# 清理无用镜像、容器、缓存
docker system prune -a
```
或将 Docker 数据目录迁移至大容量分区（修改 `<span leaf="">/etc/docker/daemon.json</span>`）：
```
{
"data-root": "/mnt/bigdisk/docker"
}
```
**Q3：WIC 镜像生成失败，`<span leaf="">losetup</span>` 或 `<span leaf="">mkfs</span>` 报错**
Yocto 生成 WIC 镜像需要操作 loop 设备。若容器未以 `<span leaf="">--privileged</span>` 启动，将出现权限错误。`<span leaf="">docker-run.sh</span>` 已默认开启 `<span leaf="">--privileged</span>`，若手动 `<span leaf="">docker run</span>` 需确认该参数存在。
**Q4：容器内代理无法连接宿主机代理服务**
因 `<span leaf="">--network host</span>` 已启用，容器与宿主机共享网络栈，`<span leaf="">127.0.0.1:7890</span>` 可直接访问。若代理监听在 `<span leaf="">127.0.0.1</span>` 以外的地址（如 `<span leaf="">192.168.x.x</span>`），需确保该地址在容器内可达。检查代理监听地址：
```
# 宿主机上
ss -tlnp | grep 7890
```
**Q5：如何保存容器内修改后的环境（如额外安装的包）**
容器重启后，内部未持久化的修改（如在容器内 `<span leaf="">apt install</span>` 额外的包）将丢失。建议将此类修改反映至 Dockerfile 并重新构建镜像，或使用 `<span leaf="">docker commit</span>` 保存当前容器状态为新镜像：
```
docker commit imx-yocto-build imx-yocto-ubuntu-22.04:custom
```
**Q6：容器内 `<span leaf="">apt update</span>` 连不上 Ubuntu 官方源**
容器有自己的网络栈，不会自动继承 dockerd 代理。若宿主机需要代理才能访问外网，需在 Dockerfile 内显式声明代理环境变量（`<span leaf="">ENV http_proxy=...</span>`），或在容器启动后手动配置 apt 代理：
```
echo 'Acquire::http::Proxy "http://127.0.0.1:7890";' | sudo tee /etc/apt/apt.conf.d/proxy.conf
```
---
◆
## 附录
### A. 代理环境变量
```
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,.local,.internal,192.168.0.0/16,10.0.0.0/8,*.tuna.tsinghua.edu.cn,mirrors.edge.kernel.org,ftpmirror.gnu.org,*.yoctoproject.org"
export NO_PROXY="${no_proxy}"
```
### B. Docker 容器管理速查
| 操作 | 命令 |
| ------------------ | ---------------------------------------------------------------------- |
| 停止容器 | `docker stop imx-yocto-build` |
| 启动容器 | `docker start imx-yocto-build` |
| 进入容器 | `docker exec -it imx-yocto-build /bin/bash` |
| 删除容器 | `docker rm -f imx-yocto-build` |
| 查看容器磁盘占用 | `docker system df -v` |
| 清理无用资源 | `docker system prune -a` |
### C. 构建参数汇总
| 参数 | 值 |
| -------------- | -------------------------- |
| BSP 版本 | LF6.18.2-1.0.0 |
| Yocto 版本 | 5.3 (Whinlatter) |
| Machine | imx95-15x15-lpddr4x-frdm |
| Distro | fsl-imx-xwayland |
| 目标架构 | aarch64 |
| 容器基础镜像 | ubuntu:22.04 |
### D. 相关资源
* NXP 官方 imx-docker 仓库：https://github.com/nxp-imx/imx-docker
* Yocto 代理配置仓库：https://github.com/fafactx/vpn-for-yocto
* NXP i.MX95 官方 BSP 文档
* Yocto Project 官方文档
### E. BitBake 常用命令速查
| 命令 | 作用 | 示例 |
| ------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------- |
| `bitbake ` | 编译指定配方 | `bitbake imx-image-full` |
| `bitbake-c fetch` | 仅执行 fetch 任务 | `bitbake imx-image-full -c fetch` |
| `bitbake--runall=fetch`| 对目标及其依赖图中所有配方执行 fetch | `bitbake imx-image-full --runall=fetch`|
| `bitbake--runonly=fetch` | 仅对目标配方执行 fetch（不处理依赖） | `bitbake imx-image-full --runonly=fetch` |
| `bitbake-c cleansstate`| 清理 sstate 缓存并重新编译 | `bitbake linux-imx -c cleansstate` |
| `bitbake-c cleanall` | 完全清理配方 | `bitbake u-boot-imx -c cleanall` |
| `bitbake-c devshell` | 进入配方的开发 Shell | `bitbake linux-imx -c devshell` |
| `bitbake-c menuconfig` | 打开内核菜单配置 | `bitbake linux-imx -c menuconfig` |
| `bitbake-c listtasks` | 列出该配方所有可用任务 | `bitbake linux-imx -c listtasks` |
| `bitbake-C compile` | 清除 compile 任务的 stamp 后执行默认任务 | `bitbake linux-imx -C compile` |
| `bitbake-f` | 强制重新运行（忽略已有 stamp） | `bitbake imx-boot -f` |
| `bitbake-k` | 出错后继续构建 | `bitbake imx-image-full -k` |
| `bitbake-n` | 干跑，不实际执行 | `bitbake imx-image-full -n` |
| `bitbake-p` | 仅解析配方后退出 | `bitbake imx-image-full -p` |
| `bitbake--no-setscene` | 忽略 sstate 缓存，全部重新构建 | `bitbake imx-image-full --no-setscene` |
| `bitbake--skip-setscene` | 跳过 setscene 任务 | `bitbake imx-image-full --skip-setscene` |
| `bitbake--setscene-only` | 仅执行 setscene 任务 | `bitbake imx-image-full --setscene-only` |
| `bitbake -s` | 显示所有配方的当前与首选版本 | — |
| `bitbake -e ` | 显示配方的完整环境变量 | `bitbake -e linux-imx` |
| `bitbake -e\| grep ^PV=`| 查看配方版本变量 PV | `bitbake -e linux-imx \| grep ^PV=` |
| `bitbake -g ` | 生成依赖关系图（.dot 格式） | `bitbake -g imx-image-full` |
| `bitbake -D ` | 提高调试级别 | `bitbake -D imx-image-full` |
| `bitbake -v ` | 启用 shell 任务跟踪 | `bitbake -v imx-image-full` |
| `bitbake -q ` | 减少终端日志输出 | `bitbake -q imx-image-full` |
| `bitbake -m` | 终止后台 bitbake server | — |
| `bitbake --status-only` | 检查远程 bitbake server 状态 | — |
| `bitbake --server-only` | 仅启动 server，不启动 UI | — |
| `bitbake-layers show-layers` | 列出所有启用的 meta-layer | — |
| `bitbake-layers show-recipes` | 列出所有可用配方 | — |
| `bitbake-layers show-appends` | 列出所有 bbappend 文件 | — |
#### 并行任务控制说明
`<span leaf="">bitbake</span>` 命令行不提供 `<span leaf="">-j</span>` 参数。并行任务数通过以下方式控制：
* 环境变量：`<span leaf="">export BB_NUMBER_THREADS=4</span>`
* `<span leaf="">local.conf</span>`：`<span leaf="">BB_NUMBER_THREADS = "4"</span>`
* 宿主机 CPU 数：默认自动检测 `<span leaf="">$(nproc)</span>`
---
◆
*本文档基于 NXP 官方 imx-docker 仓库及 Ubuntu 22.04 容器实际构建环境整理，所有命令均经过验证。*
页:
[1]