• 开箱即用: 基于官方 ImageBuilder,几分钟生成固件
• 模块化: 内置常用模块,支持自定义模块目录
• 一键构建: 图形界面或脚本命令,实时日志与进度
• 容器化: Docker 隔离构建环境,无需配置编译工具链
• 配置可复用: 多套构建方案,环境变量集中管理

• 从发布页下载预编译安装包: Releases

也可从源码构建:见文档后半部分"开发与构建"。

注意:使用 GUI 构建固件前,请先安装并启动 Docker。

安装步骤:

0. 安装并启动 Docker(必需)

   • Linux: sudo apt install docker.io 或 sudo pacman -S docker
   • macOS/Windows: 下载 Docker Desktop

1. 下载并安装 OpenWrt Builder

   • Linux (.deb): sudo dpkg -i openwrt-builder_*.deb
   • Linux (.AppImage): chmod +x OpenWrt-Builder-*.AppImage
   • macOS: 打开 .dmg 文件并拖拽到应用程序
   • Windows: 运行 .msi 安装包

2. 选择镜像(OpenWrt/ImmortalWrt)与目标平台/版本

3. 在"模块"页面勾选需要的功能模块

4. 可选:设置输出目录、镜像加速等

5. 在"构建中心"一键构建,等待完成

提示:首次构建会下载较多资源,后续会显著加快。

Linux/macOS: 在仓库根目录使用 run.sh:

# 查看帮助
./run.sh --help
# 最小示例(以 ImmortalWrt Rockchip 为例)
./run.sh \
 --image=immortalwrt/imagebuilder:rockchip-armv8-openwrt-23.05.1 \
 --profile=friendlyarm_nanopi-r2s \
 --with-pull --rm-first --use-mirror

Windows: 在仓库根目录使用 PowerShell 执行 run.ps1:

# 查看帮助
.\run.ps1 -Help
# 最小示例(以 ImmortalWrt Rockchip 为例)
.\run.ps1 `
 -Image "immortalwrt/imagebuilder:rockchip-armv8-openwrt-23.05.1" `
 -Profile "friendlyarm_nanopi-r2s" `
 -WithPull -RmFirst -UseMirror

常用参数:

Linux/macOS (Bash):

--image=... 指定 ImageBuilder 镜像(必需)
--profile=... 指定设备 Profile(可选)
--output=... 指定输出目录(默认:./bin)
--custom-modules=... 指定自定义模块目录(默认:./custom_modules)
--with-pull 构建前拉取镜像
--rm-first 构建前清理容器
--use-mirror 使用镜像加速(默认启用)
--mirror=... 指定镜像站域名,例如 mirrors.pku.edu.cn

Windows (PowerShell):

-Image "..." 指定 ImageBuilder 镜像(必需)
-Profile "..." 指定设备 Profile(可选)
-Output "..." 指定输出目录(默认:./bin)
-CustomModules "..." 指定自定义模块目录(默认:./custom_modules)
-WithPull 构建前拉取镜像
-RmFirst 构建前清理容器
-UseMirror 使用镜像加速(默认启用)
-Mirror "..." 指定镜像站域名,例如 mirrors.pku.edu.cn

环境变量(.env)示例:

# 在默认模块集基础上增减
MODULES="openclash lan pppoe -tools"
# 或完全覆盖默认模块集(更高优先级)
ENABLE_MODULES="argon base lan"
# 系统环境变量默认启用,模块可直接引用根 .env 中的变量
# 传递给 ImageBuilder 的常见参数
CONFIG_TARGET_KERNEL_PARTSIZE=32
CONFIG_TARGET_ROOTFS_PARTSIZE=256

输出目录默认为 ./bin,可通过 --output 修改。

• 默认模块集: add-all-device-to-lan argon base opkg-mirror prefer-ipv6-settings statistics system tools
• 两种选择方式:
  • ENABLE_MODULES: 完全覆盖启用模块列表
  • MODULES: 在默认模块集基础上增减(前缀 - 表示排除)
• 模块目录:同时支持 modules/(内置)与 custom_modules/(自定义)
• 目录结构:

my-module/
├─ packages # 依赖包(空格分隔或可执行脚本)
├─ files/ # 随固件打包进系统的文件
├─ post-files.sh # 可选:files 拷贝后处理
├─ .env # 可选:模块级变量
└─ README.md # 可选:模块说明

高级特性:

• 环境变量共享:模块可直接引用根 .env 中的变量(默认启用)
• 变量替换:files/etc/uci-defaults 下的文件支持 $VARNAME 替换
• 冲突保护:若不同模块生成同名目标文件,构建会失败以避免覆盖

通用问题:

• 构建很慢/网速受限?建议启用 --use-mirror 或指定 --mirror=mirrors.pku.edu.cn
• 没有安装 Docker?请先安装 Docker Desktop(macOS/Windows)或 Docker Engine(Linux)
• 构建完成后产物在哪?默认在 ./bin(可通过 --output 修改)
• GUI 构建失败/无响应?请确认 Docker 已安装并正在运行;从源码运行还需 Node.js 18+ 与 pnpm 8+,详见下文"开发与构建"

Windows 特定问题:

• PowerShell 脚本无法执行?运行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 允许脚本执行
• 提示找不到 Docker?确保 Docker Desktop 已安装并正在运行,尝试重启终端
• 构建权限问题?确保以管理员权限运行 PowerShell 或 Docker Desktop
• 中文路径问题?建议将项目放在英文路径下,避免中文目录名

Linux 特定问题:

• AppImage 无法运行?运行 sudo apt install fuse 安装 FUSE 支持
• 没有 Docker 权限?将用户加入 docker 组:sudo usermod -aG docker $USER,然后重新登录
• .deb 安装失败?运行 sudo apt-get install -f 修复依赖关系
• GUI 应用无法启动?确保已安装桌面环境和必要的系统库

目录结构:

.
├─ build.sh # 容器内实际构建脚本(跨平台通用)
├─ run.sh # Linux/macOS 构建脚本(Docker Compose)
├─ run.ps1 # Windows PowerShell 构建脚本
├─ modules/ # 内置模块库
├─ custom_modules/ # 建议放置自定义模块
├─ setup/ # 构建前置设置脚本
├─ tauri-app/ # GUI 应用(Tauri 2 + Vue 3)
└─ LICENSE # MIT 许可证

GUI 从源码运行与打包:

cd tauri-app
pnpm install
# 开发(Tauri 调试,固定端口 1420)
pnpm tauri dev
# 生产打包(生成桌面安装包)
pnpm tauri build

平台特定构建要求:

Windows:

• 安装 Rust toolchain(包含 MSVC 工具链)
• 安装 Visual Studio Build Tools 或 Visual Studio
• 确保 PowerShell 5.1+ 或 PowerShell Core 7+

Linux:

• 安装系统开发工具:sudo apt install build-essential
• 安装 GTK 开发库:sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
• 安装其他依赖:sudo apt install libappindicator3-dev librsvg2-dev patchelf

macOS:

• 安装 Xcode Command Line Tools:xcode-select --install

说明:打包会将仓库根的 build.sh、run.sh、run.ps1、setup/、modules/ 作为资源一并包含。各平台将自动生成对应的安装包格式(.dmg/.msi/.deb/.AppImage)。

• Bug 报告: 提交 Issue
• 功能建议: 功能请求
• 代码贡献: 提交 Pull Request
• 文档完善: 完善 README 和 Wiki
• 模块分享: 分享你的自定义模块

本项目基于 MIT 协议发布,详见 LICENSE。