在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常见问题及解决方案问题1fatal: destination path openwrt already exists and is not an empty directory.解决方法删除或重命名现有目录或者指定不同的克隆路径。问题2切换版本后feeds不匹配解决方法务必在切换版本后执行以下命令./scripts/feeds update -a ./scripts/feeds install -a我遇到的最棘手的问题是feeds更新不完整部分包无法安装。经过多次尝试发现这是网络连接不稳定导致的。解决方案是多次重复执行feeds更新命令检查feeds目录下的.index文件是否完整必要时可以手动删除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排查过程在OpenWrt官方GitHub的Issues中搜索相关错误发现这是已知问题#22668分析发现是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) TITLEw/ SHA256 password auth DEPENDS:python3-pymysql $(RUST_ARCH_DEPENDS) PACKAGE_python3-pymysql-sha-pwd:python3-cryptography endef这个案例教会我遇到编译错误时首先仔细阅读错误信息在官方Issue tracker中搜索相关错误理解问题的根本原因再应用修复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工具来进行格式转换解决方案安装缺失的软件包sudo apt install qemu qemu-utils或者如果不必须使用VMDK格式重新运行make menuconfig取消选择VMDK镜像格式只保留需要的格式如squashfs或ext4经验分享首次编译建议使用make -j1 Vs以便更好地查看错误成功编译一次后可以使用make -j$(nproc)加速后续编译编译生成的镜像位于bin/targets目录下5. 编译优化与调试技巧经过多次尝试我总结出以下提高成功率的技巧准备工作确保至少有20GB的可用磁盘空间使用SSD可以显著加快编译速度保持网络连接稳定编译命令make -j$(($(nproc)1)) download make -j$(($(nproc)1)) world调试方法查看详细日志添加Vs参数检查特定包的编译日志在build_dir目录下查找对应包的日志清理特定包make package/name/clean常见问题速查表问题现象可能原因解决方案下载失败网络问题多次重试或更换网络环境依赖错误包版本冲突更新feeds或手动修改Makefile权限不足未使用sudo检查命令权限需求空间不足磁盘空间不够清理空间或扩大分区6. 个性化配置建议成功编译基础系统后你可能想添加一些个性化功能常用配置选项LuCI界面中文支持LuCI → Modules → Translations → Chinese Simplified (zh_Hans)常用工具在Network或Utilities类别中选择需要的工具内核模块根据硬件需求添加特定驱动配置技巧先使用官方配置作为基础make defconfig小步迭代修改配置每次测试编译备份成功的.config文件经过这些调整和优化我最终成功编译出了满足需求的OpenWrt固件。整个过程虽然曲折但解决问题的过程让我对OpenWrt的构建系统有了更深入的理解。
在Ubuntu 22.04上编译OpenWrt 23.05.2，我踩过的坑和解决方案都在这了
发布时间：2026/5/21 3:11:03
在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常见问题及解决方案问题1fatal: destination path openwrt already exists and is not an empty directory.解决方法删除或重命名现有目录或者指定不同的克隆路径。问题2切换版本后feeds不匹配解决方法务必在切换版本后执行以下命令./scripts/feeds update -a ./scripts/feeds install -a我遇到的最棘手的问题是feeds更新不完整部分包无法安装。经过多次尝试发现这是网络连接不稳定导致的。解决方案是多次重复执行feeds更新命令检查feeds目录下的.index文件是否完整必要时可以手动删除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排查过程在OpenWrt官方GitHub的Issues中搜索相关错误发现这是已知问题#22668分析发现是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) TITLEw/ SHA256 password auth DEPENDS:python3-pymysql $(RUST_ARCH_DEPENDS) PACKAGE_python3-pymysql-sha-pwd:python3-cryptography endef这个案例教会我遇到编译错误时首先仔细阅读错误信息在官方Issue tracker中搜索相关错误理解问题的根本原因再应用修复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工具来进行格式转换解决方案安装缺失的软件包sudo apt install qemu qemu-utils或者如果不必须使用VMDK格式重新运行make menuconfig取消选择VMDK镜像格式只保留需要的格式如squashfs或ext4经验分享首次编译建议使用make -j1 Vs以便更好地查看错误成功编译一次后可以使用make -j$(nproc)加速后续编译编译生成的镜像位于bin/targets目录下5. 编译优化与调试技巧经过多次尝试我总结出以下提高成功率的技巧准备工作确保至少有20GB的可用磁盘空间使用SSD可以显著加快编译速度保持网络连接稳定编译命令make -j$(($(nproc)1)) download make -j$(($(nproc)1)) world调试方法查看详细日志添加Vs参数检查特定包的编译日志在build_dir目录下查找对应包的日志清理特定包make package/name/clean常见问题速查表问题现象可能原因解决方案下载失败网络问题多次重试或更换网络环境依赖错误包版本冲突更新feeds或手动修改Makefile权限不足未使用sudo检查命令权限需求空间不足磁盘空间不够清理空间或扩大分区6. 个性化配置建议成功编译基础系统后你可能想添加一些个性化功能常用配置选项LuCI界面中文支持LuCI → Modules → Translations → Chinese Simplified (zh_Hans)常用工具在Network或Utilities类别中选择需要的工具内核模块根据硬件需求添加特定驱动配置技巧先使用官方配置作为基础make defconfig小步迭代修改配置每次测试编译备份成功的.config文件经过这些调整和优化我最终成功编译出了满足需求的OpenWrt固件。整个过程虽然曲折但解决问题的过程让我对OpenWrt的构建系统有了更深入的理解。
