十分钟装好第一个第三方插件：Flipper Zero Unleashed 固件 FAP 体系完整入门

【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware

熟悉设备基本操作之后，大约五分钟就能把一个下载好的第三方插件放进 Flipper Zero Unleashed 固件，对应的 FAP 包会出现在主菜单里，点开即用。本文先讲清 FAP 格式在系统中的加载原理，再按新手、开发者、WiFi 模块用户三类路径走通安装流程，最后给出一套能真正编译并推送到设备验证的最小自研应用。

📦 FAP 到底是什么，以及为什么不用重刷固件

FAP（Flipper App Package）本质上是一个 ELF 可执行文件，把应用的代码、资源与元数据捆绑在一起。内置应用是随固件一起编译、固化在 Flash 里的；FAP 则独立存放在 SD 卡上，由系统内置的App Loader从卡中读出，校验完整性与兼容性后拷入 RAM、修正地址，再启动。这意味着增删一个插件不需要重新编译或刷写固件，单个 FAP 出问题时也不会波及系统其余部分，装完即生效，随时可撤。

有一个容易忽略的细节值得提前知道：FAP 运行在 RAM 中，应用可用的堆空间会比同一段代码以内置方式运行在 Flash 里时略小。自己开发吃内存的应用时，要把这点余量算进去。

确认 API 版本是否匹配、apps 目录是否就位

安装前检查两件事。

一是 API 版本。在设备的「设置 > 系统 > 关于」里查看 API 版本；每个 FAP 的清单里记录了fap_version，App Loader 会比较主版本号，一致才允许加载。拿到别人编译的 FAP 时，先核对双方版本号，不要直接硬试。

二是目录结构。在 SD 卡上建一个名为apps的顶层文件夹，FAP 文件放进去即可，也可以按用途再分子目录存放，子目录同样会被扫描。文件后缀必须是.fap。

一次完整的 FAP 安装：从下载点到启动

以新手路径为例，完整操作就是三个动作：

1. 从可信来源下载 FAP，确认文件名以.fap结尾；
2. 把 SD 卡插到读卡器，将文件拷入 apps 文件夹，安全弹出；
3. 卡插回 Flipper Zero，重启设备，新应用出现在主菜单的应用分类中，点击即可启动。

整个过程通常在十分钟以内。

新手路径：SD 卡复制

上面就是新手路径的全部。适合第一次接触外部应用、手头没有开发环境的人，也是排障时最好回退的基线操作。

开发者路径：fbt 编译并推送

手上有源码时可以跳过读卡步骤。把应用源码放在applications_user目录下，在仓库根目录执行./fbt launch APPSRC=applications_user/你的应用文件夹，fbt 会解析应用清单、编译出 FAP 并通过 USB 推到设备运行。默认的 VS Code 构建配置把这条命令预置成了构建按钮，开发期改一行代码、再按一次组合键就能看效果。

WiFi 模块路径：应用商店直接安装

扩展坞上接了可用的 WiFi 模块时，整条链路可以完全离开电脑。在设备上进入「应用 > 应用商店」，浏览分类、点击安装，系统自行完成下载与放置。对已经联网的设备来说，这是摩擦最少的一条路。

🔧 四步做出一个最小 FAP 应用

动手部分做一个只会在屏幕上画一行文字的hello_world应用，走一遍「目录 → 清单 → 代码 → 编译」的完整链路。

1. 创建应用目录

mkdir -p applications_user/hello_world

fbt 构建体系会把applications_user下的目录识别为外部应用，目录结构与仓库内置应用一致。

2. 编写应用清单 application.fam

App( appid="hello_world", apptype=FlipperAppType.EXTERNAL, name="Hello World", entry_point="hello_world_app", sources=["hello_world.c"], fap_version="1.0", stack_size=1024, )

apptype必须写FlipperAppType.EXTERNAL，构建产物才会按 FAP 处理；entry_point指向 C 代码里的入口函数名；fap_version决定兼容性声明，字段全集见后文学习资源中的清单规范。

3. 编写 C 代码

#include <furi.h> #include <gui/gui.h> static void draw(Canvas* canvas, void* ctx) { UNUSED(ctx); canvas_draw_str(canvas, 10, 30, "Hello FAP"); } void hello_world_app(void* p) { UNUSED(p); Gui* gui = furi_record_open(RECORD_GUI); ViewPort* vp = view_port_alloc(); view_port_draw_callback_set(vp, draw, NULL); gui_add_view_port(gui, vp, GuiLayerFullscreen); while (true) furi_delay_ms(50); }

最小样本只负责开一个 ViewPort 并持续绘制；退出与清理逻辑可以等跑通后再补。

4. 编译并推送到设备

./fbt fap_hello_world ./fbt launch APPSRC=applications_user/hello_world

第一条只编译，产物.fap落在构建目录的.extapps下（例如build/f7-firmware-D/.extapps），可以手动拷进 SD 卡的 apps 文件夹；第二条编译后经 USB 直接推送到设备运行。

排障：三个常见现象与对应动作

应用列表里看不到新装的 FAP

现象：重启后列表里没有新应用的踪影。原因：文件不在 apps 及其子目录内、后缀不是.fap，或文件名含异常字符。动作：先核对路径层级与文件名，再重启设备刷新列表。

应用启动即崩溃或提示内存不足

现象：点开应用立刻退出，或系统报内存错误。原因：FAP 运行在 RAM，可用堆本来就比内置应用小；stack_size配得过大、或持有大块缓冲时更容易触发。动作：关闭不需要的后台应用，回查清单里的栈尺寸设置，再检查代码里的分配是否可以收缩，改完重新编译。

启动时报 API 版本不匹配

现象：启动时给出明确的版本错误提示。原因：FAP 的fap_version与固件的主 API 版本不一致，App Loader 拒绝加载。动作：在「关于」页确认固件当前 API 版本，把清单里的fap_version对齐到同一主版本后重新编译；若应用引用了新版本已移除的符号，按符号表提示逐项调整代码。

🚀 延伸：图标、资源打包与 JS 开发路线

应用想有自己的图标，就在应用文件夹里放一个图片子目录，在清单的fap_icon_assets字段指定它，构建时会连同源码一起预处理图片；源码里#include生成的{APPID}_icons.h之后，引用方式和主固件的图标完全一样。

应用需要随包附带数据或配置文件时，用resources字段指定一个文件夹名，内容会随应用打包进 FAP。

更习惯 JavaScript 的话，可以直接走 JS SDK 路线：用npx @flipperdevices/create-fz-app@latest生成项目模板，之后每次npm start就把脚本推送上机运行，编辑器里还有 Flipper 接口的代码补全，不必为每个调用翻文档。

不自己开发的话，社区积累较多的方向有五类：红外遥控码库扩展、NFC 卡片工具、SubGHz 遥控、移植小游戏、设备诊断工具。挑一个方向先装上，比通读文档更快建立手感。

📚 学习资源

• FAP 与 SD 卡应用指南：加载原理、API 版本机制与调试方法
• 应用清单规范：application.fam 全部字段含义
• JS SDK 开发指南：模板创建与推送流程
• fbt 构建工具手册：构建目标与命令列表

结语

插件体系没有想象中复杂：把 FAP 放到正确的位置，或者自己用一条命令编译出来。挑一个想先用的方向，从可信来源拿一个来验证，剩下的交给设备自己。

【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware