悠米是只猫

logo
悠米是只猫🐱
一切顺其自然~

OpenWrt 源码编译完全指南：从 Linux 到 WSL 和 macOS

2025/12/14
#网络配置 #宽带 #Packages #Openwrt #源代码 #系统 #网络 #IP地址 #子网掩码 #服务器
14
0

OpenWrt 是一个高度模块化、功能强大的开源路由器操作系统。通过自行编译固件，你可以获得完全定制的功能，去除不必要的软件包以提升性能，或集成特定硬件驱动。本文将详细介绍在不同操作系统环境下编译 OpenWrt 的完整流程。

核心原则与准备

在开始之前，请务必牢记两点：

  1. 不要使用 root 用户进行编译，请在普通用户权限下操作。
  2. 确保网络连接正常稳定，编译过程需要下载大量源码和工具。

推荐使用 Debian 或 Ubuntu LTS 22/24 作为编译主机系统。

第一部分：标准 Linux 环境编译

这是最推荐也是问题最少的编译方式。

步骤一：安装系统与编译依赖

首先，安装一个干净的 Linux 系统。然后，打开终端，执行以下命令安装所有必要的依赖包：

sudo apt update -y
sudo apt full-upgrade -y
sudo apt install -y ack antlr3 asciidoc autoconf automake autopoint binutils bison build-essential \
bzip2 ccache clang cmake cpio curl device-tree-compiler flex gawk gcc-multilib g++-multilib gettext \
genisoimage git gperf haveged help2man intltool libc6-dev-i386 libelf-dev libfuse-dev libglib2.0-dev \
libgmp3-dev libltdl-dev libmpc-dev libmpfr-dev libncurses5-dev libncursesw5-dev libpython3-dev \
libreadline-dev libssl-dev libtool llvm lrzsz libnsl-dev ninja-build p7zip p7zip-full patch pkgconf \
python3 python3-pyelftools python3-setuptools qemu-utils rsync scons squashfs-tools subversion \
swig texinfo uglifyjs upx-ucl unzip vim wget xmlto xxd zlib1g-dev

步骤二：获取源码与配置

  1. 克隆 openwrt 源码仓库（一个流行的 OpenWrt 分支）：

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

  2. 更新并安装所有可用的软件包源（feeds）：

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

  3. 进入图形化配置界面，选择你需要的目标平台、型号和软件包：

    make menuconfig

    （在菜单中，Target System 选择硬件平台，Subtarget 选择子类型，Target Profile 选择具体型号。在 LuCI -> Applications 中选择需要的网页管理界面插件。）

步骤三：下载与编译

  1. 下载所有编译所需的 dl 库（软件包源码）：

    make download -j8  # 使用8个并行任务加速下载

  2. 开始编译固件。首次编译强烈建议使用单线程，以便于排查错误：

    make V=s -j1

    V=s 表示输出详细的编译信息，出错时更容易分析。

编译成功后的固件输出路径为：bin/targets/。

第二部分：二次编译与清理

如果你已经编译过，并想更新源码或修改配置：

cd openwrt
git pull  # 拉取最新源码
./scripts/feeds update -a
./scripts/feeds install -a
make defconfig  # 应用旧的配置到新源码
make download -j8
make V=s -j$(nproc)  # 使用所有CPU核心进行编译

如果需要彻底重新配置：

rm -rf .config  # 删除旧配置
make menuconfig # 重新配置
make V=s -j$(nproc)

注意：本套代码保证可以编译成功。你可以自由使用，但基于此源码二次发布时，请注明原始 GitHub 仓库链接。

第三部分：在 WSL/WSL2 (Windows) 中编译

在 WSL 中编译需要注意两个特殊问题。

环境变量问题

WSL 的 PATH 可能混入带空格的 Windows 路径，导致编译失败。解决方法是在所有 make 命令前修正 PATH：

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin make V=s -j$(nproc)

文件系统大小写敏感问题

WSL 挂载的 NTFS 驱动器默认不区分大小写，而 OpenWrt 编译必须在区分大小写的文件系统上进行。

解决方案（在Windows中进行）：

  1. 以管理员身份打开 PowerShell。

  2. 为你计划存放代码的目录提前启用大小写敏感特性：

    fsutil.exe file setCaseSensitiveInfo <your_local_openwrt_path> enable

    请将 <your_local_lede_path> 替换为你本地的真实路径，例如 C:\Users\Name\lede。

  3. 将源码克隆到这个已启用大小写敏感的目录中：

    git clone https://github.com/openwrt/openwrt <your_local_lede_path>

重要：此命令仅对目录之后新增的文件生效。对已克隆完成的项目目录执行此命令无效。

第四部分：在 macOS 中编译

在 macOS 上编译需要使用 Homebrew 来提供 GNU 工具链，替换掉 macOS 自带的 BSD 工具链。

步骤一：安装 Xcode 与 Homebrew

  1. 从 AppStore 安装 Xcode。

  2. 安装 Homebrew（包管理器）：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步骤二：安装编译工具与依赖

brew unlink awk
brew install coreutils diffutils findutils gawk gnu-getopt gnu-tar grep make ncurses pkg-config wget quilt xz
brew install gcc@11

步骤三：配置环境变量

根据你的 Mac 芯片类型，将 GNU 工具路径加入到环境变量最前面。

  • 对于 Intel 芯片的 Mac，将以下命令逐行执行或添加到 ~/.bashrc 或 ~/.zshrc：

    echo 'export PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/findutils/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/gnu-getopt/bin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/gnu-tar/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/grep/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> ~/.bashrc

  • 对于 Apple Silicon (M系列) 芯片的 Mac，路径前缀改为 /opt/homebrew/opt：

    echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"' >> ~/.bashrc
echo 'export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"' >> ~/.bashrc
# ... 其他路径类比修改

步骤四：应用配置并编译

  1. 让配置生效：

    source ~/.bashrc  # 如果使用 zsh，则是 source ~/.zshrc

  2. 输入 bash 启动一个 bash shell（确保环境一致）。

  3. 现在，你可以按照本文 第一部分“标准 Linux 环境编译” 中的步骤开始编译了。

总结

无论是纯 Linux、Windows 下的 WSL 还是 macOS，都可以成功编译 OpenWrt。关键在于：

  1. 满足系统依赖：确保所有必要的工具链和开发包已安装。
  2. 解决环境特性问题：WSL 注意大小写敏感，macOS 注意替换 GNU 工具链。
  3. 耐心排查：首次编译使用 -j1 单线程和 V=s 详细输出，遇到错误时根据提示搜索解决方案。

编译过程可能需要较长时间（通常1-4小时，取决于网络和CPU性能），请耐心等待。当你在 bin/targets 目录下看到编译好的固件时，所有的努力都是值得的。祝你编译顺利！