整体架构

┌─────────────────────────────────────────────────────────────┐
│                     Windows 10 主机                          │
│  ┌──────────────┐    ┌──────────────────────────────────┐   │
│  │ VS Code /    │    │         WSL2                      │   │
│  │ 串口工具 /    │    │  ┌────────────────────────────┐  │   │
│  │ 烧写工具      │    │  │  Ubuntu（纯净宿主）         │  │   │
│  │              │    │  │  · 只运行 Docker Engine      │  │   │
│  └──────┬───────┘    │  │  · SDK 源码：~/NightEyes/sdk          │  │   │
│         │            │  │  └──────────┬───────────────┘  │   │
│         │ RS232/USB  │  │             │ bind mount       │   │
│         │            │  │  ┌──────────▼───────────────┐  │   │
│         │            │  │  │  Docker 容器              │  │   │
│         │            │  │  │  ubuntu:18.04（编译环境） │  │   │
│         │            │  │  │  · 所有依赖包             │  │   │
│         │            │  │  │  · gperf / automake      │  │   │
│         │            │  │  │  · mtd-utils 依赖库      │  │   │
│         │            │  │  │  · SDK 挂载到 /opt/sdk   │  │   │
│         │            │  │  │  · SDK 自带交叉工具链     │  │   │
│         │            │  │  └──────────────────────────┘  │   │
│         │            │  └──────────────────────────────────┘   │
│  ┌──────▼───────┐                                              │
│  │ 目标板        │  以太网：SSH / scp / NFS（需端口转发）       │
│  │ Pico-G1      │◄─────────────────────────────────────────────┘
│  └──────────────┘

核心思路：WSL2 的 Ubuntu 只当干净的 Docker 宿主，不装任何编译相关软件；所有编译依赖固化在 ubuntu:18.04 容器里；SDK 源码放在 WSL2 本地，通过目录挂载进容器，修改代码不用重建镜像。

关于 Ubuntu 版本：Microsoft Store 里的通用 "Ubuntu" 应用当前是 26.04 LTS。作为 Docker 宿主，22.04 和 26.04 没有任何区别——真正的编译环境在 Docker 容器里（ubuntu:18.04），宿主只负责跑 Docker。

一、前置条件

检查 Windows 版本：按 Win + R，输入 winver 回车，查看版本号。

检查虚拟化是否启用：按 Ctrl + Shift + Esc 打开任务管理器 → 性能 → CPU → 右下角看"虚拟化"是否为"已启用"。如果未启用，需要进 BIOS 开启。

二、安装 WSL2 和 Ubuntu

2.1 一键安装（Win10 2004+ 支持）

以管理员身份打开 PowerShell（开始菜单搜 "PowerShell"，右键"以管理员身份运行"），执行：

wsl --install -d Ubuntu

这条命令会自动完成：

• 启用"适用于 Linux 的 Windows 子系统"功能

• 启用"虚拟机平台"功能

• 下载并安装 WSL2 内核

• 设置 WSL2 为默认版本

• 下载并安装 Ubuntu（最新 LTS）

执行完后重启电脑。

如果一键安装报错（常见于较老的 Win10 版本），走下面的手动安装流程。

2.2 手动安装

步骤 1：启用 WSL 和虚拟机平台（管理员 PowerShell）

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

步骤 2：重启电脑

步骤 3：下载并安装 WSL2 Linux 内核更新包

下载地址：https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

下载后双击安装。

步骤 4：设置 WSL2 为默认版本

wsl --set-default-version 2

步骤 5：安装 Ubuntu

打开 Microsoft Store，搜索 "Ubuntu"，点击第一个结果（图标是橙色圆形 Ubuntu Logo，名称就叫 "Ubuntu"，评分 3.9★）的"免费下载" / "获取"。

注意：Store 里搜不到独立的 "Ubuntu 22.04" 是正常的，微软已将旧版下架。第一个通用 "Ubuntu" 就是最新 LTS（当前 26.04），直接装它即可。

2.3 初始化 Ubuntu

安装完成后，开始菜单打开 "Ubuntu"，第一次启动会要求设置用户名和密码：

Enter new UNIX username: 你的用户名（全小写，比如 dachou）
New password: 你的密码
Retype new password: 再次输入密码

密码输入时屏幕不显示字符，正常现象，输完回车即可。

2.4 验证安装

在 Ubuntu 终端里执行：

# 查看 Ubuntu 版本，应该显示 26.04（或当前最新 LTS）
lsb_release -a

# 查看 WSL 版本（在 Windows PowerShell 里执行）
wsl -l -v

wsl -l -v 输出中 Ubuntu 的 VERSION 列应该是 2。如果是 1，执行：

wsl --set-version Ubuntu 2

2.5 用 Xshell 连接 WSL（可选）

如果你习惯用 Xshell 等 SSH 客户端操作 Linux，可以通过 SSH 连接 WSL 的 Ubuntu。

第 1 步：在 Ubuntu 里安装并启动 SSH 服务

sudo apt update
sudo apt install -y openssh-server
sudo service ssh start

设置 WSL 开机自动启动 SSH：

echo -e "[boot]\ncommand=\"service ssh start\"" | sudo tee -a /etc/wsl.conf

然后 PowerShell 执行 wsl --terminate Ubuntu 重启生效。

第 2 步：Xshell 新建会话

连接时用户名填 dachou，密码是 Ubuntu 的登录密码。

连不上的处理：

WSL2 偶尔 localhost 转发会抽风，如果 localhost 连不上，在 Ubuntu 里查实际 IP：

hostname -I

把输出的 IP（如 172.27.x.x）填到 Xshell 的"主机"里。

注意：WSL2 里不能用 reboot / systemctl 重启（默认没有 systemd），重启 Ubuntu 用 PowerShell 执行 wsl --terminate Ubuntu，然后重新打开。

三、配置 WSL2 资源限制

WSL2 默认会占用一半内存，且虚拟磁盘默认上限较小。编译嵌入式 SDK 需要更多资源，建议手动配置。

在 Windows 的用户目录下（C:\Users\你的用户名\）创建文件 .wslconfig，内容如下：

[wsl2]
# 分配给 WSL2 的内存，根据你电脑总内存调整
# 16GB 内存建议写 8GB，32GB 内存建议写 16GB
memory=8GB

# 分配的 CPU 核心数
# 20个逻辑处理核建议写 10， 16个逻辑处理核建议写 8
processors=4

# 虚拟磁盘最大空间（单位 GB），SDK 编译产物较大，建议给足
swap=8GB

注意：memory 和 processors 根据你电脑实际配置调整，不要超过物理资源。比如电脑只有 8GB 内存，就写 memory=4GB。

创建完后，在 PowerShell 里重启 WSL 生效：

wsl --shutdown

然后重新打开 Ubuntu 即可。

（可选）将 WSL 移动到非系统盘

WSL2 默认把 Ubuntu 虚拟磁盘（ext4.vhdx）装在 C 盘：

C:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu...\LocalState\ext4.vhdx

SDK 全量编译后，虚拟磁盘很容易涨到 30~50GB。如果 C 盘空间紧张，建议移到其他盘。最好在装 Docker Desktop 之前移动，避免影响 WSL 集成。

方法一：--move 一行移动（推荐，WSL 0.58.0+ 支持）

# 1. 关闭 WSL
wsl --shutdown

# 2. 创建目标目录（路径自己改，比如 D:\wsl\ubuntu）
mkdir D:\wsl\ubuntu

# 3. 移动发行版（自动迁移，不丢数据）
wsl --manage Ubuntu --move D:\wsl\ubuntu

先执行 wsl --version 确认版本 ≥ 0.58.0，不支持就用方法二。

方法二：export / import（兼容所有版本）

⚠️ 重要：export 后的 tar 文件先不要删，import 完成后先验证能正常启动，确认没问题再删 tar 和原发行版。如果 import 后启动闪退（wsl -d Ubuntu -u root 报"未发现用户"），说明 import 损坏，还可以用 tar 重新 import。

# 1. 关闭 WSL
wsl --shutdown

# 2. 导出为 tar（临时目录，确保有 10GB+ 空间）
mkdir D:\wsl-backup
wsl --export Ubuntu D:\wsl-backup\ubuntu.tar

# 3. 确认导出成功（tar 应该几个 GB，大小正常再继续）
dir D:\wsl-backup\ubuntu.tar

# 4. 注销原 C 盘发行版（会删除 C 盘 vhdx）
wsl --unregister Ubuntu

# 5. 导入到新位置
mkdir D:\wsl\ubuntu
wsl --import Ubuntu D:\wsl\ubuntu D:\wsl-backup\ubuntu.tar

# 6. 【关键】先验证能启动！能进去再继续
wsl -d Ubuntu -u root

能进去显示 root@xxx:~# 后，再配置默认用户并清理：

# 在 Ubuntu 里执行（root 身份下）
tee /etc/wsl.conf <<'EOF'
[user]
default=你的用户名
EOF

# 回到 PowerShell，重启验证普通用户登录
wsl --shutdown
wsl -d Ubuntu

# 确认正常登录后，再删临时 tar
del D:\wsl-backup\ubuntu.tar

移动完验证：

wsl -l -v
wsl -d Ubuntu

能正常进入就 OK。

移动后 Ubuntu 打开闪退的修复（import 方式常见问题）

现象：移动后点开始菜单的"Ubuntu"图标，窗口一闪就退。

原因：开始菜单里的快捷方式是 Store 版 Ubuntu 应用创建的，wsl --unregister 后原发行版已注销，快捷方式关联失效。import 出来的发行版要用 wsl -d Ubuntu 启动。

修复步骤：

第 1 步：命令行启动，确认系统完好

wsl -l -v
wsl -d Ubuntu

wsl -l -v 能看到 Ubuntu（STATE 为 Stopped）、wsl -d Ubuntu 能进去（显示 root@xxx:~#），说明系统没问题，只是启动方式和默认用户要修。

第 2 步：确认普通用户还在

id dachou

有输出说明用户在。如果提示 "no such user"，重新创建：

useradd -m -s /bin/bash dachou
passwd dachou

第 3 步：配置默认登录用户

tee /etc/wsl.conf <<'EOF'
[user]
default=dachou
EOF

exit 退出后重启 WSL：

wsl --shutdown
wsl -d Ubuntu

这次进去应该就是 dachou@xxx:~$。

第 4 步：重建快捷方式（可选）

右键桌面 → 新建 → 快捷方式，位置填：

wsl.exe -d Ubuntu

命名为"Ubuntu"，以后双击直接进。

如果 wsl -d Ubuntu 也闪退并报错，说明 import 不完整，需要回到方法二重新 export/import 一次（确保 export 的 tar 文件大小正常，几个 GB 才对）。

四、安装 Docker Desktop

4.1 下载安装

去 Docker 官网下载 Docker Desktop for Windows：

https://www.docker.com/products/docker-desktop/

下载后双击安装，安装过程中确保勾选 "Use WSL 2 instead of Hyper-V"（默认就是勾选的）。

安装完成后重启电脑。

4.2 启用 WSL2 后端和 Ubuntu 集成

1. 启动 Docker Desktop（桌面图标双击）

2. 第一次启动会弹出引导，跳过登录（Skip / Continue without signing in）

3. 点击右上角齿轮图标 ⚙️ 打开设置

4. 左侧选 General，确认 "Use the WSL 2 based engine" 已勾选

5. 左侧选 Resources → WSL Integration

6. 打开 "Enable integration with my default WSL distro"

7. 在下方列表中找到 Ubuntu，打开开关

8. 点击右下角 Apply & Restart

4.3 配置国内镜像加速（国内网络必做）

Docker Hub 在国内拉取镜像很慢，需要配置镜像加速器。

在 Docker Desktop 设置里：

1. 左侧选 Docker Engine

2. 在 JSON 配置里添加 registry-mirrors 字段，修改后如下：

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}

3. 点击 Apply & Restart

如果上面的加速器失效，可以搜索"Docker 镜像加速"找最新可用地址，替换 registry-mirrors 里的 URL。

4.4 验证 Docker 安装

打开 Ubuntu 终端，执行：

docker --version
docker run hello-world

如果看到 "Hello from Docker!" 字样，说明安装成功。

4.5 常见问题：WSL 版本过旧

现象：启动 Docker Desktop 时报错 "WSL needs updating"，提示 WSL 版本太老。

原因：Windows 自带的 WSL（inbox 版）版本较老，不支持 --manage 等新命令，Docker Desktop 要求更新。

解决方法一：命令行更新（管理员 PowerShell）

wsl --update

国内网络如果下载慢或报错 0x80072eff（网络超时），用方法二。

解决方法二：手动下载 msi 安装包（推荐，更快更稳）

1. 浏览器打开 WSL GitHub Releases（国内用镜像加速）：

   • 官方地址：https://github.com/microsoft/WSL/releases/latest

   • 国内镜像：https://ghfast.top/https://github.com/microsoft/WSL/releases/latest

2. 下载最新版的 Microsoft.WSL_2.x.x.x_x64.msi（x64 版本）

3. 双击安装

4. 管理员 PowerShell 验证：

   wsl --version
   

   能看到版本号（如 2.4.x.x）即成功。

5. 重启 WSL 和 Docker Desktop：

   wsl --shutdown
   

   然后重新打开 Docker Desktop，点 "Try Again"。

更新 WSL 后的额外好处：版本 ≥ 0.58.0 支持 wsl --manage Ubuntu --move <路径> 一行命令移动 WSL 到其他盘，不用再 export/import。

五、准备 SDK 源码

重要：SDK 必须放在 WSL2 的 Linux 文件系统里（如 ~/NightEyes/sdk），绝对不要放在 /mnt/c/（Windows 盘）下，否则编译极慢且符号链接问题会导致编译失败。

5.1 在 WSL2 中克隆 SDK

打开 Ubuntu 终端，执行：

# 回到用户主目录
cd ~

# 先建父目录，再把仓库直接克隆成 ~/NightEyes/sdk
mkdir -p ~/NightEyes
git clone https://gitee.com/ShiMetaPi_0/shimetapi_pico_gx.git ~/NightEyes/sdk

git clone <url> <目录> 的第二个参数就是最终目录：写成 ~/NightEyes/sdk 后，该目录里直接是 SDK 内容（run.sh、build/、tools/…），不会再套一层 sdk/sdk。
不要用 cd ~ && git clone ... sdk——那会克隆到 ~/sdk，和下文所有 ~/NightEyes/sdk 的路径对不上。

如果已经误克隆到 ~/sdk，不用重下，直接挪：

mkdir -p ~/NightEyes
mv ~/sdk ~/NightEyes/sdk

5.2 验证 SDK 目录

cd ~/NightEyes/sdk
pwd          # 应输出 /home/<你的用户名>/NightEyes/sdk
ls -la

应该能看到 build/、configs/、source/、tools/、run.sh、cfg.mk 等文件和目录。

若 ls 里只看到一个 sdk/ 子目录，说明多套了一层（例如按旧命令克隆过），把内容上提一层即可：

mv ~/NightEyes/sdk/sdk/* ~/NightEyes/sdk/ && rmdir ~/NightEyes/sdk/sdk

5.3 确认工具链存在

ls tools/linux/toolchains/

应该能看到交叉编译工具链目录（如 arm-gcc12.2.0-linux-uclibceabi）。SDK 自带工具链，不需要额外安装。

六、编写 Dockerfile 并构建镜像

6.1 创建 Dockerfile

在 WSL2 中创建 Dockerfile。一个镜像一个子目录，文件名仍用默认的 Dockerfile：

cd ~
mkdir -p docker-build-env/pico-g1-1804
cd docker-build-env/pico-g1-1804
nano Dockerfile

将下面 附录 A：Dockerfile 完整代码 的完整代码复制粘贴进去，按 Ctrl + O 保存，Ctrl + X 退出。

为什么还叫 Dockerfile，不改个名字区分？
Dockerfile 只是 docker build 的默认清单文件名（大小写敏感），跟镜像名、容器名无关。不同目录下的同名 Dockerfile 完全独立、互不覆盖，所以靠子目录隔离就够了。一旦改名，每次构建都必须加 -f <路径>，漏一次就报 Dockerfile not found；.dockerignore、CI 脚本、本文档里的命令也都要跟着改，纯属自找麻烦。

如果之前已经建过 ~/docker-build-env/Dockerfile，一条命令挪进去即可：

mkdir -p ~/docker-build-env/pico-g1-1804 && mv ~/docker-build-env/Dockerfile ~/docker-build-env/pico-g1-1804/

6.2 Dockerfile 做了什么

6.3 构建镜像

cd ~/docker-build-env/pico-g1-1804
docker build -t pico-g1-build-env:18.04 .

构建过程需要 5~15 分钟，取决于网络速度。看到 Successfully tagged pico-g1-build-env:18.04 即成功。

6.4 验证镜像

docker images

应该能看到 pico-g1-build-env 镜像，大小约 1GB 左右。

6.5 多项目 / 多镜像共存

以后接了别的板子、别的 SDK，不要往同一个 Dockerfile 里塞，也不要给文件改各种名字，一镜像一目录即可：

~/docker-build-env/
├── pico-g1-1804/Dockerfile        # -t pico-g1-build-env:18.04
├── xm7206-2004/Dockerfile         # -t xm7206-build-env:20.04
└── another-proj-2204/Dockerfile   # -t another-proj-build-env:22.04

三条规则：

什么时候才需要 -f：人站在父目录构建时。此时 build context 变成父目录，本 Dockerfile 里没有 COPY/ADD，无副作用：

cd ~/docker-build-env
docker build -f pico-g1-1804/Dockerfile -t pico-g1-build-env:18.04 .

查看与清理：

docker images "pico-g1*"                  # 按项目过滤
docker rmi pico-g1-build-env:18.04        # 删除指定镜像
docker image prune                        # 清理无 tag 的悬空镜像

若确实想用描述性文件名（不推荐）：得用 pico-g1-1804.dockerfile（小写后缀，编辑器能高亮），并且每次构建都带 -f pico-g1-1804.dockerfile，漏了就是 Dockerfile not found。收益只有一个"文件名自解释"，代价是每条命令都变长，多项目时更容易抄错。

七、启动编译容器

7.1 启动命令

在 WSL2 终端执行：

docker run -it --rm \
  -v ~/NightEyes/sdk:/opt/sdk \
  -w /opt/sdk \
  --name pico-build \
  pico-g1-build-env:18.04 \
  bash

参数说明：

7.2 进入容器后验证

# 查看系统版本，应该是 18.04
cat /etc/os-release | grep VERSION

# 查看 SDK 是否挂载成功
ls /opt/sdk/run.sh

# 验证 32 位工具链能否运行
/opt/sdk/tools/linux/toolchains/arm-gcc12.2.0-linux-uclibceabi/bin/arm-gcc12.2.0-linux-uclibceabi-gcc --version

工具链目录名可能略有不同，用 ls /opt/sdk/tools/linux/toolchains/ 查看实际名称。

如果能看到 gcc 版本号，说明 32 位库安装成功，工具链可以正常运行。

八、编译 SDK 验证环境

8.1 加载工具链环境变量

cd /opt/sdk
source build/env.sh

每次新开容器终端都要执行一次这步，否则找不到交叉编译器。

8.2 选择板级配置（lunch）

./run.sh lunch

会出现交互式选择：

========================================
 Select Board Configuration
========================================

Board:
 1. ShiMetaPi-Pico-G1-128M_DDR(GK7206V11A)
 2. ShiMetaPi-Pico-G1-256M_DDR(GK7206V12A)

Select board [1-2]:

• 128MB DDR 的板子选 1（GK7206V11A）

• 256MB DDR 的板子选 2（GK7206V12A）

然后选择内核版本：

Kernel:
 1. linux-5.10
 2. linux-4.9

Select kernel [1-2]:

推荐选 1（linux-5.10），较新。

选择完成后会写入 cfg.mk 文件。

8.3 一键编译

./run.sh all -j

• all：编译全部组件（uboot + kernel + rootfs + driver + media + sample + mcu）

• -j：自动使用所有 CPU 核心并行编译

• 也可以指定核心数，如 -j4

首次全量编译耗时较长（20~60 分钟，取决于 CPU 和内存），后续修改代码后增量编译只需几分钟。

8.4 编译产物

编译成功后，固件在：

/opt/sdk/out/xm7206v11a/image/    # 128MB 版本
/opt/sdk/out/xm7206v12a/image/    # 256MB 版本

因为 SDK 目录是挂载的，在 WSL2 里也能直接访问：

# 在 WSL2 终端（不是容器里）查看编译产物
ls ~/NightEyes/sdk/out/xm7206v12a/image/

九、日常使用流程

9.1 每天开机后怎么开始

1. 启动 Docker Desktop（等左下角图标变绿）
2. 打开 Ubuntu 终端
3. 执行启动容器命令（建议做成别名，见附录 B）
4. source build/env.sh
5. 开始编译或改代码

9.2 修改代码后怎么编译

用 VS Code 连接 WSL2 编辑代码（装 "WSL" 扩展，左下角点 >< 连接到 Ubuntu），改完代码后在容器终端里执行：

# 只编译内核
./run.sh kernel -j

# 只编译 rootfs
./run.sh rootfs

# 只编译示例应用
./run.sh sample

# 全量重新编译
./run.sh all -j

9.3 把固件传到板子

固件在 WSL2 的 ~/NightEyes/sdk/out/.../image/ 目录下，有两种方式传到板子：

方式一：Windows 侧烧写工具（推荐）

在 Windows 文件管理器地址栏输入：

\\wsl$\Ubuntu\home\你的用户名\sdk\out\

可以直接访问 WSL2 里的文件，把固件复制到 Windows，用官方烧写工具烧录。

方式二：scp 网络传输

板子和电脑在同一局域网时，在容器里执行：

scp out/xm7206v12a/image/*.bin root@<板子IP>:/tmp/

WSL2 默认 NAT，板子主动连容器需要做端口转发；但容器主动连板子（scp 到板子）通常没问题。

十、常见问题排查

Q1：docker build 时 apt update 失败 / 404 Not Found

典型报错：

Err:5 http://mirrors.aliyun.com/ubuntu-old-releases bionic Release
  404  Not Found [IP: 59.80.28.226 80]
E: The repository '... bionic Release' does not have a Release file.

真实原因：Dockerfile 里的 apt 源地址写错了，不是"18.04 已 EOL"。

• ubuntu-old-releases 这个目录在阿里云、清华、中科大、华为云等国内镜像上都不存在（全部 404）。

• old-releases.ubuntu.com（官方 EOL 归档）目前也没有 bionic，18.04 还没被搬进去。

• bionic 至今仍在 Ubuntu 正源里，直接指向镜像的 /ubuntu 即可。

正确写法（附录 A 的 Dockerfile 已修正为此版本）：

RUN sed -i 's|http://archive.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g; s|http://security.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g' /etc/apt/sources.list

动手前先验证源是否可用（宿主机或 WSL2 里执行，返回 200 才算通）：

curl -o /dev/null -w '%{http_code}\n' http://mirrors.aliyun.com/ubuntu/dists/bionic/Release
curl -o /dev/null -w '%{http_code}\n' http://mirrors.aliyun.com/ubuntu/dists/bionic-security/Release
# 32 位包索引也要在（dpkg --add-architecture i386 后 apt 会拉这个）
curl -o /dev/null -w '%{http_code}\n' http://mirrors.aliyun.com/ubuntu/dists/bionic/main/binary-i386/Packages.gz

备选镜像（把上面 sed 里的 mirrors.aliyun.com/ubuntu 换掉即可）：

将来 bionic 真的被移入 old-releases（届时官方会正式公告），再把地址改成 http://old-releases.ubuntu.com/ubuntu。

Q2：编译报错 arm-gcc12.2.0-linux-uclibceabi-gcc: command not found

原因：没有执行 source build/env.sh，或者工具链是 32 位但容器没装 32 位库。

解决：

1. 先执行 source build/env.sh

2. 验证 32 位库：dpkg -l | grep libc6:i386，有输出说明装了

3. 如果没装，重新构建镜像（Dockerfile 里已包含 i386 步骤）

Q3：编译极慢 / 卡死 / 内存不足

原因：WSL2 分配的内存或 CPU 不够。

解决：

1. 编辑 C:\Users\你的用户名\.wslconfig，调大 memory 和 processors

2. wsl --shutdown 重启 WSL

3. 编译时减少并行数：./run.sh all -j2（用 2 核编译，更稳）

Q4：我把 SDK 放 /mnt/c 下了，编译报错

原因：/mnt/c 是 Windows NTFS 文件系统，不支持 Linux 符号链接和权限，SDK 编译会失败。

解决：把 SDK 移到 WSL2 的 Linux 文件系统：

# 在 WSL2 里执行
mv /mnt/c/Users/.../sdk ~/NightEyes/sdk

Q5：Docker Desktop 启动报错 "WSL 2 installation is incomplete"

原因：没装 WSL2 内核更新包。

解决：下载安装 https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi ，然后重启 Docker Desktop。

Q6：容器里看不到 /opt/sdk 里的文件

原因：挂载路径不对，或者 SDK 目录不存在。

解决：

1. 在 WSL2 里确认 ls ~/NightEyes/sdk/run.sh 有输出

2. 启动容器时 -v 参数的路径要写对：-v ~/NightEyes/sdk:/opt/sdk

3. 注意 ~ 在 docker run 里会被 WSL2 的 shell 展开，确保在 WSL2 终端执行，不是 Windows PowerShell

Q7：Store 里搜不到 Ubuntu 22.04

原因：微软已将旧版独立应用下架，只保留通用 "Ubuntu"。

解决：直接装第一个通用 "Ubuntu" 应用即可，它是最新 LTS（当前 26.04）。作为 Docker 宿主，和 22.04 没有任何区别。

Q8：eudev 编译失败 / mtd-utils 编译失败

原因：缺少 gperf 或 automake 版本不对。

解决：确认 Dockerfile 里安装了 gperf 和 automake。Ubuntu 18.04 源里的版本正好是 gperf 3.1 和 automake 1.15.1，满足要求。

Q9：第三方库编译报错 / 链接失败

原因：缺少 /etc/ld.so.preload 空文件。

解决：Dockerfile 里已包含 RUN touch /etc/ld.so.preload，确认构建镜像时这步没报错。

附录 A：Dockerfile 完整代码

# ============================================================
# ShiMetaPi-Pico-G1 编译环境 Dockerfile
# 基础系统：Ubuntu 18.04（与官方文档编译环境一致）
# 包含：所有依赖包、32位库、gperf、automake、mtd-utils依赖、网络组件
# ============================================================

FROM ubuntu:18.04

# 避免 apt 安装时弹出交互对话框
ENV DEBIAN_FRONTEND=noninteractive

# ------------------------------------------------------------
# 1. 替换 apt 源为阿里云镜像（18.04 仍在 Ubuntu 正源，换镜像仅为加速）
#    注意：不要写成 /ubuntu-old-releases，该路径在阿里云/清华等镜像上不存在，
#    old-releases.ubuntu.com 目前也没有 bionic，写错会直接 404 构建失败
# ------------------------------------------------------------
RUN sed -i 's|http://archive.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g; s|http://security.ubuntu.com/ubuntu|http://mirrors.aliyun.com/ubuntu|g' /etc/apt/sources.list

# ------------------------------------------------------------
# 2. 启用 32 位架构（SDK 交叉工具链是 32 位程序）
# ------------------------------------------------------------
RUN dpkg --add-architecture i386 && apt-get update

# ------------------------------------------------------------
# 3. 安装基础依赖包（对应文档 2.3 步骤 2）
# ------------------------------------------------------------
RUN apt-get install -y \
    make \
    g++ \
    zlib1g-dev \
    libncurses5-dev \
    ncurses-term \
    libncursesw5-dev \
    texinfo \
    texlive \
    gawk \
    libssl-dev \
    openssl \
    bc \
    bison \
    flex \
    libelf-dev \
    liblzma-dev \
    liblz4-tool \
    libzstd-dev \
    device-tree-compiler \
    fakeroot \
    build-essential

# ------------------------------------------------------------
# 4. 安装 32 位兼容库（对应文档 2.3 步骤 2 中的 i386 包）
# ------------------------------------------------------------
RUN apt-get install -y \
    libc6:i386 \
    lib32z1 \
    lib32stdc++6 \
    u-boot-tools:i386

# ------------------------------------------------------------
# 5. 安装 gperf 工具（对应文档 2.3 步骤 4）
# Ubuntu 18.04 源里 gperf 版本就是 3.1，无需手动编译
# ------------------------------------------------------------
RUN apt-get install -y gperf

# ------------------------------------------------------------
# 6. 安装 mtd-utils 依赖库（对应文档 2.3 步骤 5）
# ------------------------------------------------------------
RUN apt-get install -y \
    zlib1g-dev \
    liblzo2-dev \
    uuid-dev \
    pkg-config

# 设置 pkg-config 搜索路径（显式列出 64/32 位 multiarch 路径）
# 不要写成 "...:${PKG_CONFIG_PATH}"，此时变量未定义，docker build 会报 UndefinedVar 警告
ENV PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/lib/i386-linux-gnu/pkgconfig"

# ------------------------------------------------------------
# 7. 安装 automake 1.15.1（对应文档 2.3 步骤 6）
# Ubuntu 18.04 源里 automake 版本就是 1.15.1，无需手动编译
# ------------------------------------------------------------
RUN apt-get install -y automake autoconf libtool

# ------------------------------------------------------------
# 8. 安装网络组件（对应文档 2.2：NFS / Samba / SSH）
# ------------------------------------------------------------
RUN apt-get install -y \
    nfs-kernel-server \
    samba \
    ssh \
    rsync

# ------------------------------------------------------------
# 9. 安装常用工具
# ------------------------------------------------------------
RUN apt-get install -y \
    git \
    wget \
    curl \
    vim \
    sudo \
    net-tools \
    iputils-ping \
    locales

# ------------------------------------------------------------
# 10. 创建 /etc/ld.so.preload 空文件（对应文档 2.3 步骤 3）
# 解决 64 位系统上某些第三方库编译失败的问题
# ------------------------------------------------------------
RUN touch /etc/ld.so.preload

# ------------------------------------------------------------
# 11. 将默认 shell 从 dash 切换为 bash（对应文档 2.3 步骤 1）
# ------------------------------------------------------------
RUN echo "dash dash/sh boolean false" | debconf-set-selections && \
    dpkg-reconfigure -p critical dash

# ------------------------------------------------------------
# 12. 配置中文 locale（避免中文文件名/路径乱码）
# ------------------------------------------------------------
RUN locale-gen en_US.UTF-8 && \
    locale-gen zh_CN.UTF-8
ENV LANG=en_US.UTF-8
ENV LANGUAGE=en_US:en
ENV LC_ALL=en_US.UTF-8

# ------------------------------------------------------------
# 13. 创建 SDK 挂载目录
# ------------------------------------------------------------
RUN mkdir -p /opt/sdk
WORKDIR /opt/sdk

# ------------------------------------------------------------
# 14. 清理 apt 缓存，减小镜像体积
# ------------------------------------------------------------
RUN apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# 默认启动 bash
CMD ["bash"]

附录 B：常用命令速查

WSL2 相关（Windows PowerShell 执行）

# 查看已安装的 WSL 发行版和版本
wsl -l -v

# 关闭所有 WSL（改完 .wslconfig 后执行）
wsl --shutdown

# 进入 Ubuntu
wsl -d Ubuntu

Docker 相关（WSL2 Ubuntu 终端执行）

# 构建镜像（在镜像自己的目录里）
cd ~/docker-build-env/pico-g1-1804
docker build -t pico-g1-build-env:18.04 .

# 也可以站在父目录用 -f 指定
# cd ~/docker-build-env && docker build -f pico-g1-1804/Dockerfile -t pico-g1-build-env:18.04 .

# 启动编译容器（最常用）
docker run -it --rm -v ~/NightEyes/sdk:/opt/sdk -w /opt/sdk pico-g1-build-env:18.04 bash

# 查看本地镜像
docker images

# 删除镜像
docker rmi pico-g1-build-env:18.04

# 查看正在运行的容器
docker ps

# 查看所有容器（包括已退出的）
docker ps -a

设置命令别名（推荐）

在 WSL2 的 ~/.bashrc 末尾加一行，以后输入 pico 就能直接启动编译容器：

echo "alias pico='docker run -it --rm -v ~/NightEyes/sdk:/opt/sdk -w /opt/sdk pico-g1-build-env:18.04 bash'" >> ~/.bashrc
source ~/.bashrc

以后只要输入 pico 就进入编译容器了。

SDK 编译相关（容器内执行）

# 加载工具链环境（每次进容器必做）
source build/env.sh

# 选择板级配置
./run.sh lunch

# 查看当前配置
./run.sh info

# 全量编译
./run.sh all -j

# 单独编译各组件
./run.sh uboot -j     # 编译 U-Boot
./run.sh kernel -j    # 编译内核
./run.sh rootfs       # 编译 rootfs
./run.sh sample       # 编译示例应用
./run.sh mcu          # 编译 MCU 固件

# 清理
./run.sh clean all    # 清理全部
./run.sh clean kernel # 只清理内核

# 检查编译环境
./run.sh check

版本记录

教程版本：v1.9 ｜ 最后更新：2026-10-20 ｜ 适用 SDK：ShiMetaPi-Pico-G1 SDK V1.0.0（gitee 仓库 master 分支）

v1.9 — Dockerfile 改为子目录隔离 ~/docker-build-env/pico-g1-1804/Dockerfile（文件名仍用默认 Dockerfile，说明为何不改名、改名的代价）；新增 6.5「多项目 / 多镜像共存」（目录树、三条规则、-f 使用场景、镜像过滤与清理）；6.3 与附录 B 的构建命令同步新路径。

v1.8 — 修复 docker build 在 [ 3/16] apt-get update 处 404 失败：apt 源由不存在的 mirrors.aliyun.com/ubuntu-old-releases 改为正源 mirrors.aliyun.com/ubuntu（已实测 bionic / bionic-security / binary-i386 索引均 200；各国内镜像均无 ubuntu-old-releases 目录，old-releases.ubuntu.com 目前也没有 bionic）；同步修正 6.2 步骤表说明、PKG_CONFIG_PATH 未定义变量导致的 UndefinedVar 警告，并重写 Q1 排查流程（附源可用性自检命令与镜像备选表）。

v1.7 — 修正 5.1 克隆命令：改为 mkdir -p ~/NightEyes && git clone <url> ~/NightEyes/sdk，使 SDK 真正落在 ~/NightEyes/sdk（原命令会落到 ~/sdk，与下文路径不符）；5.2 增加 pwd 校验与「多套一层」的修复命令。

v1.6 — SDK 路径统一改为 ~/NightEyes/sdk；新增第二章 2.5「用 Xshell 连接 WSL」（含 openssh-server 安装、localhost 连接、hostname -I 排查）；新增第四章 4.5「WSL 版本过旧的处理」（wsl --update 及手动下载 GitHub msi 包方案）。
v1.5 — 修复 WSL 移动流程：import 后必须先验证启动成功再删 tar，新增 import 损坏导致"未发现用户"的重装方案。
v1.4 — WSL 移动章节新增「移动后 Ubuntu 闪退的修复」排查流程。
v1.3 — 第三章新增「（可选）将 WSL 移动到非系统盘」小节。
v1.2 — 同步实际安装环境，WSL 宿主为 Ubuntu 26.04.1 LTS。
v1.1 — WSL 宿主从 Ubuntu 22.04 改为 Store 通用 Ubuntu，新增 Store 搜不到旧版 Ubuntu 的 FAQ。