使用 Docker/WSL 编译 ImmortalWrt/OpenWrt

在本文开始前，务必确保你的网络已经附魔，如果没有，这里给你一个词：V2rayN，研究好了再回来这里。

其次，务必确保 OpenWrt 支持你的机型，在这里查：https://firmware-selector.openwrt.org/ ，比如我的是华硕小旋风 pro，英文代号是 ASUS TUF-AX4200

最后，务必了解清楚如何刷入你的机型，以及如何恢复到原厂固件，以及如何救砖。

刷机有风险，玩机需谨慎！！！

〇、前言

本教程不使用 VMWare 等虚拟机软件，而是在 Docker 容器上编译 ImmortalWrt，全程使用终端进行操作，可能需要少许的 Linux 的基础，比如掌握 ls cd 等基础命令以及对 Docker 有基本的认识。

不使用 Docker 而直接使用 WSL（Windows Subsystem for Linux）的操作是差不多的。

温馨提示：从这里开始，请使用魔法上网。

一、部署 Docker Desktop 或 WSL

方式一：Docker 部署

官网下载：https://www.docker.com/products/docker-desktop/，看不懂英文的，直接点这里下载

然后按照教程来（懒得写了 (￣o￣) . z Z ）：https://blog.csdn.net/Natsuago/article/details/145588600

方式二：WSL 部署

# 列出可用的发行版
wsl --list --online

# 安装 Ubuntu 24.04
# wsl --install Ubuntu-24.04 --name Ubutnu_immortalwrt

# 进入 Ubuntu 子系统
wsl -d Ubutnu_immortalwrt

按照提示添加账户，设置密码即可进入。

二、部署 Linux 容器

到这里，你应该已经安装并启动 Docker 程序界面了。直接使用 WSL 的可跳转到第二步更换软件源。

1、安装 Linux 容器

打开 Windows 终端：（右键开始菜单，选择终端管理员），拉取 Ubuntu 24.04版本的镜像

docker pull ubuntu:24.04

部署容器并进入其终端（直接在镜像界面上点击运行容器是运行不起来的）

docker run -it --name ubuntu_for_openwrt ubuntu:24.04 /bin/bash
  # -it 创建一个交互式终端会话，让你能够在 Windows 终端上操控容器内终端
  # --name 容器名字
  # /bin/bash 启动一个 bash 终端

2、更换软件源

虽然已经给网络附魔了，但是准备编译环境时还需要下载大量的软件包。

安装文件编辑软件 nano （比 vi 好用，因为可以复制粘贴）与验证 SSL 证书合法性的软件包 ca-certificates（必须安装，不然换源后无法使用）

apt update   # 更新软件列表
apt install nano ca-certificates  # 安装软件

这里使用清华镜像站，里面有详细说明

Ubuntu 24.04 以上版本的使用 DEB822 格式而不是传统格式，勾选强制安全更新使用镜像（因为不是生产环境，所以勾选没问题，能加快软件包安装速度）

1、打开软件源列表

nano /etc/apt/sources.list.d/ubuntu.sources

2、注释原来的两段，并将清华镜像站的两段复制进去

3、保存： Ctrl + O，回车

4、回到终端：Ctrl + X

三、配置编译环境

根据 ImmortalWrt Github 中的指导进行配置，但是不要加 sudo（已经拥有 root 权限，且没有安装 sudo），注意方法1方法2也同样执行，中途要选择地区和语言就选 5（Asia）和 69（Shanghai）

# 更新软件源
apt update -y
# 更新所有软件包
apt full-upgrade -y
# 安装必要环境
apt install -y ack antlr3 asciidoc autoconf automake autopoint binutils bison build-essential \
  bzip2 ccache clang cmake cpio curl device-tree-compiler ecj fastjar flex gawk gettext gcc-multilib \
  g++-multilib git gnutls-dev gperf haveged help2man intltool lib32gcc-s1 libc6-dev-i386 libelf-dev \
  libglib2.0-dev libgmp3-dev libltdl-dev libmpc-dev libmpfr-dev libncurses-dev libpython3-dev \
  libreadline-dev libssl-dev libtool libyaml-dev libz-dev lld llvm lrzsz mkisofs msmtp nano \
  ninja-build p7zip p7zip-full patch pkgconf python3 python3-pip python3-ply python3-docutils \
  python3-pyelftools qemu-utils re2c rsync scons squashfs-tools subversion swig texinfo uglifyjs \
  upx-ucl unzip vim wget xmlto xxd zlib1g-dev zstd

# 执行官方安装脚本
bash -c 'bash <(curl -s https://build-scripts.immortalwrt.org/init_build_environment.sh)'

A few moments later...

官方安装脚本执行成功后，你应该能看到结尾显示 [SUCCESS] All dependencies have been installed. 如果没有，那就重新执行脚本，出问题的基本上是网络问题。

强制使用 root 权限编译，GitHub 上的 Note 提到不可使用 root 进行编译，但是我们现在就是 root，因此加一个环境变量（必须加，不然编译检查阶段就不通过）（为什么官方不建议你去用 root 编译呢，是因为怕把你系统搞崩了，但是我们在 Docker 或虚拟环境上编译就没什么关系了）

export FORCE_UNSAFE_CONFIGURE=1

（可选）到这里，我们的编译环境就准备好了，再打开一个 Windows 终端（不要在当前 Docker 容器的终端执行），执行下面的命令将当前容器保存为一个镜像，下面如果搞崩了就不用重新配置环境了，运行保存好的镜像就行。

# 查看正在运行的容器ID（确认目标容器）
docker ps

# 创建镜像快照（保留文件系统层）
docker commit <容器ID> ubuntu-backup:v1

# 如果需要运行此镜像
# docker run -it -name <自定义容器名> ubuntu-backup:v1 /bin/bash

四、拉取官方源码

拉取官方源码

git clone -b <branch> --single-branch --filter=blob:none https://github.com/immortalwrt/immortalwrt

上面的 -b 参数指的是分支，目前最新的分支是 openwrt-24.10 ，在GitHub 界面的 Code 中查看。（别手贱选 master 或 main ，这些开发分支什么也没有配置，包括 luci ）

更新软件包列表

# 进入源码目录
cd immortalwrt
# 更新软件列表
./scripts/feeds update -a
# 建立软件包链接（快捷方式），编译时需要这个软件包就会自动下载
./scripts/feeds install -a

五、添加第三方软件

虽然 ImmortalWrt 中的源提供的软件包足够用了，但是还是有不少需要我们去手动添加才有的，下面我就以 OpenClash、MosDNS、Partexp（用于硬路由上的 U盘扩容）为例，说明如何添加第三方软件。

基本上就是把第三方包添加到源码中的 package 目录下即可，该操作应该在执行完上面的 ./scripts/feeds install -a 之后。

OpenClash（仓库已包含，无需手动添加）

GitHub 网站：https://github.com/vernesong/OpenClash/tree/master

## 下载OpenClash，不推荐用 git clone，会把整个仓库拉下来，非常大
wget https://github.com/vernesong/OpenClash/archive/master.zip

## 解压
unzip master.zip

## 复制OpenClash软件包到OpenWrt
cp -r OpenClash-master/luci-app-openclash ./package

## 删除下载文件
rm -rf master.zip
rm -rf OpenClash-master

MosDNS —— DNS 分流软件

GitHub 网站：https://github.com/sbwml/luci-app-mosdns

MosDNS 的添加稍微复杂了一点，因为依赖其自定义的软件包 V2dat

rm -rf feeds/packages/lang/golang
git clone https://github.com/sbwml/packages_lang_golang -b 24.x feeds/packages/lang/golang # 注意 -b 参数分支的选择
git clone https://github.com/sbwml/luci-app-mosdns -b v5 package/mosdns
git clone https://github.com/sbwml/v2ray-geodata package/v2ray-geodata

Partexp —— 一键分区扩容挂载工具

GitHub 网站：https://github.com/sirpdboy/luci-app-partexp

git clone https://github.com/sirpdboy/luci-app-partexp.git package/luci-app-partexp

六、配置编译选项

进入编译配置菜单，自定义编译

make menuconfig

1、选择目标机型（以小旋风 pro 为例）

目标平台 Target System：MediaTek ARM

平台子选项 Subtarget：Filogic 8x0 (MT798x)

目标机型 Target Profile：ASUS TUF-AX4200

2、选择软件包（按需选择，某些软件包 ImmortalWrt 含有，而 OpenWrt 没有）

进入 Luci -> Applications

Collections
- luci （ Web 界面，ImmortalWrt 默认添加，OpenWrt 默认没有）
Modules -> Translations
- Chinese Simplified (zh_Hans)（中文包，ImmortalWrt 默认添加，OpenWrt 默认没有）
Applications
- luci-app-argon-config（argon 主题设置）
- luci-app-autoreboot （自动重启设置）
- luci-app-cpufreq（设置路由器的 CPU 性能模式）
- luci-app-ddns-go（动态域名解析）
- luci-app-mosdns（第三方软件）
- luci-app-openclash（小猫咪）
- luci-app-partexp（第三方软件）
- luci-app-ramfree（内存释放）
- luci-app-uhttpd（Web 服务器设置界面）
- luci-app-upnp（UPNP）
- luci-app-usb3disable（关闭 USB3，避免干扰 2.4GHz WiFi）
- luci-app-wifischedule（WiFi 定时）
- luci-app-wol（网络唤醒）
Themes
- luci-theme-argon（argon 主题）
添加额外的系统模块
- 内存压缩 ZRAM
  - Base system -> zram-swap
  - Kernel modules -> Other modules -> kmod-zram（添加后更改压缩算法，推荐 lz4（列表中从上往下压缩率依次增大，对CPU的负担也依次加大））

3、保存配置

按左右方向键到 <save>，点击保存配置

七、编译

先多线程下载好所需的软件包（这一点很重要），免得编译的时候报错。然后再编译，如果编译报错，取消 -j4 多线程参数，然后再单线程编译，找出错误所在。（编译过程可能持续 3~6 个小时，稍安勿躁）


# 下载所需文件
make download V=s -j $(nproc) # V=s 输出日志，-j 启用多线程

# 启动编译
make V=s -j $(nproc)

如果编译顺利没有出错，那么恭喜！！！你已经学会了如何使用 Docker 编译 Openwrt。

编译完成后的固件在 ImmortalWrt 下的 /bin/targets 目录下，利用 ls 和 cd 命令找到生成的固件，比如我的小旋风 pro ，其路径为 /bin/targets/mediatek/filogic ，固件文件名为 immortalwrt-mediatek-filogic-asus_tuf-ax4200-squashfs-sysupgrade.bin

八、导出固件文件

编译完成后，需要从 Docker 容器中导出固件到 Windows 中。

# 查看编译 Openwrt 的容器，获取容器ID （如abcd1234）
docker ps

# 复制固件到 C 盘
docker cp abcd1234:/immortalwrt/bin/targets/mediatek/filogic/immortalwrt-mediatek-filogic-asus_tuf-ax4200-squashfs-sysupgrade.bin C:\

使用 WSL 的打开文件资源管理器在子系统文件夹的 /root/ 下打开相同路径即可看到固件（如果遇到权限问题请查看下方解决方案）。

至此，结束。

我遇到的问题

国行小旋风pro 的适配问题

国行版本的小旋风代号为 AX4200q，并不是国际版的 AX4200，对比国际版增加了一个 2.5G 的 Lan 口。需要在编译之前手动修改 dts 文件才能使用这个额外的 2.5G 口。

论坛中提到的修改方案：https://forum.openwrt.org/t/asus-tuf-ax4200-support/155738/415

对应的 dts 文件存放在 ImmortalWrt 项目下的：/target/linux/mediatek/dts/mt7986a-asus-tuf-ax4200.dts

添加论坛上提到的代码即可：

添加到 &mdio 节点的代码：

	phy5: phy@5 {
		compatible = "ethernet-phy-ieee802.3-c45";
		reg = <5>;

		mxl,led-drive-vdd;
		mxl,led-config = <0x03f0 0x0 0x0 0x0>;
	};

添加到 &switch 节点的代码：

		port@5 {
			reg = <5>;
			label = "lan5";
			phy-mode = "2500base-x";
			phy-handle = <&phy5>;
		};

如何进入已经在运行的容器终端

# 查询容器id
docker ps

# 进入容器终端
docker exec -it <容器id> /bin/bash

编译时 U-boot 报错，缺失 config.h 文件

错误提示：

make[4]: Entering directory '/usr/local/openwrt/build_dir/target-aarch64_cortex-a53_musl/u-boot-2025.01'
ENVP include/generated/env.in
<command-line>: fatal error: include/config.h: No such file or directory
compilation terminated.

排查：

进入 uboot 目录单独编译发现错误

# 单独编译 uboot
make package/boot/uboot-tools/compile V=s -j1

scripts/dtc/pylibfdt/libfdt_wrap.c:177:11: fatal error: Python.h: No such file or directory
177 | # include <Python.h>
| ^~~~~~~~~~
compilation terminated.

这个问题发生在我用 Debian 容器而不是 Ubuntu，这是因为缺失了 Python.h 头文件导致的（感谢 DeepSeek），重新安装 Python 软件包即可。

# 安装 Python 环境
apt install python3-dev

# 检查 Python.h 头文件是否存在
find /usr -name "Python.h" 2>/dev/null

# 重新编译
make V=s -j4

资源管理器访问 /root 没有权限

访问 WSL 子系统的 /root 文件夹时提示没有权限访问。

# 进入 WSL 子系统
wsl -d Ubuntu

# 提权
sudo -i

# 赋予其他用户只读权限（包括文件夹下的其他文件）
chmod 755 /root -R

更改访问权限后，即可在 Windows 的文件资源管理器访问 WSL 子系统的 /root 文件。