OpenWrt 编译完整教程 (从零开始)

OpenWrt 的魅力之一就是它的可定制性，通过自己编译，你可以：

• 选择自己需要的软件包：只编译你需要的功能，去除不需要的，减小固件体积，提高设备性能。
• 集成自定义软件：添加你自己的程序或脚本。
• 更新内核和软件：使用最新的稳定版或开发版内核。
• 深度定制系统：修改配置文件、主题等。

本教程将使用目前最主流、最推荐的 LEDE 项目（后与 OpenWrt 合并，现在统称 OpenWrt）的 SDK 和 make menuconfig 方式进行编译，这种方式相对简单且不易出错。

第一部分：准备工作

在开始之前,请确保你的环境满足以下要求。

硬件要求

• 一台电脑：无论是 Windows, macOS 还是 Linux 都可以。
• 足够的内存：强烈建议 8GB 或以上，如果内存较小（如 4GB），编译过程会非常缓慢，甚至可能失败，可以通过创建一个虚拟的交换文件来缓解。
• 足够的硬盘空间：至少需要 20GB 的可用空间，整个编译过程会下载大量源码和依赖，最终生成的固件和源码仓库会占用大量空间。
• 稳定的网络连接：需要从 GitHub 和 OpenWrt 的服务器下载大量源码和软件包，网络不稳定会导致下载失败。

软件环境

根据你的操作系统进行准备：

A. Linux (推荐，最原生)

以 Ubuntu/Debian 为例，其他发行版包名可能略有不同。

# 更新软件包列表
sudo apt update
# 安装编译所需的基本工具
sudo apt install -y build-essential cmake ccache git unzip python3 python3-pip python3-setuptools python3-distutils libncurses-dev gawk subversion libssl-dev zlib1g-dev file wget rsync
# 安装 OpenWrt 官方推荐的 Python 依赖
# 注意：OpenWrt 22.03 及以后版本推荐使用 Python 3
sudo pip3 install setuptools

B. macOS

使用 Homebrew 来安装依赖。

# 安装 Xcode Command Line Tools
xcode-select --install
# 安装 Homebrew (如果尚未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装编译所需工具
brew install coreutils gawk wget gettext cmake ccache libtool automake autoconf unzip

C. Windows (最复杂，不推荐新手)

Windows 环境编译 OpenWrt 非常麻烦，需要借助 WSL (Windows Subsystem for Linux) 或虚拟机。

• 推荐方式：WSL 2

  1. 在 Windows 功能中启用 "适用于 Linux 的 Windows 子系统" 和 "虚拟机平台"。
  2. 从 Microsoft Store 安装 Ubuntu (建议选择 20.04 LTS 或 22.04 LTS 版本)。
  3. 打开 Ubuntu 终端，它会引导你创建一个用户名和密码。
  4. 在 Ubuntu 终端内，执行上面 Linux (Ubuntu/Debian) 部分的所有安装命令即可。

• 备选方式：虚拟机

  1. 安装 VMware 或 VirtualBox。
  2. 下载一个 Ubuntu Desktop 的 ISO 镜像文件。
  3. 在虚拟机中安装 Ubuntu 系统，然后按照 Linux 的步骤安装依赖。

第二部分：编译流程

你的环境已经准备好了,可以开始编译了。

步骤 1：下载 OpenWrt 源码

我们选择一个稳定的版本分支,openwrt-22.03，你也可以选择最新的 master 分支，但稳定性可能稍差。

# 创建一个工作目录
mkdir openwrt-workspace
cd openwrt-workspace
# 克隆 OpenWrt 源码仓库
# 这里以 22.03.5 版本为例，你可以去 GitHub 查找最新的稳定版本号
git clone https://github.com/openwrt/openwrt.git -b openwrt-22.03.5

等待下载完成,这会创建一个名为 openwrt 的目录。

步骤 2：更新和安装 feeds

feeds 是 OpenWrt 的软件包管理系统，包含了大量非核心的软件包。

# 进入源码目录
cd openwrt
# 更 feeds 的索引
./scripts/feeds update -a
# 安装所有 feeds 中的软件包到源码树中
./scripts/feeds install -a

步骤 3：配置固件

这是整个编译过程中最核心的一步,决定了你的固件里包含什么。

# 打开图形化配置菜单
make menuconfig

你会看到一个类似 Linux 内核配置的 ncurses 界面。

• 导航：使用 方向键移动光标。
• 选择：按 Enter 键进入子菜单，按 Y 键选中（[*]），按 M 键编译为模块（<M>），按 N 键取消选中（[ ]）。
• 搜索：按 键可以快速搜索配置项。
• 保存和退出：按 Esc 键返回上一层，直到主菜单，选择 Save 保存你的配置，然后选择 Exit 退出。

关键配置项说明：

1. Target System (目标系统)

   • 路径：Target System
   • 说明：选择你的路由器 SoC 架构，如果你用的是小米 AX3600/AX6000，你应该选择 ARMv8 based CPUs，如果你用的是华为 AX3 Pro，你应该选择 ARMv7 based CPUs。
   • 如何查找：去你的路由器官网或 OpenWrt 官网的硬件兼容列表页面查找你的型号，确认其 SoC 类型。

2. Subtarget (子目标)

   • 路径：在 Target System 下选择
   • 说明：进一步细化 SoC 类型，在 ARMv8 based CPUs 下，有 Rockchip RK33xx (小米 AX3600/AX6000) 和 Qualcomm Atheros IPQ806x (网件 R7800) 等。

3. Target Profile (目标型号)

   • 路径：在 Subtarget 下选择
   • 说明：这是最重要的一步！ 从列表中选择你的 具体路由器型号。Xiaomi Mi Router AX3600，选择后，系统会自动加载该型号的默认配置（如分区、默认插件等）。

4. LuCI -> Applications (Web 界面插件)

   • 路径：LuCI -> Applications
   • 说明：这里是你添加/删除 Web 管理界面插件的地方。
   • 推荐新手保留：
     • luci-app-adblock (广告屏蔽)
     • luci-app-argon-config (主题配置)
     • luci-app-upnp (通用即插即用)
     • luci-app-wol (网络唤醒)
   • 按需添加：
     • luci-app-aria2 (下载工具)
     • luci-app-docker (容器)
     • luci-app-v2ray (代理)
     • luci-app-smartdns (智能 DNS)

5. Utilities (工具)

   • 路径：Utilities
   • 说明：添加命令行工具。
   • 推荐添加：
     • curl (URL 传输工具)
     • htop (系统进程监控)
     • vim / nano (文本编辑器)
     • wget (文件下载)
     • bc (计算器)
     • jq (JSON 处理器)

6. Network (网络)

   • 路径：Network
   • 说明：添加网络协议和工具。
   • 推荐添加：
     • luci-app-mwan3 (多拨负载均衡)
     • luci-app-olsr (OLSRd 动态路由)
     • luci-app-sqm (智能队列管理，优化延迟)

配置完成后,保存并退出。

步骤 4：下载编译依赖 (下载 Dl files)

这一步会根据你的 .config 文件，自动下载所有需要的源码包和工具链。

make download -j$(nproc)

如果过程中出现网络错误,可以多试几次或使用代理，完成后，你会在 dl 目录下看到所有下载好的文件。

步骤 5：开始编译

万事俱备,开始编译！

# -j$(nproc) 表示使用所有 CPU 核心进行并行编译，速度最快
make -j$(nproc)

编译过程：

• 第一次编译：会非常非常慢！因为需要下载并编译整个工具链和所有选定的软件包，根据你的电脑性能，这可能需要 30分钟到数小时不等。
• 后续编译：如果你只修改了少量配置或软件包，再次编译会快很多，因为它只会重新编译发生变化的文件。

编译成功标志：

当你看到类似下面的输出时,表示编译成功了！

...
package/Makefile:144: recipe for target 'compile' failed
make[2]: Leaving directory '/home/user/openwrt-workspace/openwrt'
make[1]: Leaving directory '/home/user/openwrt-workspace/openwrt'
rm -rf /tmp/.ccache-root
# make[1]: Leaving directory '/home/user/openwrt-workspace/openwrt'

注意：如果看到 recipe for target 'compile' failed，不要慌张，这通常只是某个软件包编译失败，不代表整个编译失败，你需要继续向上滚动日志，找到具体的错误信息，通常的错误是：

• 内存不足：cc1plus: out of memory，尝试减少 -j 的值，如 make -j1 V=s`。
• 网络问题：下载中断，可以尝试重新 make download 或使用代理。
• 代码错误：某个软件包的源码有问题，可以尝试更新到最新版本或暂时禁用该软件包。

步骤 6：找到你的固件

编译成功后,你的固件会生成在 bin/targets/ 目录下。

路径结构为：bin/targets/<目标系统>/<子目标>/

对于小米 AX3600 (Rockchip RK33xx)，固件会在： bin/targets/armv8-rockchip/rk33xx/

在这个目录下,你会看到几个文件：

• openwrt-rockchip-armv8-xxxxxxxxxxxx-squashfs-factory.img：刷机固件，用于官方升级或 TFTP 恢复。
• openwrt-rockchip-armv8-xxxxxxxxxxxx-squashfs-sysupgrade.bin：系统升级固件，用于在已刷入 OpenWrt 的系统上进行升级。
• openwrt-rockchip-armv8-xxxxxxxxxxxx-ext4-factory.img：另一种格式的刷机固件。
• manifest: 包含了该固件的所有软件包列表。

如何刷机？ 请务必根据你的 路由器型号，去 OpenWrt 官网 Wiki 页面查找正确的刷机方法！刷错固件或方法不当会导致设备变砖。

第三部分：常见问题与技巧

1. 如何清理编译环境？

   • make clean：清理编译产生的文件，但保留 .config 和 dl 目录。
   • make dirclean：更彻底的清理，会删除 bin 和 build_dir 目录。
   • make distclean：最彻底的清理，等同于删除整个 openwrt 目录并重新 git clone。

2. 如何更新源码？ 当 OpenWrt 发布新版本或有重要更新时，你可以更新你的源码。

   cd openwrt
   git pull
   # 如果有冲突，可能需要解决
   # ./scripts/feeds update -a
   # ./scripts/feeds install -a
   # make menuconfig  # 检查一下配置是否需要调整
   # make -j$(nproc)

3. 如何添加自定义软件？ 你可以将软件源码放在 openwrt/package/ 目录下的一个自定义文件夹中（如 myapp），然后在该目录下创建 Makefile，编写编译规则，然后在 make menuconfig 中就能找到它。

4. 编译失败怎么办？

   • 仔细阅读错误日志：错误信息通常就在屏幕的最后几行。
   • 使用 V=s 参数：在 make 命令后加上 V=s，可以显示更详细的编译日志，方便定位问题。

     make -j$(nproc) V=s

恭喜你！如果你成功完成了以上所有步骤，你就已经掌握了 OpenWrt 自定义编译的核心技能，虽然第一次编译过程漫长，但当你看到自己亲手打造的、只包含所需功能的固件成功运行在路由器上时，那种成就感是无与伦比的。

祝你编译愉快！