在Ubuntu 22.04上编译OpenWrt 23.05.2，我踩过的坑和解决方案都在这了

在Ubuntu 22.04上编译OpenWrt 23.05.2的深度排错指南

编译OpenWrt固件是许多网络爱好者和开发者的必经之路，但这个过程往往伴随着各种意想不到的挑战。本文将分享我在Ubuntu 22.04系统上编译OpenWrt 23.05.2时遇到的实际问题及其解决方案，希望能帮助遇到类似困境的开发者少走弯路。

1. 环境准备：那些官方文档没告诉你的细节

Ubuntu 22.04作为长期支持版本，理论上应该是编译OpenWrt的理想平台。但实际操作中，我发现官方文档列出的依赖包并不完全准确。以下是经过验证的完整依赖安装命令：

sudo apt update sudo apt install -y build-essential clang flex bison g++ gawk \ gcc-multilib g++-multilib gettext git libncurses-dev libssl-dev \ python3-distutils rsync unzip zlib1g-dev file wget qemu qemu-utils \ libelf-dev python3-setuptools ccache

注意：qemu-utils这个包经常被忽略，但如果你计划生成VDI/VMDK格式的虚拟机镜像，它是必不可少的。我在第一次编译时就因为缺少它而失败。

提示：使用ccache可以显著加快后续的编译速度，特别是当你需要多次尝试不同的配置时。

2. 源代码管理：从克隆到版本切换的陷阱

获取OpenWrt源代码看似简单，但有几个关键点需要注意：

git clone https://git.openwrt.org/openwrt/openwrt.git cd openwrt git checkout v23.05.2

常见问题及解决方案：

• 问题1：fatal: destination path 'openwrt' already exists and is not an empty directory.

  解决方法：删除或重命名现有目录，或者指定不同的克隆路径。

• 问题2：切换版本后feeds不匹配

  解决方法：务必在切换版本后执行以下命令：

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

我遇到的最棘手的问题是feeds更新不完整，部分包无法安装。经过多次尝试，发现这是网络连接不稳定导致的。解决方案是：

1. 多次重复执行feeds更新命令
2. 检查feeds目录下的.index文件是否完整
3. 必要时可以手动删除feeds目录重新开始

3. 递归依赖错误：python3-pymysql案例分析

执行make defconfig时，我遇到了典型的递归依赖错误：

tmp/.config-package.in:33826:error: recursive dependency detected! tmp/.config-package.in:33826: symbol PACKAGE_python3-pymysql depends on PYTHON3_PYMYSQL_SHA_PASSWORD_SUPPORT feeds/packages/lang/python/pymysql/Config.in:4: symbol PYTHON3_PYMYSQL_SHA_PASSWORD_SUPPORT depends on PACKAGE_python3-pymysql

排查过程：

1. 在OpenWrt官方GitHub的Issues中搜索相关错误
2. 发现这是已知问题（#22668）
3. 分析发现是feeds/packages/lang/python/pymysql路径下的Makefile存在依赖冲突

解决方案：

需要修改pymysql的Makefile文件，主要变更包括：

• 将PKG_RELEASE从1改为2
• 重构包定义，分离基础包和SHA密码支持功能
• 添加新的python3-pymysql-sha-pwd元包

修改后的关键部分如下：

define Package/python3-pymysql $(call Package/python3-pymysql/Default) DEPENDS:=+python3 endef define Package/python3-pymysql-sha-pwd $(call Package/python3-pymysql/Default) TITLE+=w/ SHA256 password auth DEPENDS:=+python3-pymysql $(RUST_ARCH_DEPENDS) PACKAGE_python3-pymysql-sha-pwd:python3-cryptography endef

这个案例教会我，遇到编译错误时：

1. 首先仔细阅读错误信息
2. 在官方Issue tracker中搜索相关错误
3. 理解问题的根本原因再应用修复

4. 镜像生成失败：qemu-img缺失问题

在编译接近完成时，系统报错：

WARNING: Install qemu-img to create VDI/VMDK images make[5]: *** [Makefile:158: /path/to/openwrt-23.05.2-x86-64-generic-squashfs-combined.vmdk] Error 1

原因分析：

• 在make menuconfig中选择了生成VMDK格式的镜像
• 系统缺少qemu-img工具来进行格式转换

解决方案：

1. 安装缺失的软件包：

   sudo apt install qemu qemu-utils

2. 或者，如果不必须使用VMDK格式：

   • 重新运行make menuconfig
   • 取消选择VMDK镜像格式
   • 只保留需要的格式（如squashfs或ext4）

经验分享：

• 首次编译建议使用make -j1 V=s以便更好地查看错误
• 成功编译一次后，可以使用make -j$(nproc)加速后续编译
• 编译生成的镜像位于bin/targets目录下

5. 编译优化与调试技巧

经过多次尝试，我总结出以下提高成功率的技巧：

准备工作：

1. 确保至少有20GB的可用磁盘空间
2. 使用SSD可以显著加快编译速度
3. 保持网络连接稳定

编译命令：

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

调试方法：

• 查看详细日志：添加V=s参数
• 检查特定包的编译日志：在build_dir目录下查找对应包的日志
• 清理特定包：make package/name/clean

常见问题速查表：

6. 个性化配置建议

成功编译基础系统后，你可能想添加一些个性化功能：

常用配置选项：

1. LuCI界面中文支持：

   • LuCI → Modules → Translations → Chinese Simplified (zh_Hans)

2. 常用工具：

   • 在Network或Utilities类别中选择需要的工具

3. 内核模块：

   • 根据硬件需求添加特定驱动

配置技巧：

• 先使用官方配置作为基础：make defconfig
• 小步迭代修改配置，每次测试编译
• 备份成功的.config文件

经过这些调整和优化，我最终成功编译出了满足需求的OpenWrt固件。整个过程虽然曲折，但解决问题的过程让我对OpenWrt的构建系统有了更深入的理解。