ImmortalWrt固件编译完整教程（基于OpenWrt）

项目地址：https://github.com/immortalwrt/immortalwrt

一、ImmortalWrt 在线构建（快速生成固件）

官方提供的网页在线构建工具为 ImageBuilder，其核心原理是借助官方服务器资源，使用预编译好的 SDK，通过选择所需软件包快速生成固件，无需本地编译源码。

1.1 在线构建特点

优点：构建速度快，操作简单，无需配置本地环境；

缺点：自定义程度有限，但可满足日常常用配置（如预安装插件、配置网口、防火墙等）。

1.2 官方在线编译地址

https://firmware-selector.immortalwrt.org

1.3 必备软件包（推荐添加）

curl luci-theme-argon luci-i18n-homeproxy-zh-cn luci-i18n-ttyd-zh-cn luci-i18n-diskman-zh-cn luci-i18n-filemanager-zh-cn luci-i18n-package-manager-zh-cn luci-i18n-firewall-zh-cn

说明：安装插件包时，系统会自动下载该插件所需的依赖软件，因此只需添加对应插件的汉化包即可。

ImmortalWrt 软件包查询（需替换实际版本和设备架构）：https://downloads.immortalwrt.org/releases/24.10.4/packages/x86_64/luci/index.json

1.4 初始化构建脚本（自定义配置）

脚本说明：需修改的配置项请去掉对应注释（删除开头的 #），未修改的项保持默认即可。

#!/bin/sh

exec >/tmp/setup.log 2>&1
###########################################################
自 定 义 配 置 区 域
###########################################################
系统后台密码（为空则不修改）
root_password="admin"
LAN 的 IPv4 地址（也是后台地址，例如 192.168.2.1）
lan_ip_address="192.168.2.1"
LAN 的子网掩码（例如 255.255.255.0）
lan_netmask="255.255.255.0"
LAN 的 IPv4 网关（可为空）
lan_gateway="192.168.1.1"
LAN 的 DNS（多个 DNS 可空格分隔，如 "8.8.8.8 1.1.1.1"）
lan_dns="8.8.8.8 223.5.5.5"
DHCP 是否开启（1=开启，0=关闭）
lan_dhcp_enable="1"
DHCP 起始地址
lan_dhcp_start="100"
DHCP 地址池数量
lan_dhcp_limit="150"
DHCP 租约时间
lan_dhcp_leasetime="12h"
WiFi 名称 SSID（为空则不修改）
wlan_name="ImmortalWrt"
WiFi 密码（≥ 8 位才生效）
wlan_password="12345678"
PPPoE 宽带账号（为空则跳过）
pppoe_username=""
PPPoE 宽带密码
pppoe_password=""
###########################################################
------------ root 密码 ------------
if [ -n "$root_password" ]; then
  (echo "$root_password"; sleep 1; echo "$root_password") | passwd >/dev/null
fi
------------ LAN 基础配置 ------------
if [ -n "$lan_ip_address" ]; then
  uci set network.lan.ipaddr="$lan_ip_address"
fi
if [ -n "$lan_netmask" ]; then
  uci set network.lan.netmask="$lan_netmask"
fi
if [ -n "$lan_gateway" ]; then
  uci set network.lan.gateway="$lan_gateway"
fi
DNS
if [ -n "$lan_dns" ]; then
  uci delete network.lan.dns 2>/dev/null
  for d in $lan_dns; do
    uci add_list network.lan.dns="$d"
  done
fi
uci commit network
------------ DHCP 设置 ------------
if [ -n "$lan_dhcp_enable" ]; then
  uci set dhcp.lan.ignore=$([ "$lan_dhcp_enable" = "1" ] && echo 0 || echo 1)
fi
[ -n "$lan_dhcp_start" ] && uci set dhcp.lan.start="$lan_dhcp_start"
[ -n "$lan_dhcp_limit" ] && uci set dhcp.lan.limit="$lan_dhcp_limit"
[ -n "$lan_dhcp_leasetime" ] && uci set dhcp.lan.leasetime="$lan_dhcp_leasetime"
uci commit dhcp
------------ WIFI 配置 ------------
if [ -n "$wlan_name" ] && [ -n "$wlan_password" ] && [ ${#wlan_password} -ge 8 ]; then
  uci set wireless.@wifi-device[0].disabled='0'
  uci set wireless.@wifi-iface[0].disabled='0'
  uci set wireless.@wifi-iface[0].encryption='psk2'
  uci set wireless.@wifi-iface[0].ssid="$wlan_name"
  uci set wireless.@wifi-iface[0].key="$wlan_password"
  uci commit wireless
fi
------------ PPPoE 宽带拨号 ------------
if [ -n "$pppoe_username" ] && [ -n "$pppoe_password" ]; then
  uci set network.wan.proto=pppoe
  uci set network.wan.username="$pppoe_username"
  uci set network.wan.password="$pppoe_password"
  uci commit network
fi
echo "All done!"

构建完成后，下载对应的固件包，刷入目标设备即可使用。

二、ImmortalWrt 基于源码编译（高度自定义）

2.1 编译环境要求

- 系统：干净的 Debian 12 或 Ubuntu 22.04（建议全新安装，避免依赖冲突）；

- 网络：国外网络通畅（需下载海外源码和依赖）；

- 存储：50G 以上空闲存储空间（编译过程会生成大量中间文件）。

2.2 编译步骤（全程终端操作）

步骤1：安装编译依赖

sudo apt update -y
sudo apt full-upgrade -y
sudo 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 gperf haveged help2man intltool libc6-dev-i386 libelf-dev 
  libglib2.0-dev libgmp-dev libltdl-dev libmpc-dev libmpfr-dev libncurses-dev libpython3-dev 
  libreadline-dev libssl-dev libtool libyaml-dev lld llvm lrzsz genisoimage 
  ninja-build p7zip-full patch pkgconf python3 python3-pip python3-ply python3-docutils 
  python3-pyelftools qemu-utils re2c rsync scons squashfs-tools subversion swig texinfo 
  uglifyjs unzip wget nano xmlto xxd zlib1g-dev upx zstd

步骤2：下载对应版本源码（以 v24.10.4 为例）

说明：后续步骤建议切换为普通用户，不要使用 root 用户编译（避免权限异常）。

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

步骤3：进入项目目录

cd immortalwrt

步骤4：获取最新软件包清单

./scripts/feeds update -a

步骤5：安装软件包符号链接

./scripts/feeds install -a

步骤6：配置固件信息（关键步骤）

make menuconfig

配置说明：

- 前三个选项：目标系统 → 子架构 → 目标机型，需严格根据你的实际设备型号选择；

- 第四个选项 Target Images：用于修改固件配置，其中 Root filesystem partition size（根文件系统分区大小）建议修改，需根据设备存储空间选择（该值为固件可使用的最大存储空间）；

- 其他配置（可选）：在 luci 选项中，可预安装所需插件包（与在线构建的软件包一致）。

步骤7：修改 LAN 口 IP 等基础配置（可选）

可先查看默认配置：https://github.com/immortalwrt/immortalwrt/blob/master/package/base-files/files/bin/config_generate

nano package/base-files/files/bin/config_generate

修改完成后，按 Ctrl+O 保存，Ctrl+X 退出。

步骤8：编译固件

方式1：单线程编译（适合排查编译错误，速度慢）

make -j1 V=s

方式2：多线程编译（推荐，速度快，根据CPU核心数自动分配线程）

make -j$(nproc --ignore=1)

编译完成后，固件文件位于项目目录下的 bin 文件夹中。

步骤9：重新编译说明

若需修改配置后重新编译，需先清理残留文件和工具链，再从步骤4重新开始：

make distclean

三、固件刷入与使用教程

3.1 VirtualBox 虚拟机运行 ImmortalWrt

步骤1：准备镜像文件

选择 x86/64 型号编译固件，下载 COMBINED (EXT4) 格式的镜像，并解压至下载目录。

步骤2：将镜像转换为 VDI 格式

在镜像所在目录打开 PowerShell，执行以下命令（替换镜像文件名）：

& "C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" convertfromraw "immortalwrt-24.10.4-f726c678216d-x86-64-generic-ext4-combined.img"
"immortalwrt.vdi" `
--format VDI

步骤3：创建虚拟机并配置

1. 打开 VirtualBox，点击“新建”，操作系统选择 Linux，版本选择 Other Linux；

2. 指定虚拟硬盘，选择“使用已有的虚拟硬盘文件”，选中刚才转换的 immortalwrt.vdi 文件，点击完成；

3. 进入虚拟机设置，找到“网络”，选择“桥接网卡”，勾选“Virtual Cable Connected”；

4. 注意：ImmortalWrt 系统的 LAN 口 IP 需与电脑在同一网段，网关和 DNS 需与电脑一致。

步骤4：修改网络配置（如需）

vi /etc/config/network  # 编辑网络配置
/etc/init.d/network restart  # 重启网络生效

步骤5：登录后台

打开浏览器，输入 LAN 口 IP 地址，使用脚本中设置的 root 密码登录即可。

3.2 X86 主机将镜像写入硬盘（本地运行）

步骤1：准备工作

将编译好的镜像烧录到 U 盘，使用 U 盘启动电脑，进入 ImmortalWrt 系统（临时运行）。

步骤2：查看设备信息

执行以下命令，查看 U 盘（输入源）和目标硬盘（输出目标）的设备名称（如 U 盘为 /dev/sdb，硬盘为 /dev/sda）：

lsblk -f

步骤3：卸载目标硬盘（若已挂载）

若目标硬盘之前安装过系统，需先卸载其分区（替换 sda1、sda2 为实际分区）：

umount /dev/sda1

umount /dev/sda2

umount /dev/sda3

步骤4：验证卸载是否成功

mount | grep sda

若命令无返回结果，说明卸载成功。

步骤5：写入镜像到硬盘

执行以下命令（替换 /dev/sdb 为 U 盘设备，/dev/sda 为目标硬盘）：

dd if=/dev/sdb of=/dev/sda bs=4M conv=fsync

说明：若未报错，且终端显示两行数字（写入字节数、读取字节数），则代表写入成功。

步骤6：强制刷新缓存

确保所有数据写入硬盘，执行：

sync

命令参数解释

- if=/dev/sdb：输入源，即存放镜像的 U 盘设备；

- of=/dev/sda：输出目标，即要安装 ImmortalWrt 的硬盘/闪存设备；

- bs=4M：每次写入 4M 数据，提升写入速度；

- conv=fsync：写入完成后刷新缓存，确保数据落盘；

- sync：再次确认所有数据写入完成，避免数据丢失。

写入完成后，拔掉 U 盘，重启电脑即可进入 ImmortalWrt 系统。

一、ImmortalWrt 在线构建（快速生成固件）

1.1 在线构建特点

1.2 官方在线编译地址

1.3 必备软件包（推荐添加）

1.4 初始化构建脚本（自定义配置）

自 定 义 配 置 区 域

系统后台密码（为空则不修改）

LAN 的 IPv4 地址（也是后台地址，例如 192.168.2.1）

LAN 的子网掩码（例如 255.255.255.0）

lan_netmask="255.255.255.0"

LAN 的 IPv4 网关（可为空）

lan_gateway="192.168.1.1"

LAN 的 DNS（多个 DNS 可空格分隔，如 "8.8.8.8 1.1.1.1"）

lan_dns="8.8.8.8 223.5.5.5"

DHCP 是否开启（1=开启，0=关闭）

lan_dhcp_enable="1"

DHCP 起始地址

lan_dhcp_start="100"

DHCP 地址池数量

lan_dhcp_limit="150"

DHCP 租约时间

lan_dhcp_leasetime="12h"

WiFi 名称 SSID（为空则不修改）

wlan_name="ImmortalWrt"

WiFi 密码（≥ 8 位才生效）

wlan_password="12345678"

PPPoE 宽带账号（为空则跳过）

pppoe_username=""

PPPoE 宽带密码

pppoe_password=""

------------ root 密码 ------------

------------ LAN 基础配置 ------------

DNS

------------ DHCP 设置 ------------

------------ WIFI 配置 ------------

------------ PPPoE 宽带拨号 ------------