OpenWrt 自编译编译记录

前几年刚搞家庭网络，捡垃圾捡来一个 TP-Link TL-WDR4310 v1 路由器，这玩意可以刷 OpenWrt。

后来随着 OpenWrt 大版本更新，固件也越来越大，TL-WDR4310 本身自带的存储空间已经不够用了，于是给它物理扩容到 16MB。

不过这样硬改之后，官方的固件他识别不到 16MB，需要自己编译固件。

本文最后更新于：2025-12-10

准备环境

基础环境镜像

构建镜像

docker build -t build-base - <<\EOF
FROM debian:13

RUN <<EOT
    sed -e 's|deb.debian.org|mirrors.aliyun.com|g' -i.bak /etc/apt/sources.list.d/debian.sources
    apt update
    apt install -y sudo bash-completion command-not-found procps vim wget curl net-tools git subversion
    apt update
    apt clean && rm -rf /var/lib/apt/lists/*
EOT

ENV TZ=Asia/Shanghai
RUN <<EOT
    useradd --create-home --uid 1000 --groups users,sudo --shell /bin/bash user
    echo "user:1111" | chpasswd
    ln -snf /usr/share/zoneinfo/${TZ} /etc/localtime
    echo "${TZ}" > /etc/timezone
EOT

COPY <<EOT /etc/profile.d/aliases.sh
alias ll='ls -lh -F --color=auto --time-style=long-iso'
alias la='ls -lhA -F --color=auto --time-style=long-iso'
alias lt='ls -lht -F --color=auto --time-style=long-iso'
alias lat='ls -lhAt -F --color=auto --time-style=long-iso'
EOT

USER user
WORKDIR /home/user/
EOF

1. 使用管道输入 Dockerfile 内容，自定义镜像标签为 build-base。
   https://docs.docker.com/build/building/context/#how-to-build-without-a-context
2. 使用 Here-Documents 运行 RUN、COPY 指令，注意如果是在 Dockerfile 中使用需要保证文件换行符是 LF。
   https://docs.docker.com/reference/dockerfile/#here-documents
3. 备用镜像站:
   - mirrors.aliyun.com
   - mirrors.cernet.edu.cn
   - mirrors.tuna.tsinghua.edu.cn

使用镜像

docker run -ti --rm build-base bash -l

1. 默认为 non-login 的 shell，需要使用 ‘-l’ 参数登录以生效 /etc/profile 配置。
   https://github.com/gliderlabs/docker-alpine/issues/443

构建专用镜像

docker build -t build-openwrt - <<\EOF
FROM build-base
USER root

RUN <<EOT
    apt update
	apt install -y build-essential clang flex bison g++ gawk
	apt install -y gcc-multilib g++-multilib gettext git libncurses5-dev libssl-dev
	apt install -y python3-setuptools rsync swig unzip zlib1g-dev file wget
    apt clean &&  rm -rf /var/lib/apt/lists/*
EOT

USER user
EOF

下载源码

mkdir -p ~/projects/
git clone https://github.com/openwrt/openwrt.git -b v24.10.4 openwrt

构建固件

启动容器

docker run -ti --rm --privileged -v ~/projects/:/projects/ build-openwrt bash -l

初始化依赖

cd /projects/openwrt/

./scripts/feeds update -a
./scripts/feeds install -a

清理构建历史(可选)

cd /projects/openwrt/

# rm -rf bin build_dir
make clean
# rm -rf bin build_dir staging_dir toolchain logs
make dirclean
# 删除以上所有文件 ， dl 和 .config
make distclean

初始化编译选项

cd /projects/openwrt/

wget https://downloads.openwrt.org/releases/24.10.4/targets/ath79/generic/config.buildinfo -O .config

自定义编译选项

cd /projects/openwrt/

make menuconfig

启动可视化配置后，可按需配置构建项目：

# 配置基本系统
- Base system -> apk-mbedtls
* Base system -> apk-openssl
* Base system -> ca-certificates
* Base system -> dnsmasq
* Base system -> dnsmasq-dhcpv6
* Base system -> opkg

# 系统扩展配置
* Image configuration -> Use preinit IP configuration as default LAN IP
* Image configuration -> Preinit configuration options
  Image configuration -> IP address for preinit network messages
    192.168.10.1
  Image configuration -> Netmask for preinit network messages
    255.255.255.0
  Image configuration -> Broadcast address for preinit network messages
    192.168.10.255
* Image configuration -> Version configuration options
  Image configuration -> Version configuration options -> Release repository
    https://mirrors.tuna.tsinghua.edu.cn/openwrt/releases/24.10.4

# 配置 LuCI 功能
- LuCI -> Collections -> luci-ssl
* LuCI -> Collections -> luci-ssl-openssl
* LuCI -> Modules -> Translations -> Simplified Chinese (zh_Hans)
* LuCI -> Applications -> luci-app-dcwpad
* LuCI -> Applications -> luci-app-ddns
* LuCI -> Applications -> luci-app-wol

# 启用 DDNS 服务
* Network -> IP Addresses and Names -> ddns-scripts
* Network -> IP Addresses and Names -> ddns-scripts-aliyun
* Network -> IP Addresses and Names -> ddns-scripts-cloudflare
* Network -> IP Addresses and Names -> ddns-scripts-dnspod
* Network -> IP Addresses and Names -> ddns-scripts-dnspod-v3

# 启用 ISC DHCP 服务组件（isc-dhcp-xxxx-ipv6 包含 isc-dhcp-xxxx-ipv4 的能力）
* Network -> IP Addresses and Names -> isc-dhcp-client-ipv6
* Network -> IP Addresses and Names -> isc-dhcp-omshell-ipv6
* Network -> IP Addresses and Names -> isc-dhcp-relay-ipv6
* Network -> IP Addresses and Names -> isc-dhcp-server-ipv6

# 启用 WPAD, 支持企业无线网
* Network -> WirelessAPD -> wpad
- Network -> WirelessAPD -> wpad-basic-mbedtls
M Network -> WirelessAPD -> wpad-basic-openssl

# 启用 openssh / sftp
* Network -> SSH -> openssh-server
* Network -> SSH -> openssh-sftp-server

# 启用 openssl 工具集
* Utilities -> openssl-util

https://openwrt.org/packages/index/start

适配硬改存储空间

修改 target/linux/ath79/dts/ar9344_tplink_tl-wdrxxxx.dtsi 和 target/linux/ath79/image/generic-tp-link.mk 适配硬改的存储空间区域:

git apply << \EOF
diff --git a/target/linux/ath79/dts/ar9344_tplink_tl-wdrxxxx.dtsi b/target/linux/ath79/dts/ar9344_tplink_tl-wdrxxxx.dtsi
index 94bfef57f6..0b13038fc0 100644
--- a/target/linux/ath79/dts/ar9344_tplink_tl-wdrxxxx.dtsi
+++ b/target/linux/ath79/dts/ar9344_tplink_tl-wdrxxxx.dtsi
@@ -100,12 +100,12 @@
                        partition@20000 {
                                compatible = "tplink,firmware";
                                label = "firmware";
-                               reg = <0x020000 0x7d0000>;
+                               reg = <0x020000 0xfd0000>;
                        };

                        partition@7f0000 {
                                label = "art";
-                               reg = <0x7f0000 0x010000>;
+                               reg = <0xff0000 0x010000>;
                                read-only;

                                nvmem-layout {
diff --git a/target/linux/ath79/image/generic-tp-link.mk b/target/linux/ath79/image/generic-tp-link.mk
index b5b2ec8c7c..7ff2117edf 100644
--- a/target/linux/ath79/image/generic-tp-link.mk
+++ b/target/linux/ath79/image/generic-tp-link.mk
@@ -668,7 +668,7 @@ endef
 TARGET_DEVICES += tplink_tl-wdr4300-v1-il

 define Device/tplink_tl-wdr4310-v1
-  $(Device/tplink-8mlzma)
+  $(Device/tplink-16mlzma)
   SOC := ar9344
   DEVICE_MODEL := TL-WDR4310
   DEVICE_VARIANT := v1
EOF

下载构建中间件

cd /projects/openwrt/

# 访问 Github 等外网网站，如有必要可配置代理
export http_proxy=http://192.168.8.11:20170
export https_proxy=http://192.168.8.11:20170

make download -j$(nproc)

启动构建

cd /projects/openwrt/

# 全量编译
make -j$(nproc)

# 单独构建 ipk 包
make package/[包名]/compile

构建产物

user@47494c359781:/projects/openwrt$ ls -lh ./bin/targets/ath79/generic/
total 421M
-rw-r--r-- 1 user user 4.4K Dec  9 22:13 config.buildinfo
-rw-r--r-- 1 user user  395 Dec  9 22:13 feeds.buildinfo
-rw-r--r-- 1 user user  89M Dec  9 22:24 kernel-debug.tar.zst
-rw-r--r-- 1 user user  47M Dec  9 22:04 llvm-bpf-18.1.7.Linux-x86_64.tar.zst
-rw-r--r-- 1 user user  11M Dec  9 22:25 openwrt-24.10.4-r28959-29397011cc-ath79-generic-tplink_tl-wdr4310-v1-initramfs-kernel.bin
-rw-r--r-- 1 user user  16M Dec  9 22:25 openwrt-24.10.4-r28959-29397011cc-ath79-generic-tplink_tl-wdr4310-v1-squashfs-factory.bin
-rw-r--r-- 1 user user  13M Dec  9 22:25 openwrt-24.10.4-r28959-29397011cc-ath79-generic-tplink_tl-wdr4310-v1-squashfs-sysupgrade.bin
-rw-r--r-- 1 user user  25K Dec  9 22:51 openwrt-24.10.4-r28959-29397011cc-ath79-generic-tplink_tl-wdr4310-v1.bom.cdx.json
-rw-r--r-- 1 user user 6.0K Dec  9 22:51 openwrt-24.10.4-r28959-29397011cc-ath79-generic-tplink_tl-wdr4310-v1.manifest
-rw-r--r-- 1 user user 205M Dec  9 22:52 openwrt-sdk-24.10.4-ath79-generic_gcc-13.3.0_musl.Linux-x86_64.tar.zst
-rw-r--r-- 1 user user  43M Dec  9 22:03 openwrt-toolchain-24.10.4-ath79-generic_gcc-13.3.0_musl.Linux-x86_64.tar.zst
drwxr-xr-x 3 user user  92K Dec  9 21:20 packages
-rw-r--r-- 1 user user   18 Dec  9 22:13 version.buildinfo

问题

报错 python3-distutils 不存在

• 现象

WARNING: Makefile 'package/feeds/packages/fail2ban/Makefile' has a dependency on 'python3-distutils', which does not exist
WARNING: Makefile 'package/feeds/packages/flent/Makefile' has a dependency on 'python3-distutils', which does not exist
WARNING: Makefile 'package/feeds/packages/onionshare-cli/Makefile' has a dependency on 'python3-pysocks', which does not exist
WARNING: Makefile 'package/feeds/packages/onionshare-cli/Makefile' has a dependency on 'python3-unidecode', which does not exist
WARNING: Makefile 'package/feeds/packages/python-babel/Makefile' has a dependency on 'python3-distutils', which does not exist
WARNING: Makefile 'package/feeds/packages/python-docker/Makefile' has a dependency on 'python3-distutils', which does not exist
WARNING: Makefile 'package/feeds/packages/python-incremental/Makefile' has a dependency on 'python3-distutils', which does not exist

• 原因

python3-distutils 这个包在 python3.12 以上版本没有了, 所以会报错.

• 解决
  参考: https://github.com/openwrt/packages/issues/27812

CMake 版本不匹配

• 现象

Not searching for unused variables given on the command line.
CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.31 or higher is required.  You are running version 3.30.5


-- Configuring incomplete, errors occurred!
make[3]: *** [Makefile:60: /projects/openwrt/build_dir/target-mips_24kc_musl/rpcd-mod-luci-20240305/.configured_68b329da9893e34099c7d8ad5cb9c940] Error 1
make[3]: Leaving directory '/projects/openwrt/feeds/luci/libs/rpcd-mod-luci'
time: package/feeds/luci/rpcd-mod-luci/compile#0.28#0.22#0.44
    ERROR: package/feeds/luci/rpcd-mod-luci failed to build.
make[2]: *** [package/Makefile:176: package/feeds/luci/rpcd-mod-luci/compile] Error 1
make[2]: Leaving directory '/projects/openwrt'
make[1]: *** [package/Makefile:170: /projects/openwrt/staging_dir/target-mips_24kc_musl/stamp/.package_compile] Error 2
make[1]: Leaving directory '/projects/openwrt'
make: *** [/projects/openwrt/include/toplevel.mk:233: world] Error 2

• 解决
  修改 ./feeds/luci/libs/rpcd-mod-luci/src/CMakeLists.txt、./feeds/luci/libs/rpcd-mod-rrdns/src/CMakeLists.txt 文件，修改其中的 cmake_minimum_required(VERSION 3.31) 为 cmake_minimum_required(VERSION 3.30)。

可以通过命令 grep -nR cmake_minimum_required ./feeds/luci/libs/ 批量查找。

找不到 opkg-key 文件

• 现象

cp: cannot stat '/projects/openwrt/staging_dir/target-mips_24kc_musl/root-ath79/usr/sbin/opkg-key': No such file or directory
make[3]: *** [Makefile:51: /projects/openwrt/bin/targets/ath79/generic/openwrt-imagebuilder-24.10.4-ath79-generic.Linux-x86_64.tar.zst] Error 1
make[3]: Leaving directory '/projects/openwrt/target/imagebuilder'
time: target/imagebuilder/install#0.12#0.24#0.37
    ERROR: target/imagebuilder failed to build.
make[2]: *** [target/Makefile:32: target/imagebuilder/install] Error 1
make[2]: Leaving directory '/projects/openwrt'
make[1]: *** [target/Makefile:26: /projects/openwrt/staging_dir/target-mips_24kc_musl/stamp/.target_install] Error 2
make[1]: Leaving directory '/projects/openwrt'
make: *** [/projects/openwrt/include/toplevel.mk:233: world] Error 2

• 解决

选中 Base system -> opkg 包。

参考

• https://openwrt.org/docs/guide-developer/toolchain/install-buildsystem
• https://openwrt.org/docs/guide-developer/toolchain/use-buildsystem
• https://zhuanlan.zhihu.com/p/65012947
• https://zhuanlan.zhihu.com/p/661462395