1. 为什么要在优麒麟上折腾 Flatpak 打包优麒麟Ubuntu Kylin作为国内用户接触较多的桌面 Linux 发行版之一底层依然是标准的 Debian/Ubuntu 体系软件生态主要依赖 apt 和 deb 包。但如果你是一个软件开发者或者喜欢尝鲜的用户迟早会遇到一个尴尬的局面自己写的应用或者想用的某个软件在 apt 源里找不到或者版本太旧而官方又只提供了 Flatpak 版本。这时候学会在优麒麟上构建 Flatpak 软件包就从一个“可选项”变成了“必备技能”。Flatpak 的核心价值在于一次构建多发行版运行。它把应用和依赖打包在一个沙箱环境里不依赖宿主系统的库版本。这意味着你在优麒麟上打好的包理论上可以拿到其他主流 Linux 发行版上直接跑反过来也一样。对于软件分发来说这省去了为每个发行版单独维护 deb、rpm 的麻烦。我最初接触 Flatpak 就是因为一个图像处理的小工具官方只发了 Flatpak 包apt 源里根本没有硬着头皮研究了一周踩了不少坑才把整个流程跑通。这篇文章适合三类人看一是手里有自研软件、想扩大分发范围的开发者二是想把自己常用的软件打包成 Flatpak 方便迁移的进阶用户三是对 Linux 打包机制好奇、想了解沙箱化分发原理的技术爱好者。不管你是哪一类只要跟着走一遍至少能独立完成一个可用的 Flatpak 包。2. 环境准备与工具链选型2.1 优麒麟上的基础依赖安装优麒麟的软件源里已经包含了 Flatpak 相关的工具但默认不一定装全。第一步先把基础环境搭起来。打开终端执行下面这行命令sudo apt update sudo apt install flatpak flatpak-builder elfutils这里解释一下三个包各自的作用。flatpak是运行时和命令行客户端负责安装、运行、管理 Flatpak 应用flatpak-builder是构建工具用来根据清单文件把源码编译打包成 Flatpak 格式elfutils提供了一组处理 ELF 文件的工具Flatpak 在打包过程中需要用它来剥离调试符号、检查二进制依赖缺了它构建会报错。装完之后建议把 Flathub 仓库加上虽然构建自己的包不强制需要 Flathub但很多运行时Runtime和基础 SDK 都托管在上面没有它你连编译环境都凑不齐flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo注意如果你的网络环境访问 Flathub 比较慢可以先把仓库地址记下来后续构建时用--from参数指定本地已经下载好的运行时文件避免构建过程中反复拉取超时。2.2 运行时与 SDK 的选择逻辑Flatpak 的构建体系里有两个核心概念Runtime运行时和SDK软件开发套件。Runtime 是应用运行时的基础环境SDK 是在 Runtime 基础上加了编译工具链的版本。构建的时候用 SDK运行的时候用 Runtime两者版本号必须对应。选哪个版本的 Runtime 和 SDK取决于你的应用依赖什么。比如你的应用是基于 GNOME 技术栈的那就选org.gnome.Platform和org.gnome.Sdk如果是纯命令行工具或者不依赖特定桌面环境用org.freedesktop.Platform和org.freedesktop.Sdk就够了。版本号方面我一般选当前稳定版往前推一两个版本太新的可能不稳定太旧的又缺新特性。以 freedesktop 为例安装对应版本的 SDK 和 Runtimeflatpak install flathub org.freedesktop.Sdk//23.08 flatpak install flathub org.freedesktop.Platform//23.08这里的23.08是版本标识代表 2023 年 8 月发布的稳定分支。你可以在 Flathub 的页面上查到所有可用版本。选好之后后面写清单文件时runtime-version字段要跟这个保持一致否则构建会直接失败。2.3 构建目录的规划在开始写清单之前先把目录结构规划好。我习惯在~/flatpak-build下建项目文件夹里面分几个子目录sources放源码压缩包或补丁build作为临时构建目录repo作为最终输出的本地仓库。这样做的目的是让构建过程可复现清理起来也方便不会把系统目录搞得一团糟。mkdir -p ~/flatpak-build/myapp/{sources,build,repo} cd ~/flatpak-build/myapp实操心得不要把构建目录放在/tmp下因为 Flatpak 构建过程中会产生大量中间文件/tmp空间不够会导致构建中断而且重启后数据丢失排查问题很麻烦。放在用户主目录下最稳妥。3. 清单文件的核心结构与参数详解3.1 清单文件的整体框架Flatpak 的构建完全由一个 JSON 或 YAML 格式的清单文件驱动通常命名为org.example.MyApp.json。这个文件描述了应用的基本信息、依赖的运行时、构建步骤、安装规则等。下面是一个最小可用的清单骨架{ app-id: org.example.MyApp, runtime: org.freedesktop.Platform, runtime-version: 23.08, sdk: org.freedesktop.Sdk, command: myapp, finish-args: [ --sharenetwork, --shareipc, --socketfallback-x11, --socketwayland ], modules: [] }app-id采用反向域名格式必须全局唯一建议用自己的域名倒序加应用名。command是应用启动时执行的命令必须跟后面安装到/app/bin下的可执行文件名一致。finish-args定义了沙箱权限这个后面单独展开讲。3.2 模块定义与源码引入方式modules数组是清单的核心每个模块代表一个构建单元。最简单的场景是只有一个模块直接编译你的应用源码。源码的引入方式有几种从 URL 下载压缩包、从本地目录复制、从 Git 仓库拉取。我一般用本地目录方式方便调试modules: [ { name: myapp, buildsystem: simple, build-commands: [ make, install -Dm755 myapp /app/bin/myapp ], sources: [ { type: dir, path: sources } ] } ]buildsystem指定构建系统类型常见的有simple、cmake、meson、autotools。如果项目用的是 Makefile选simple然后自己写build-commands最灵活。sources里的type: dir表示把本地sources目录的内容复制到构建环境中。3.3 沙箱权限的取舍原则finish-args决定了应用能访问宿主系统的哪些资源。Flatpak 的沙箱默认非常严格几乎什么都访问不了所以必须显式声明需要的权限。常见的权限项权限参数作用适用场景--sharenetwork允许访问网络需要联网的应用--shareipc允许进程间通信大多数 GUI 应用--socketx11访问 X11 显示服务传统 GUI 应用--socketwayland访问 Wayland 显示服务现代 GUI 应用--socketpulseaudio访问音频服务音视频应用--devicedri访问 GPU 设备需要硬件加速的应用--filesystemhome访问用户主目录文件管理器类应用注意权限给得越多沙箱的安全性越低。原则是“最小必要”应用不需要的权限坚决不加。比如一个纯计算工具就不应该给--sharenetwork。我见过有人图省事直接加--filesystemhost等于把整个文件系统都暴露了这跟不用沙箱没区别。4. 完整构建流程与实操记录4.1 从零开始构建一个示例应用假设我们有一个用 C 语言写的简单命令行工具源码在sources目录下包含main.c和Makefile。Makefile内容如下CC gcc CFLAGS -O2 myapp: main.c $(CC) $(CFLAGS) -o myapp main.c clean: rm -f myapp对应的清单文件org.example.MyApp.json完整内容{ app-id: org.example.MyApp, runtime: org.freedesktop.Platform, runtime-version: 23.08, sdk: org.freedesktop.Sdk, command: myapp, finish-args: [ --sharenetwork ], modules: [ { name: myapp, buildsystem: simple, build-commands: [ make, install -Dm755 myapp /app/bin/myapp ], sources: [ { type: dir, path: sources } ] } ] }执行构建命令flatpak-builder --reporepo build org.example.MyApp.json这条命令会做几件事读取清单文件下载或确认运行时和 SDK 已安装在build目录下创建沙箱环境把sources目录复制进去执行build-commands里的命令最后把产物打包成 Flatpak 格式存入repo目录。整个过程第一次会比较慢因为要下载 SDK后面有缓存就快了。4.2 构建产物的本地安装与验证构建成功后repo目录里就有了一个可安装的 Flatpak 仓库。先把它添加为本地远程仓库flatpak --user remote-add --no-gpg-verify local-repo repo然后安装flatpak --user install local-repo org.example.MyApp安装完成后运行flatpak run org.example.MyApp如果一切正常你应该能看到应用的输出。如果报错先用flatpak run --commandsh org.example.MyApp进入沙箱内部手动执行命令排查问题。这个技巧非常实用相当于给你一个 shell 进到沙箱里看看到底缺了什么。4.3 构建过程中的参数计算与优化构建时有两个参数值得关注--jobs和--ccache。--jobsN控制并行编译的任务数默认是 CPU 核心数。如果你的机器内存不大并行数太高会导致 OOM这时候可以手动降下来flatpak-builder --jobs2 --reporepo build org.example.MyApp.json--ccache启用编译缓存对于反复调试的场景能大幅缩短构建时间。第一次构建会慢一些后面改动少量代码重新构建时没变的部分直接命中缓存速度提升非常明显。我实测一个中等规模的项目启用 ccache 后二次构建时间从 8 分钟降到了 1 分半。实操心得构建大型项目时建议把build目录和repo目录分开放在不同的磁盘分区避免 IO 瓶颈。另外flatpak-builder默认会保留构建目录方便你进去检查中间产物但如果磁盘紧张可以在构建完成后手动清理build目录下的内容。5. 常见问题排查与避坑指南5.1 构建失败的典型原因与解决Flatpak 构建失败的原因五花八门但高频问题就那么几类。下面这张表是我踩坑后整理的速查表报错信息根本原因解决方法Runtime org.xxx not installed运行时或 SDK 未安装用flatpak install安装对应版本Command xxx not foundSDK 里缺少该工具在清单里添加包含该工具的 SDK 扩展Permission denied沙箱权限不足检查finish-args是否缺少必要权限No such file or directory路径写错或源码未正确复制检查sources配置和build-commands路径GPG verification failed本地仓库未禁用签名验证添加远程仓库时加--no-gpg-verify其中最常见的是运行时版本不匹配。比如清单里写runtime-version: 23.08但系统里只装了22.08构建直接报错退出。解决办法要么改清单版本号要么装对应版本的运行时。我建议在项目文档里明确写清楚依赖的运行时版本避免换台机器就构建不了。5.2 沙箱内调试的实用技巧构建成功但运行报错是最让人头疼的情况。这时候需要进沙箱内部看。除了前面提到的--commandsh还有几个有用的参数flatpak run --commandsh --devel org.example.MyApp加--devel会挂载开发环境让你在沙箱里也能用调试工具。进去之后可以用ldd检查二进制依赖是否齐全用strace跟踪系统调用看卡在哪一步。如果应用需要访问某个文件但被沙箱挡住了错误信息通常会提示Permission denied这时候回到清单里补对应的--filesystem权限即可。另一个技巧是用flatpak enter进入正在运行的应用沙箱flatpak enter org.example.MyApp bash这个命令需要 root 权限但能让你直接进入一个已经运行的沙箱实例观察运行时的真实状态比重新启动一个调试实例更贴近实际。5.3 打包体积优化的几个手段Flatpak 包动辄几百 MB主要体积来自运行时。但应用本身的体积也有优化空间。第一个手段是剥离调试符号在build-commands里加一行strip /app/bin/myapp第二个手段是删除不必要的文件比如文档、测试用例、静态库rm -rf /app/share/doc /app/share/man /app/lib/*.a第三个手段是确保没有把构建工具链打进最终包。Flatpak 的机制本身会把 SDK 和 Runtime 分开最终用户只需要 Runtime但如果你在build-commands里不小心把编译器或者开发头文件装到了/app下它们就会进入最终包。构建完成后用flatpak build-export导出时留意一下文件列表把不该有的东西清理掉。注意不要为了减小体积而删除应用运行必需的库文件。判断标准很简单用ldd检查二进制的依赖凡是列出来的.so文件都不能删。删错了会导致运行时崩溃而且报错信息往往很隐晦排查起来非常费劲。6. 从本地构建到分发的延伸思考6.1 本地仓库的维护与更新构建出来的repo目录是一个标准的 OSTree 仓库可以持续追加新版本。每次重新构建后用同样的flatpak build-export命令把新版本导进去然后更新本地安装flatpak --user update org.example.MyApp如果想把仓库分享给同一台机器上的其他用户可以把repo目录放到一个公共位置其他用户添加这个本地远程仓库即可。这种方式适合团队内部小范围分发不需要搭建服务器。6.2 打包过程中的版本管理策略应用版本号的管理在 Flatpak 里通过build-export的--subject和--body参数来标记但更规范的做法是在清单文件里通过源码的 tag 或者 commit 来区分。我习惯在sources里用type: git并指定tag这样每次构建都能明确对应到源码的哪个版本。如果用的是本地目录方式就在目录名里带上版本号比如sources-1.2.0构建不同版本时切换目录。另外app-id一旦确定就不要改因为它是应用的唯一标识改了之后用户那边的更新链路就断了。版本迭代只更新build-export时的提交信息app-id保持不变。6.3 什么场景下值得用 Flatpak不是所有软件都适合打成 Flatpak。我的判断标准是如果应用依赖复杂的第三方库、或者目标用户分布在多个 Linux 发行版上、又或者官方源更新太慢那 Flatpak 就很值得。反过来如果应用本身就是发行版官方源里的核心组件或者体积极小、依赖极简那用 deb 包反而更轻量。还有一个容易被忽略的点Flatpak 的沙箱机制对某些需要深度访问系统资源的应用不太友好比如系统监控工具、硬件驱动配置工具。这类应用强行打包成 Flatpak要么权限开得太大失去沙箱意义要么功能受限用起来别扭。这种情况下传统的 deb 包或者直接提供源码编译才是更合适的选择。我在实际打包过程中最大的体会是Flatpak 的清单文件看似简单但每一个字段背后都对应着构建系统的具体行为写错一个参数可能就要花半天排查。建议新手从最简单的单模块、无依赖的命令行工具开始练手跑通整个流程后再逐步增加复杂度。另外养成每次构建前先flatpak-builder --clean清理缓存的习惯能避免很多因为缓存不一致导致的诡异问题。