INAV 在 Windows 10 下使用 VS Code + WSL 搭建开发环境的完整指南

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

本文面向所有在 Windows 10 上参与 INAV（Navigation-enabled flight control software）固件开发与调试的开发者。文章以仓库中的官方 IDE 配置指南（IDE - Visual Studio Code with Windows 10）为主体，完整讲解如何用 Visual Studio Code 与 WSL 协同完成代码浏览、智能提示、一键编译乃至硬件调试。读完本文，你将掌握.vscode下c_cpp_properties.json与tasks.json两套配置文件的完整含义、Ctrl+Shift+B快速编译任意 INAV target 的方法，以及这些配置背后的真实构建链路与源码依据。

为什么选择 VS Code + WSL

对 Windows 10 用户而言，Visual Studio Code 是免费且几乎零成本上手的选择。它与运行 Ubuntu 的 WSL（Windows Subsystem for Linux）几乎无缝集成，可以在 Windows 侧享受图形界面，同时让编译真正发生在 Linux 环境里，从而获得：

• 接近原生 Linux 的make/cmake/ninja工具链体验；
• 语法高亮与基于标签（tag）的符号跳转；
• 通过 WSL Remote 扩展实现的硬件调试能力（OpenOCD + GDB）。

注意：INAV 的官方推荐构建路径是先在 WSL 里搭好编译环境，再在 Windows 侧用 VS Code 打开工程。因此本文第 2 节会先给出 WSL 环境的最小搭建步骤，完整细节见仓库的 WSL 构建指南。

第一步：在 WSL 中准备 INAV 构建环境

本节的命令均应在 Ubuntu 的 shell 中执行（而非 Windows CMD/PowerShell）。

1. 启用 WSL：在 Windows 中运行windows features，勾选Windows Subsystem for Linux，重启；
2. 从 Microsoft Store 安装最新 Ubuntu LTS，并设置用户名与密码；
3. 更新软件源并安装构建工具：

sudo apt update sudo apt-get install git make cmake ruby python3 ninja-build

• cmake负责生成构建系统，make/ninja-build负责实际编译，ruby供仓库内的构建辅助脚本使用（见 src/utils 下的.rb脚本），python3用于生成文档与部分代码（见下文"更新自动化文档"）。

获取 INAV 源码（示例）

cd /mnt/c git clone https://github.com/iNavFlight/inav.git cd inav git checkout 6.1.1 # 切换到某个发布 tag git checkout -b my-branch # 创建自己的开发分支

若克隆时报chmod on /mnt/c/inav/.git/config.lock failed: Operation not permitted，可先卸载并重新挂载 C 盘（启用 metadata）：

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

一次性配置构建目录

cd /mnt/c/inav mkdir build && cd build cmake .. # 或使用 Ninja：cmake -GNinja ..

之后在build目录内即可按 target 编译，例如：

make MATEKF722 # 单 target make MATEKF405 MATEKF405SE # 多 target（Ninja 时为 ninja MATEKF722 MATEKF405SE SPEEDYBEEF405）

关于 target 的完整机制，可参考 docs/development/targets/overview.md：CMake 先读取src/main/target/<TARGET>/下的CMakeLists.txt与target.h，再据此选择 MCU 类型、闪存容量并裁剪驱动，最终链接生成 hex/bin。

第二步：安装 VS Code 并接入 WSL

1. 下载并安装 Visual Studio Code；
2. 在扩展市场安装Remote - WSL插件；
3. 用 VS Code 打开 INAV 仓库文件夹；
4. 按Ctrl + Shift + P打开命令面板，执行Remote-WSL: Reopen Folder in WSL，让整个工作区切换到 WSL 侧；
5. 若 Windows 防火墙弹窗询问权限，请允许；
6. 在 WSL 工作区中再安装两个插件：
   • C/C++（Microsoft cpptools）：提供IntelliSense、语法高亮与调试支持；
   • Bookmarks：用于在庞大代码库中快速标记和跳转。

第三步：配置 C/C++ 智能提示（c_cpp_properties.json）

编辑仓库根目录下的 .vscode/c_cpp_properties.json，以声明 INAV 源码中需要启用的宏定义（defines）与头文件搜索路径。仓库自带示例配置如下：

{ "configurations": [ { "name": "Win32", "includePath": [ "${workspaceRoot}", "${workspaceRoot}/src/main/**" ], "browse": { "limitSymbolsToIncludedHeaders": false, "path": [ "${workspaceRoot}/**" ] }, "intelliSenseMode": "msvc-x64", "cStandard": "c11", "cppStandard": "c++17", "defines": [ "USE_OSD", "USE_GYRO_NOTCH_1", "USE_GYRO_NOTCH_2", "USE_DTERM_NOTCH", "USE_ACC_NOTCH", "USE_GYRO_BIQUAD_RC_FIR2", "USE_D_BOOST", "USE_SERIALSHOT", "USE_ANTIGRAVITY", "USE_ASYNC_GYRO_PROCESSING", "USE_RPM_FILTER", "USE_GLOBAL_FUNCTIONS", "USE_DYNAMIC_FILTERS", "USE_DSHOT", "FLASH_SIZE 480", "USE_I2C_IO_EXPANDER", "USE_PCF8574", "USE_ESC_SENSOR" ] } ], "version": 4 }

关键字段解读

为什么这些 defines 很重要

INAV 的源码大量使用条件编译。例如 src/main/target/common.h 就根据MCU_FLASH_SIZE是否大于 512 KB 来决定是否启用USE_AUTO_TRANSITION、USE_TELEMETRY_MAVLINK等大体积功能，并在MCU_FLASH_SIZE <= 512时关闭USE_SERIALRX_SPEKTRUM、USE_TELEMETRY_SRXL等以节省闪存。同时，像USE_DSHOT、USE_GYRO_NOTCH_1这类功能开关需要先在defines里声明，编辑器才能正确解析对应代码分支——否则你会看到大量被#ifdef包裹的代码无法高亮、无法跳转。

仓库自带的 .vscode/c_cpp_properties.json 中defines还额外包含USE_PROGRAMMING_FRAMEWORK、USE_SERIALRX_GHST、USE_DJI_HD_OSD、USE_GYRO_KALMAN、USE_RANGEFINDER、USE_NAV、USE_SDCARD、USE_GYRO_FFT_FILTER、USE_ADAPTIVE_FILTER以及MCU_FLASH_SIZE 1024等更贴近现代 1 MB 闪存目标的宏集合。你可以以此为基准，针对自己正在开发的 target 增删宏。注意这里同时出现了FLASH_SIZE 480（示例旧值）与MCU_FLASH_SIZE 1024（仓库当前值）两种写法，二者本质都是模拟目标 MCU 的闪存容量，建议统一使用MCU_FLASH_SIZE（单位 KB）以匹配 common.h 中的判断逻辑。

小提示：如果你的编辑器提示缺少宏导致大量误报错误，优先从 src/main/target/common.h 与对应 target 的 target.h（例如src/main/target/MATEKF722/target.h）中复制真正的宏定义，这是保证 IntelliSense 与实际编译行为一致的最稳妥做法。

第四步：配置一键构建任务（tasks.json）

编辑仓库根目录下的 .vscode/tasks.json，即可通过Ctrl + Shift + B快捷键或命令面板执行构建。官方指南给出了四个典型任务：

{ "version": "2.0.0", "tasks": [ { "label": "Install/Update CMAKE", "type": "shell", "command": "mkdir -p build && cd build && cmake ..", "group": "build", "problemMatcher": [], "options": { "cwd": "${workspaceFolder}" } }, { "label": "Compile autogenerated docs", "type": "shell", "command": "python3 src/utils/update_cli_docs.py", "problemMatcher": [], "options": { "cwd": "${workspaceFolder}" } }, { "label": "Build Matek F722-WPX", "type": "shell", "command": "make MATEKF722WPX", "group": "build", "problemMatcher": [], "options": { "cwd": "${workspaceFolder}/build" } }, { "label": "Build Matek F405-STD & WING", "type": "shell", "command": "make MATEKF405 MATEKF405SE", "group": "build", "problemMatcher": [], "options": { "cwd": "${workspaceFolder}/build" } } ] }

四个任务分别做什么

• Install/Update CMAKE：首次进入工程时初始化构建目录（mkdir -p build && cd build && cmake ..），这一步只需执行一次；
• Compile autogenerated docs：运行 src/utils/update_cli_docs.py 重新生成 CLI 文档。该脚本读取 src/main/fc/settings.yaml 并输出到 docs/Settings.md，用于在你修改了飞控设置项后同步官方设置文档（详见 Development.md 中关于设置文档自动生成的表单）；
• Build Matek F722-WPX：单 target 编译示例。MATEKF722WPX在源码中确实存在，由 src/main/target/MATEKF722PX/CMakeLists.txt 通过target_stm32f722xe(MATEKF722WPX)注册；
• Build Matek F405-STD & WING：多 target 编译示例，一条命令编译MATEKF405与MATEKF405SE两个目标板，对应仓库中的 src/main/target/MATEKF405SE 目录。

自定义你自己的构建任务

把上面的make {TARGET}换成你要开发的板子即可，例如把make MATEKF722WPX改为make MATEKF722或make SPEEDYBEEF405。还可以基于 dev/vscode/tasks.json 中更完善的任务体系做扩展——仓库的 dev 配置把任务拆成了target、flash、svd、openocd-cfg、openocd-debug-prepare五步：

{ "label": "target", "type": "shell", "command": "make", "args": ["-C", "${config:BUILD_DIR}", "${config:TARGET}"], "problemMatcher": "$gcc", "group": { "kind": "build", "isDefault": true } }

并通过options.env.TARGET从 VS Code 的settings.json读取目标板参数。这套任务还衔接了 SVD 文件生成（svd_${config:TARGET}）、OpenOCD 配置生成（openocd_cfg_${config:TARGET}）与烧录（openocd_flash_${config:TARGET}），配合硬件调试方案使用（见下文）。

第五步：硬件调试（进阶）

完成以上配置后，你已具备完整的编译与代码浏览能力。若需要在线调试，仓库还提供了配套文档 Hardware Debugging in VSC on Windows 10 or 11 with WSL.md，核心思路是：

• 在 WSL 侧通过 OpenOCD 启动 GDB Server；
• 在launch.json中设置servertype: external，gdbTarget指向 Windows 宿主机的windows-host-ip:3333；
• 复用上述openocd-debug-prepare任务链（先svd、openocd-cfg、flash，再启动调试）。

该文档中的任务定义同样基于.vscode/tasks.json，与本文第 4 节是一脉相承的。

常见问题与排查

1.Syntax error: "(" unexpected

该错误通常由 Windows PATH 被注入 WSL 环境导致（常见于 WSL 1）。三种解法（详见 WSL 构建指南）：

• WSL 1：打开 RegEdit，将HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags从7改为5，重启后重新cmake ..；
• WSL 2：将同一键值从f（0x0f）改为d（0x0d）；
• 通用方案：在 WSL 中创建/etc/wsl.conf，写入[Interop]段并设置appendWindowsPath=false。

2. 编译非常缓慢

如果wsl -l -v显示发行版为 WSL 2，且源码位于/mnt/c挂载盘上，跨文件系统 I/O 会导致编译极慢（实测单 target 可能从 2.5 分钟恶化到 25 分钟）。推荐把仓库放到 Linux 文件系统（通过\\wsl$访问发行版目录）并映射网络驱动器；必要时可切换回 WSL 1：

wsl --set-version Ubuntu-20.04 1

3. IntelliSense 大量误报未定义符号

请先确认c_cpp_properties.json的defines是否覆盖了当前 target 实际启用的宏，并核对MCU_FLASH_SIZE数值是否与目标板闪存一致——common.h 中大量功能是围绕MCU_FLASH_SIZE分档的，数值不对会导致看到的条件编译分支与真实编译结果不一致。

小结

在 Windows 10 上开发 INAV 的推荐链路是：WSL 搭建工具链 → VS Code Remote-WSL 打开工程 →c_cpp_properties.json声明宏与头文件路径 →tasks.json实现一键编译。本文给出的两份配置（.vscode/c_cpp_properties.json与.vscode/tasks.json）均可在仓库根目录直接查阅，dev/vscode/tasks.json则提供了面向target/flash/svd/openocd的更完整任务链。以仓库中的真实 target（如MATEKF722、MATEKF405SE、MATEKF722WPX）替换任务命令中的目标板名，即可开始你的 INAV 开发。

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