介绍在 Ubuntu 环境下编译 OpenWrt 固件的完整流程。涵盖硬件环境准备、源码克隆、配置界面操作、编译命令执行、多架构支持及 Docker 环境构建。同时提供常见问题排查方法与性能优化技巧，帮助开发者定制高效稳定的嵌入式系统固件。
在嵌入式系统开发领域，OpenWrt 固件编译是一项核心技能，它允许开发者根据特定硬件需求定制路由器系统。本文将通过关键步骤，带领你在 Ubuntu 环境下完成 OpenWrt 固件的编译全过程，涵盖环境准备、源码获取、配置优化、编译执行、结果解析、扩展方案及问题排查等关键环节。
搭建符合 OpenWrt 编译要求的 Ubuntu 开发环境，确保硬件兼容性与软件依赖完整性。
| 硬件类型 | 最低配置 | 推荐配置 | |---------|---------|---------|| | 处理器 | 双核 CPU | 四核及以上 | | 内存 | 4GB RAM | 8GB RAM | | 存储 | 40GB 可用空间 | 100GB SSD | | 网络 | 稳定互联网连接 | 100Mbps 以上 |
系统依赖安装
# 更新软件源
sudo apt update
# 安装基础编译工具链
sudo apt install -y build-essential subversion git-core libncurses5-dev \
zlib1g-dev gawk flex quilt libssl-dev xsltproc libxml-parser-perl \
mercurial bzr ecj cvs unzip git wget curl rsync
执行以下命令检查关键依赖是否安装成功：
# 检查 gcc 版本
gcc --version
# 检查 git 版本
git --version
获取完整的 OpenWrt 项目源码并了解项目结构，为后续编译配置做准备。
| 目录/文件 | 功能描述 | |---------|---------|| | configs/ | 设备配置文件集合 | | docker/ | Docker 编译环境配置 | | images/ | 项目图片资源 | | scripts/ | 自动化配置脚本 | | diy-script.sh | 完整功能配置脚本 | | diy-mini.sh | 精简版配置脚本 |
克隆代码仓库
# 克隆项目源码
git clone https://gitcode.com/GitHub_Trending/open/OpenWrt
# 进入项目目录
cd OpenWrt
查看项目目录结构确认源码克隆成功：
# 列出项目根目录文件
ls -la
根据目标设备架构和功能需求，配置编译参数与软件包选择。
自定义配置
# 启动图形化配置界面
make menuconfig
在配置界面中可以：
选择设备配置文件
| 配置文件 | 适用架构 | 特点 | |---------|---------|------|| | x86_64.config | X86_64 | 通用 PC 架构，功能完整 | | x86_64-mini.config | X86_64 | 精简版本，适合资源有限设备 | | rpi4.config | ARM | 树莓派 4B 专用配置 | | armv8-docker.config | ARMv8 | 适用于 Docker 环境的 ARM 配置 |
应用配置文件：
# 例如选择 x86_64 架构完整配置
cp configs/x86_64.config .config
运行配置脚本
# 完整功能版本
bash diy-script.sh
# 或精简版本
bash diy-mini.sh
检查配置文件是否正确生成：
# 查看配置摘要
cat .config | grep -i "CONFIG_TARGET"
执行编译过程并优化编译参数，提高编译效率和成功率。
| 参数 | 说明 | 推荐配置 | |------|------|---------|| | -jN | 并行编译任务数 | N=CPU 核心数 +1 | | V=s | 显示详细编译信息 | 调试时使用 | | -s | 静默模式 | 减少输出信息 |
开始编译
# 使用所有 CPU 核心编译并显示详细信息
make -j$(nproc) V=s
下载依赖包
# 多线程下载依赖包
make download -j8
| 硬件配置 | 预估时间 | 备注 |
|---|---|---|
| 双核 4GB | 3-4 小时 | 基础配置 |
| 四核 8GB | 1.5-2 小时 | 推荐配置 |
| 八核 16GB | 45-60 分钟 | 高性能配置 |
检查编译过程是否正常进行，无错误提示。
make clean了解多架构编译方法，掌握 Docker 环境下的编译流程。
| 架构 | 适用设备 | 编译要点 | |------|---------|---------|| | x86_64 | 通用 PC、虚拟机 | 兼容性好，编译速度快 | | ARM | 树莓派、嵌入式设备 | 需要特定交叉编译工具链 | | MIPS | 传统路由器 | 资源占用低，功能相对精简 |
Docker 编译环境
# 进入 Docker 目录
cd docker
# 构建 Docker 镜像
bash buildImageX.sh
检查 Docker 镜像是否构建成功：
docker images | grep openwrt
识别并解决常见编译错误，优化编译流程。
| 错误类型 | 可能原因 | 解决方法 | |---------|---------|---------|| | 依赖缺失 | 缺少必要的开发库 | 安装对应的-dev 包 | | 网络问题 | 依赖包下载失败 | 检查网络连接或使用代理 | | 配置错误 | 选择了不兼容的功能组合 | 重置配置或检查依赖关系 | | 磁盘空间 | 存储空间不足 | 清理空间或扩展分区 |
编译环境清理
# 清理编译中间文件
make clean
# 完全清理（包括配置）
make distclean
重新执行编译命令，确认错误已解决。
make distclean会清除所有配置，谨慎使用掌握高级编译技巧，提升固件质量和编译效率。
编译性能优化
# 使用 ccache 加速重复编译
sudo apt install ccache
export USE_CCACHE=1
export CCACHE_DIR=/path/to/ccache
配置文件管理
# 备份配置
cp .config configs/my-custom.config
# 恢复配置
cp configs/my-custom.config .config
| 工具 | 推荐版本 | 最低版本 |
|---|---|---|
| GCC | 7.5.0+ | 5.4.0 |
| Git | 2.20.0+ | 1.8.0 |
| Perl | 5.26+ | 5.18.0 |
| Python | 3.6+ | 3.4.0 |
| CMake | 3.10+ | 2.8.12 |
通过本文介绍的步骤，你已掌握 OpenWrt 固件编译的完整流程。从环境搭建到问题排查，从基础配置到高级优化，这些技能将帮助你根据实际需求定制高效稳定的 OpenWrt 固件。记住，编译过程中遇到问题是正常的，关键是通过错误信息定位问题并逐步解决。随着实践经验的积累，你将能够更高效地完成固件定制与优化工作。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online