使用 WSL 编译 OpenWrt 固件完整指南

Posted 2021-11-25 Updated 5 days ago

By Ryan Chen

30~39 min read

使用 WSL 编译 OpenWrt 固件完整指南

前言

OpenWrt 固件编译通常需要 Linux 环境。对于日常主力机是 Windows 的用户来说，WSL2 是一个非常方便的选择：不用单独安装 Linux 虚拟机，也不需要长期维护一台独立编译服务器，就可以在 Windows 中完成 OpenWrt 固件构建。

不过，WSL 编译 OpenWrt 也有一些容易踩坑的地方：

不要在 /mnt/c 这类 Windows 挂载目录中编译；
需要使用 WSL2，而不是早期 WSL1；
依赖包要按当前 OpenWrt 官方文档更新；
第三方源码和插件可能带来 feed 冲突；
首次编译最好单线程，方便定位错误；
.config 要备份，否则二次编译很容易丢配置。

本文以 WSL2 + Ubuntu / Debian 为基础，整理一套相对通用的 OpenWrt 固件编译流程。文中也会说明官方 OpenWrt、Lean lede、ImmortalWrt 的区别，方便根据自己的软路由需求选择源码。

编译前准备

建议准备：

项目	建议
Windows	Windows 10 2004+ 或 Windows 11
WSL	WSL2
Linux 发行版	Ubuntu 22.04 / 24.04 或 Debian
磁盘空间	至少 30GB，建议 50GB+
内存	至少 8GB，建议 16GB+
网络	能稳定访问 GitHub、OpenWrt 源和软件包下载站

特别注意：

OpenWrt 源码必须放在 WSL 的 Linux 文件系统中，例如 ~/openwrt，不要放在 /mnt/c/Users/... 下编译。

原因包括：

Windows 文件系统大小写敏感问题；
软链接、权限、可执行位可能异常；
/mnt/c I/O 性能较差；
构建系统会生成大量小文件，Windows 挂载目录容易拖慢编译。

推荐路径：

cd ~
mkdir -p workspace
cd workspace

安装 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu

或者安装 Debian：

wsl --install -d Debian

安装完成后重启，首次进入 Linux 子系统时会要求创建用户名和密码。

查看 WSL 版本：

wsl -l -v

如果不是 WSL2，可以转换：

wsl --set-version Ubuntu 2

也可以设置默认使用 WSL2：

wsl --set-default-version 2

可选：配置代理

如果网络环境无法稳定访问 GitHub 或 OpenWrt 下载源，可以在 WSL 中配置代理。

例如本机代理端口为 7890：

cat >> ~/.bashrc <<'EOF'
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export all_proxy="socks5://127.0.0.1:7890"
EOF

source ~/.bashrc

验证：

curl -I https://github.com

如果 Windows 代理没有监听 WSL 可访问地址，需要根据实际网络环境调整为 Windows 主机 IP。

安装编译依赖

先更新系统：

sudo apt update
sudo apt upgrade -y

安装常用构建依赖：

sudo apt install -y \
  build-essential clang flex bison g++ gawk gcc-multilib g++-multilib \
  gettext git libncurses-dev libssl-dev python3 python3-distutils \
  python3-setuptools rsync swig unzip zlib1g-dev file wget curl \
  subversion mercurial libelf-dev device-tree-compiler \
  qemu-utils ccache xsltproc docbook-xsl

说明：

新版本 Ubuntu / Debian 中，python2.7、lib32gcc1 等旧包可能不可用；
依赖包会随 OpenWrt 版本和 Linux 发行版变化，建议以 OpenWrt 官方文档为准；
如果编译过程中提示缺少某个命令或库，再按错误信息补装。

选择源码：官方 OpenWrt、Lean lede、ImmortalWrt

不同源码适合不同场景。

源码	地址	特点	适合场景
官方 OpenWrt	`https://github.com/openwrt/openwrt.git`	官方主线、文档完善、上游兼容性好	学习、稳定、官方设备支持
Lean lede	`https://github.com/coolsnowwolf/lede.git`	国内软路由用户多、插件生态丰富	x86 软路由、个人定制
ImmortalWrt	`https://github.com/immortalwrt/immortalwrt.git`	OpenWrt 分支，国内设备和包支持较多	国内设备、软路由定制

如果是第一次学习构建流程，建议先用官方 OpenWrt 完成一次最小编译；如果目标是软路由插件较多的个人固件，再考虑 Lean lede 或 ImmortalWrt。

拉取源码

官方 OpenWrt

cd ~/workspace
git clone https://github.com/openwrt/openwrt.git
cd openwrt

Lean lede

cd ~/workspace
git clone https://github.com/coolsnowwolf/lede.git openwrt
cd openwrt

ImmortalWrt

cd ~/workspace
git clone https://github.com/immortalwrt/immortalwrt.git openwrt
cd openwrt

后文统一假设源码目录为：

~/workspace/openwrt

更新 feeds

进入源码目录：

cd ~/workspace/openwrt

更新并安装 feeds：

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

feeds 可以理解为 OpenWrt 软件包索引。更新 feeds 后，make menuconfig 中才能选择对应软件包。

可选：添加第三方 feed

如果需要额外插件，可以编辑 feeds.conf.default 或创建 feeds.conf。

例如：

echo 'src-git helloworld https://github.com/fw876/helloworld' >> feeds.conf.default

然后重新更新：

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

注意：

第三方 feed 可能存在兼容性、依赖冲突、下载失败、源码变动和合规风险。建议先完成官方源码最小编译，再逐步添加插件。

如果一开始就添加大量插件，编译失败时很难判断问题来自 OpenWrt 本体、feed 还是某个具体插件。

配置固件

执行：

make menuconfig

常见选择：

Target System
Subtarget
Target Profile
LuCI
Network
Utilities

例如 x86_64 软路由通常选择：

Target System  ---> x86
Subtarget       ---> x86_64
Target Profile  ---> Generic x86/64

保存后会生成 .config 文件。

可选：修改默认 IP

OpenWrt 默认 LAN IP 通常是 192.168.1.1。如果和现有网络冲突，可以修改为其他网段。

部分源码可以通过修改 config_generate 实现：

sed -i 's/192.168.1.1/192.168.66.1/g' package/base-files/files/bin/config_generate

更推荐的方式是：

编译后首次启动再通过 LuCI 或 UCI 修改；
或者使用自定义 files 覆盖配置；
不同源码分支路径可能不同，修改前先确认文件存在。

检查：

grep -R "192.168.1.1" package/base-files/files/bin/config_generate

保存和复用配置

.config 很重要，建议备份：

cp .config ../openwrt.config.backup

恢复配置：

cp ../openwrt.config.backup .config
make defconfig

如果只想保存和默认配置的差异，可以使用：

./scripts/diffconfig.sh > diffconfig

后续可以把 diffconfig 作为自己的最小配置记录，方便迁移到新源码。

下载源码包

开始正式编译前，先下载依赖源码包：

make download -j$(nproc)

检查异常小文件：

find dl -size -1024c -exec ls -lh {} \;

如果确认是下载失败产生的异常文件，可以删除后重新下载：

find dl -size -1024c -exec rm -f {} \;
make download -j$(nproc)

开始编译

首次编译建议单线程，方便定位错误：

make -j1 V=s

说明：

-j1：单线程；
V=s：输出详细日志；
首次编译时间可能很长，取决于 CPU、内存、磁盘和网络。

如果首次编译成功，后续可以提高并发：

make -j$(nproc)

或者稍微激进一点：

make -j$(($(nproc) + 1))

如果出现奇怪的编译失败，优先回到：

make -j1 V=s

用单线程日志定位具体失败包。

查找编译产物

编译成功后，固件一般在：

bin/targets/<target>/<subtarget>/

例如 x86_64：

bin/targets/x86/64/

查看：

ls -lh bin/targets/x86/64/

在 Windows 资源管理器中可以访问：

\\wsl$\Ubuntu\home\你的用户名\workspace\openwrt\bin\targets\x86\64

不同 WSL 发行版名称可能不同，可以在 PowerShell 中查看：

wsl -l -v

二次编译与更新

进入源码目录：

cd ~/workspace/openwrt

更新源码：

git pull

更新 feeds：

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

如果配置不变：

make defconfig

重新下载：

make download -j$(nproc)

编译：

make -j$(nproc)

如果改了大量源码、feeds 或遇到异常，可以清理后重来。

常见清理命令：

make clean       # 清理 bin 和 build_dir，保留工具链
make dirclean    # 更彻底，清理工具链，耗时更长
make distclean   # 清理到接近初始状态，会删除 .config 等配置

使用 distclean 前一定要备份 .config。

常见问题排查

1. 不要在 /mnt/c 下编译

错误示例：

cd /mnt/c/Users/xxx/openwrt
make

建议移动到：

~/workspace/openwrt

2. 下载失败

表现：

make download 报错；
dl 目录出现很小的压缩包；
编译到某个包时报 checksum 错误。

处理：

find dl -size -1024c -exec rm -f {} \;
make download -j$(nproc)

必要时检查代理或手动下载。

3. 内存不足

表现：

编译中断；
cc1plus 被 killed；
WSL 内存占满。

处理：

make -j1 V=s

也可以配置 .wslconfig 限制或增加 WSL 可用资源。

4. 磁盘空间不足

检查：

df -h

清理：

make clean

如果 WSL 虚拟磁盘长期膨胀，需要根据 Microsoft WSL 文档进行压缩或迁移。

5. feed 冲突

如果添加第三方 feed 后失败，建议：

注释掉第三方 feed；
重新 feeds update/install；
最小配置编译；
再逐个添加插件定位问题。

6. menuconfig 找不到包

通常是 feeds 没安装：

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

如果还是找不到，检查 feed 是否更新成功、分支是否兼容。

7. 配置丢失

如果执行了 make distclean 或删除 .config，配置会丢失。

建议长期保留：

.config
openwrt.config.backup
diffconfig

实践建议

第一次先编译官方 OpenWrt 或最小配置，确认环境可用；
插件不要一次性加太多，逐步添加更容易排错；
.config 和 diffconfig 要备份；
首次失败优先用 make -j1 V=s；
编译目录放在 WSL Linux 文件系统；
不要盲目复制过旧依赖列表；
软路由固件升级前先备份配置；
第三方插件涉及网络代理、DNS、广告过滤时，要注意当地法律法规和网络合规要求。

总结

使用 WSL2 编译 OpenWrt 是 Windows 用户定制软路由固件的便捷方案。完整流程可以概括为：

安装 WSL2
  ↓
安装编译依赖
  ↓
选择源码
  ↓
更新 feeds
  ↓
make menuconfig
  ↓
make download
  ↓
make -j1 V=s
  ↓
在 bin/targets 中获取固件

相比旧版教程，当前更需要注意：

使用 WSL2；
编译目录放在 Linux 文件系统；
依赖包按官方文档更新；
区分官方 OpenWrt 和第三方分支；
先最小编译，再添加第三方插件；
保存 .config 和 diffconfig；
遇到问题用单线程详细日志排查。

如果后续要在 PVE 中安装编译好的 OpenWrt 固件，可以参考：PVE 安装 OpenWrt：软路由虚拟机搭建指南。

参考资料

软路由

OpenWrt WSL2 Windows 固件编译软路由 Linux Build System OpenWrt 编译

License: CC BY 4.0