在 Windows 10/11 下通过 WSL 构建 INAV 飞控固件：环境搭建、Make/Ninja 编译与故障排查实战指南

• 无人机
• 嵌入式
• 智能硬件

本文以 INAV（Navigation-enabled flight control software）仓库中的 Building in Windows 10 or 11 with Linux Subsystem（WSL） 文档为主体，系统讲解如何在 Windows 10/11 的 WSL 环境中搭建 INAV 交叉编译工具链、克隆源码、使用 Make 与 Ninja 两种构建系统编译目标固件、烧录到飞控并处理常见构建故障。读完本文，你可以在不离开 Windows 的前提下，拥有一个可重复、可排错的 Linux 构建环境，从零编译出MATEKF722、MATEKF405SE等任意目标固件。

为什么在 Windows 上推荐用 WSL 构建 INAV

INAV 的固件工程是一个典型的 CMake 驱动的嵌入式交叉编译项目，根级 CMakeLists.txt 声明的cmake_minimum_required(VERSION 3.13...3.18)说明它依赖较新的 CMake，并要求gcc-arm-none-eabi交叉编译器、make（或ninja）、ruby、python3等一系列 Linux 生态工具。在 Windows 原生环境里逐个安装并配置这些工具相当繁琐，而 Linux 子系统（WSL）提供了一套接近原生的 Linux shell，因此官方文档将其评价为"probably the simplest way of building INAV under Windows"——它省去了 Cygwin / MSYS2 等方案的兼容层负担，是官方推荐的 Windows 构建路径。

WSL 方案的核心优势在于：

• 直接在 Ubuntu 的apt中安装git、make、cmake、ruby等构建工具，无需手工处理 Windows 安装包的路径与依赖；
• CMake 在cmake ..阶段会自动检测并下载 INAV 内嵌的 ARM 官方交叉编译器，路径问题由构建脚本统一处理（详见下文"编译器自动下载"一节）；
• 与 Building in Linux 文档共用同一套构建流程，后续升级工具链、批量构建多目标都很自然。

环境准备：启用 WSL 并安装 Ubuntu

第一步：启用 Windows 功能

在 Windows 10/11 上执行以下操作：

1. 运行windows features（在开始菜单搜索"启用或关闭 Windows 功能"并打开）；
2. 勾选"适用于 Linux 的 Windows 子系统"（Windows Subsystem for Linux）；
3. 重启电脑使功能生效。

说明：新式 WSL 发行版在第一次启动时会自动处理 WSL2 内核与虚拟化平台依赖；如果系统提示需要安装内核更新包，按提示完成安装即可。

第二步：安装 Ubuntu

1. 打开 Microsoft Store，搜索并安装最新版本的Ubuntu LTS（如 Ubuntu 20.04 LTS / 22.04 LTS）；
2. 下载完成后点击Launch Ubuntu启动；
3. 首次启动会提示创建 UNIX 用户名与密码，务必牢记，后续在 WSL 中使用sudo均需要此密码；
4. 创建完成后即进入 Linux 命令行提示符。

从这一步开始，本文的所有命令都输入到Ubuntu shell 窗口中，而不是 Windows 的 PowerShell 或 CMD。

第三步：更新软件源并安装构建工具

进入 Ubuntu shell 后，先更新软件包索引：

sudo apt update

再安装构建 INAV 所需的核心工具：

sudo apt-get install git make cmake ruby

此外还需要 Python 3（用于更新文档，见下文"更新文档"小节）：

sudo apt-get install python3

各工具在 INAV 构建流程中的职责如下（与 Building in Linux 文档一致）：

CMAKE 与 Ubuntu 18.04 的版本陷阱

INAV 需要 CMake3.13 或更高版本，而 Ubuntu 18.04 LTS 仓库中的 CMake 版本过旧，无法满足要求。若你安装的是 Ubuntu 18.04，最快的方式是卸载后从 Microsoft Store 重新安装 Ubuntu 20.04 LTS（官方文档给出了该版本的 Store 产品链接，产品 ID 为9N6SVWS3RX71）。从 CMakeLists.txt 可以看到项目的最低版本约束写死在构建脚本中，因此升级系统版本是比手工升级 CMake 更省心的选择。

下载 INAV 源码仓库

INAV 仓库默认存放在 Windows 的 C 盘根目录，这样可以直接在 Windows 资源管理器 / VSCode 中编辑源码，同时在 WSL 中编译。

# 挂载 Windows C 盘（WSL 自动挂载路径） cd /mnt/c # 克隆 INAV 仓库 git clone https://github.com/iNavFlight/inav.git # （可选）切换到指定版本标签，例如 INAV 6.1.1 git checkout 6.1.1 # （可选）基于该版本创建自己的分支 git checkout -b my-branch

完成后，C 盘根目录下会多出一个inav文件夹，它同时被 Windows 和 WSL 可见，可以直接用 Windows 编辑器修改源码，随后在 WSL 中编译。

注意：官方文档中的git clone使用 GitHub 地址。若你的网络环境访问 GitHub 受限，可将源码克隆到本地后切换到相应分支继续后续步骤；仓库的构建流程不依赖克隆来源，只依赖源码内容本身。

克隆报错：chmod on /mnt/c/inav/.git/config.lock failed

某些 Windows 安装上克隆 INAV 时会遇到如下错误：

Cloning into 'inav'... error: chmod on /mnt/c/inav/.git/config.lock failed: Operation not permitted fatal: could not set 'core.filemode' to 'false'

原因是 WSL 对drvfs（Windows 挂载盘）默认不启用 POSIX 元数据。解决办法是重新挂载 C 盘并开启metadata选项：

sudo umount /mnt/c sudo mount -t drvfs C: /mnt/c -o metadata

挂载完成后重新执行克隆即可。

构建 INAV：两种构建系统详解

INAV 自 2.6 起全面转向 CMake：CMake 负责生成构建文件，构建管理器（make或ninja）负责实际编译。因此必须先执行一次cmake配置，之后即可反复编译。

使用 Make 构建（传统方式）

先进入 INAV 目录，只需一次执行以下命令准备构建环境（除非重装 WSL 或 CMake）：

cd /mnt/c/inav mkdir build cd build cmake ..

cmake ..中的..是必需的，它告诉 CMake 到哪里寻找规则集（根级 CMakeLists.txt）。CMake 完成配置后会在build目录生成CMakeCache.txt与Makefile。

随后编译指定目标：

cd build make MATEKF722

MATEKF722是 INAV 众多目标（target）中的一个。若不加目标直接运行make，默认会构建所有目标（通常有上百个，耗时很长），因此日常使用务必显式指定目标名。查看全部可用目标可以用make help | less分页浏览。

使用 Ninja 构建（推荐）

Ninja 是轻量级且默认并行执行的跨平台构建工具，比传统的 Make 方式更快，官方文档建议优先使用 Ninja。

先在 Ubuntu 中安装 Ninja：

sudo apt-get install ninja-build -y

然后按以下步骤配置并构建：

cd /mnt/c/inav mkdir build cd build # 指定使用 Ninja 作为构建系统 cmake -GNinja ..

以后每次编译只需在build目录内调用：

ninja MATEKF722

若要一次构建多个目标：

ninja MATEKF722 MATEKF405SE SPEEDYBEEF405

从源码结构看，INAV 的 CMake 体系对 Ninja 有完整支持：cmake/main.cmake 中的collect_targets()会汇总所有有效的目标名生成构建入口，Ninja 与 Make 在目标语义上完全一致；cmake/stm32.cmake、cmake/rp2350.cmake、cmake/sitl.cmake等模块内部也大量出现ninja生成器命令，印证 Ninja 已是项目构建的主力路径之一。

编译器自动下载：cmake背后的交叉工具链机制

执行cmake ..时，构建系统会先检查本机是否存在arm-none-eabi-gcc。在 cmake/arm-none-eabi.cmake 中，工具链被定义为arm-none-eabi-gcc系列工具，并预设了Debug / Release / RelWithDebInfo三种构建类型。而 cmake/arm-none-eabi-checks.cmake 实现了"版本检查 + 自动下载"的完整流程：

• 期望版本固定为13.2.1（arm-none-eabi_gcc_version），对应 ARM 官方工具链包名arm-gnu-toolchain-13.2.rel1；
• 若本机找不到交叉编译器，或COMPILER_VERSION_CHECK=ON（默认开启）且版本不符，脚本会从 ARM 官方地址下载对应平台的压缩包（Windows 的mingw-w64-i686-arm-none-eabi.zip、Linux x86_64 的x86_64-arm-none-eabi.tar.xz等），校验 MD5 后解压到tools/目录，并自动把tools/arm-gnu-toolchain-13.2.rel1/bin加入 PATH；
• 若你希望使用发行版自带的交叉编译器（如 Arch 上更新的版本，或 ARM 官方未提供 32 位平台的编译包），可以用cmake -DCOMPILER_VERSION_CHECK=OFF ..跳过版本强校验。

这意味着在全新 WSL 环境里，你不需要手工安装ARM 交叉编译器——cmake ..这一步会替你完成。

Release 模式与磁盘占用

INAV 默认以RelWithDebInfo构建类型编译（对应-ggdb3 -DNDEBUG，见 cmake/arm-none-eabi.cmake），包含大量调试符号。如果只构建单个目标影响不大，但要批量构建所有目标或用于 CI，磁盘消耗非常可观（官方 Linux 构建文档给出的参考数据：全部目标约 109 GB）。对于生产环境、CI 或批量构建，建议使用 Release 模式：

cd /mnt/c/inav mkdir build-release cd build-release cmake -DCMAKE_BUILD_TYPE=Release .. # 构建指定目标 make MATEKF405 # 或构建全部正式发布目标（对应 cmake/main.cmake 中的 release 聚合目标） make release

两种模式下最终产出的.hex/.bin固件是等价的，Release 只是省略了中间调试符号，因此可以放心用于刷写。

清理与缓存维护

与 Linux 构建流程一致，WSL 下同样支持清理操作：

# 清理所有构建产物 make clean # 只清理单个目标 make clean_MATEKF405 # 清理多个目标 make clean_MATEKF405 clean_MATEKF722

CMake 会缓存构建环境，因此编译不同目标时无需反复执行cmake。若需维护缓存，可使用make edit_cache或make rebuild_cache（典型场景是在内嵌 ARM 编译器与发行版编译器之间切换）。

更新文档（可选）：运行 CLI 文档生成脚本

INAV 仓库提供了一个从源码生成 CLI 相关文档的脚本。在 WSL 中执行：

cd /mnt/c/inav python3 src/utils/update_cli_docs.py

该脚本位于 src/utils/update_cli_docs.py，依赖前面安装的python3，它会扫描源码中的 CLI 定义并更新对应文档。

烧录固件到飞控

编译完成后，产物（.hex文件）位于build目录下，对应 Windows 路径为c:\inav\build。烧录方式有两种：

1. 图形界面（推荐新手）：启动 Windows 版 INAV Configurator，在固件刷写（Firmware Flasher）界面选择Load firmware [Local]，浏览到c:\inav\build选择本地.hex文件刷写；
2. 命令行：也可以参考 Linux 构建文档，使用stm32flash或dfu-util等工具直接从命令行烧录。

Troubleshooting：常见故障与解决方案

故障一：Syntax error: "(" unexpected

典型报错（以make MATEKF722SE为例）：

Generating MATEKF722SE/settings_generated.h, MATEKF722SE/settings_generated.c /bin/sh: 1: Syntax error: "(" unexpected make[3]: *** [src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/build.make:63: .../settings_generated.h] Error 2

原因：Windows 的 PATH 被注入到了 WSL 的 shell 环境中，导致某些构建步骤（如调用脚本生成settings_generated.h/c）在解析命令时看到 Windows 风格的路径或命令而报语法错误。

解法 A——修改注册表 Flags（WSL 1）：

1. 打开 WindowsRegEdit；
2. 定位到HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags；
3. WSL 1 默认值为7，将其改为5；
4. 重启 WSL（最好同时重启 Windows）；
5. 重新进入构建目录执行cmake ..后make {TARGET}，应可恢复正常。

解法 B——修改注册表 Flags（WSL 2）：

1. 同上打开RegEdit并定位到同一个Flags键；
2. WSL 2 默认值为0x0000000f（15），在 Base Hexadecimal 下改为d（13）；
3. 重启 WSL 与 Windows；
4. 重新执行cd build && cmake .. && make {TARGET}。

解法 C——禁用 Windows PATH 注入（通用，推荐）：

在 WSL 内创建/etc/wsl.conf：

cd /etc/ sudo nano wsl.conf

在文件中写入：

[Interop] appendWindowsPath=false

保存（Ctrl+O，回车确认文件名），退出（Ctrl+X），重启 WSL 与 Windows，然后重新配置构建环境：

cd build cmake .. make {TARGET}

该方案适用于 WSL 1 与 WSL 2 两种版本，是从根源上切断 Windows PATH 干扰的通用做法。

故障二：构建目标非常缓慢

如果出现"新电脑编译反而比旧电脑慢得多"的反直觉现象（原文档举例：i7-10750 编译单个目标约 25 分钟，而 i3-4030 仅需约 2.5 分钟），通常与 WSL 版本和文件系统位置有关。

先在提升权限的 PowerShell 窗口中检查：

wsl -l -v

如果输出显示发行版运行在WSL 2下，且你的源码位于 Windows 挂载盘（/mnt/c），就会触发跨文件系统 I/O 的性能瓶颈——WSL 2 在"读 Windows 盘上的文件"这一场景下远比 WSL 1 慢。两个解决方案：

方案一：把源码放到 Linux 文件系统（官方推荐）

1. 确保发行版正在运行；
2. 在 Windows 文件资源管理器地址栏输入\\wsl$，找到你的发行版，将网络驱动器映射到该发行版；
3. 在发行版内部，源码放在主目录/home/你的用户名/下，例如创建GitHub目录存放仓库；
4. 若之后 VSCode 写入目录权限不足，在发行版 shell 中执行：

sudo chown -R 你的用户名 GitHub

其中你的用户名是创建发行版时设置的用户，GitHub是存放仓库的根目录。之后编译会明显提速。

方案二：切回 WSL 1

在提升权限的 PowerShell 中执行（以发行版名Ubuntu-20.04为例）：

wsl --set-version Ubuntu-20.04 1

转换完成后重启系统，下一次编译即可恢复 WSL 1 的文件访问速度。

小结：从零到烧录的完整命令速查

将以上步骤汇总为一张速查表，方便在全新 WSL 环境中一次性走通：

# 1. 环境准备（Ubuntu shell） sudo apt update sudo apt-get install git make cmake ruby python3 sudo apt-get install ninja-build -y # 使用 Ninja 时需要 # 2. 克隆源码（放在 /mnt/c 或 Linux 主目录均可） cd /mnt/c git clone https://github.com/iNavFlight/inav.git cd inav git checkout 6.1.1 # 可选：切换版本 # 3. 配置构建环境（仅首次需要） mkdir build cd build cmake -GNinja .. # 或 cmake ..（Make 方式） # 4. 编译目标 ninja MATEKF722 # 或 make MATEKF722 ninja MATEKF722 MATEKF405SE # 多目标并行编译 # 5. 烧录：Configurator 中 Load firmware[Local] 选择 c:\inav\build 下的 .hex

在此基础上，Building in Linux 提供了更完整的 Linux 侧构建细节（编译器选择、多目标并行make -j、缓存维护、更新与重建流程），可作为进一步查阅的扩展资料；开发总览 则覆盖更深入的 Git 工作流与开发规范。现在你已经拥有了一套可在 Windows 上稳定复现的 INAV 固件构建环境，可以自由切换到任何目标板、任何版本分支进行编译与烧录验证。

• 无人机
• 嵌入式
• 智能硬件