把 LocalSend 打成单文件 AppImage任意 Linux 发行版直接跑通【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend给同事分发内部工具时最容易踩的坑程序在 Ubuntu 上编好了拿到 Fedora 上一运行缺库报错。这就是 Linux 发行版碎片化问题而 LocalSend一个类 AirDrop 的跨平台文件传输工具给出的解法是把整个应用连同依赖库打进一个 AppImage 单文件——拷贝过去就能跑。本文以 LocalSend 为例走一遍从源码到可发布产物的完整链路。一句话结论LocalSend 的 AppImage 产物是一个自包含可执行文件应用本体 全部运行时库压缩进单文件适合需要向异构 Linux 环境分发工具的团队也适合复制即用、不想装依赖的普通用户。原理为什么换个发行版也能直接跑AppImage 的本质是文件即文件系统内核加载器把这个文件挂载为只读 SquashFS一种把目录压缩成单文件的只读快照格式应用启动时引用的 .so 库全部来自镜像内部而不是系统目录。运行时环境与发行版彻底解耦自然不存在库版本对不上的问题。从零复现五步跑出一个可用的 AppImage构建脚本参考仓库里的support/scripts/compile_linux_appimage.sh核心步骤如下第 1 步准备 Ubuntu 22.04 构建机。AppImage 对依赖版本敏感构建机和 CI 用同一基础系统能最大限度复现问题。sudo apt install curl clang cmake libgtk-3-dev ninja-build \ libayatana-appindicator3-dev libfuse2 squashfs-toolslibayatana-appindicator3-dev是系统托盘组件libfuse2是 AppImage 挂载必需项squashfs-tools提供压缩工具 mksquashfs。第 2 步获取源码。git clone https://gitcode.com/GitHub_Trending/lo/localsend cd localsend git submodule update --init仓库用support/submodules/flutter固定了 Flutter SDK 版本编译时直接用子模块里的 flutter避免版本漂移。第 3 步编译 Linux 二进制。cd app submodules/../submodules/flutter/bin/flutter pub get flutter pub run build_runner build -d flutter build linux产物落在build/linux/x64/release/bundle/里面是可执行文件、.desktop 桌面项和资源。第 4 步组装 AppDir。AppDir 是 AppImage 的原料目录结构模拟一个最小化的 Linux 系统mkdir AppDir cp -r build/linux/x64/release/bundle/* AppDir第 5 步执行构建。配方文件support/build/appimage/AppImageBuilder_x86_64.yml需要复制为工作目录下的AppImageBuilder.yml然后appimage-builder --recipe AppImageBuilder.yml跑完得到LocalSend-版本-x86_64.AppImage。仓库里 x86_64 与 ARM64 两套配方都在 support/build/appimage/ 目录下。YAML 里最容易配错的三处一、app_info.version与update-information。项目曾专门修过AppImage 版本号未同步真实版本的 bug。这个字段不是摆设AppImage 靠它做版本比较和更新探测。发布时务必让它与pubspec.yaml的实际版本号一致update-information: guess则控制更新信息从哪里猜。二、apt.arch与include的架构后缀。包名必须写成libayatana-appindicator3-1:amd64这样带后缀的形式且后缀要和arch严格一致。ARM 配方里漏写:arm64或误写成:amd64依赖解析直接失败这类错误在 CI 日志里很隐蔽。三、runtime.env与files.exclude。AppImage 挂载为只读应用自己写不了镜像内的目录XDG_DATA_DIRS把系统主题、图标目录补进查找路径保证桌面集成正常exclude则把 man 手册、各包的 README/changelog 从镜像里剔掉纯减重。两条一个管找得到一个管装得下。双架构x86_64 与 ARM64 的构建切换两套配置几乎相同差异只有三行apt.archamd64 / arm64、include包名的架构后缀、AppImage.archx86_64 / arm_64。关键区别在构建环境Flutter 官方没有提供 Linux ARM64 的交叉编译工具链所以 ARM64 的 CI 直接跑在真实的ubuntu-22.04-armrunner 上产物取自build/linux/arm64/release/bundle/。也就是说换架构不是改个参数而是换构建机本地 x86 机器编不出 ARM64 AppImage。排错手册四个高频问题Q在某个发行版上出现库版本冲突配方把 apt 源固定为同一批 LTSjammy源include只列最小运行库并用exclude剔除 adwaita 图标主题这类顺带装上的包。依赖面越小跨发行版冲突概率越低。Q托盘图标不显示、SVG 图标渲染成空白托盘依赖libayatana-appindicator3-1SVG 渲染依赖librsvg2-common两者都必须在include里。另外 CI 会额外把 logo 的 32/128/256 三种 PNG 拷进usr/share/icons/hicolor/...缺了这一步桌面图标会缺省。Q构建报 mksquashfs 找不到配方开头那条which mksquashfs || apt install squashfs-tools就是兜底本地构建机建议直接把 squashfs-tools 装好。Q产物为什么不能写文件只读挂载是 AppImage 的安全设计。应用若需写配置走XDG_DATA_DIRS指向的系统目录或用户主目录即可不要假设 AppDir 可写。发布前检查清单在至少三个发行版Debian、Ubuntu、Fedora/Arch里直接双击或命令行运行产物桌面菜单项、托盘图标在明暗两套主题下都正常版本号与发布号一致对照app_info.version局域网内完整走一遍发送/接收流程ARM64 产物在真机或 ARM runner 上验证不能只信 x86 结果产物体积抽查确认files.exclude生效man/doc 不应在镜像里一页纸模板最小可复制的 AppImageBuilder.ymlversion: 1 script: - which mksquashfs || apt install squashfs-tools AppDir: path: AppDir app_info: id: org.localsend.localsend_app name: LocalSend icon: localsend version: 1.18.2 exec: localsend_app exec_args: $ apt: arch: [amd64] allow_unauthenticated: true sources: - sourceline: deb http://archive.ubuntu.com/ubuntu/ jammy main restricted - sourceline: deb http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted include: - libayatana-appindicator3-1:amd64 - librsvg2-common:amd64 exclude: - adwaita-icon-theme:* runtime: env: XDG_DATA_DIRS: /usr/local/share/:/usr/share/:${XDG_DATA_DIRS} files: include: [] exclude: - usr/share/man - usr/share/doc/*/README.* - usr/share/doc/*/changelog.* AppImage: arch: x86_64 update-information: guess改 ARM64 时只需三处arch: [arm64]、两个包的:arm64后缀、AppImage.arch: arm_64。这套单文件 AppImage 锁定 LTS 依赖 双架构配方的做法最适合需要向异构 Linux 环境分发的 Flutter/Rust 桌面应用——拷一个文件全发行版直接跑。【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 把 LocalSend 打成单文件 AppImage：任意 Linux 发行版直接跑通
把 LocalSend 打成单文件 AppImage任意 Linux 发行版直接跑通【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend给同事分发内部工具时最容易踩的坑程序在 Ubuntu 上编好了拿到 Fedora 上一运行缺库报错。这就是 Linux 发行版碎片化问题而 LocalSend一个类 AirDrop 的跨平台文件传输工具给出的解法是把整个应用连同依赖库打进一个 AppImage 单文件——拷贝过去就能跑。本文以 LocalSend 为例走一遍从源码到可发布产物的完整链路。一句话结论LocalSend 的 AppImage 产物是一个自包含可执行文件应用本体 全部运行时库压缩进单文件适合需要向异构 Linux 环境分发工具的团队也适合复制即用、不想装依赖的普通用户。原理为什么换个发行版也能直接跑AppImage 的本质是文件即文件系统内核加载器把这个文件挂载为只读 SquashFS一种把目录压缩成单文件的只读快照格式应用启动时引用的 .so 库全部来自镜像内部而不是系统目录。运行时环境与发行版彻底解耦自然不存在库版本对不上的问题。从零复现五步跑出一个可用的 AppImage构建脚本参考仓库里的support/scripts/compile_linux_appimage.sh核心步骤如下第 1 步准备 Ubuntu 22.04 构建机。AppImage 对依赖版本敏感构建机和 CI 用同一基础系统能最大限度复现问题。sudo apt install curl clang cmake libgtk-3-dev ninja-build \ libayatana-appindicator3-dev libfuse2 squashfs-toolslibayatana-appindicator3-dev是系统托盘组件libfuse2是 AppImage 挂载必需项squashfs-tools提供压缩工具 mksquashfs。第 2 步获取源码。git clone https://gitcode.com/GitHub_Trending/lo/localsend cd localsend git submodule update --init仓库用support/submodules/flutter固定了 Flutter SDK 版本编译时直接用子模块里的 flutter避免版本漂移。第 3 步编译 Linux 二进制。cd app submodules/../submodules/flutter/bin/flutter pub get flutter pub run build_runner build -d flutter build linux产物落在build/linux/x64/release/bundle/里面是可执行文件、.desktop 桌面项和资源。第 4 步组装 AppDir。AppDir 是 AppImage 的原料目录结构模拟一个最小化的 Linux 系统mkdir AppDir cp -r build/linux/x64/release/bundle/* AppDir第 5 步执行构建。配方文件support/build/appimage/AppImageBuilder_x86_64.yml需要复制为工作目录下的AppImageBuilder.yml然后appimage-builder --recipe AppImageBuilder.yml跑完得到LocalSend-版本-x86_64.AppImage。仓库里 x86_64 与 ARM64 两套配方都在 support/build/appimage/ 目录下。YAML 里最容易配错的三处一、app_info.version与update-information。项目曾专门修过AppImage 版本号未同步真实版本的 bug。这个字段不是摆设AppImage 靠它做版本比较和更新探测。发布时务必让它与pubspec.yaml的实际版本号一致update-information: guess则控制更新信息从哪里猜。二、apt.arch与include的架构后缀。包名必须写成libayatana-appindicator3-1:amd64这样带后缀的形式且后缀要和arch严格一致。ARM 配方里漏写:arm64或误写成:amd64依赖解析直接失败这类错误在 CI 日志里很隐蔽。三、runtime.env与files.exclude。AppImage 挂载为只读应用自己写不了镜像内的目录XDG_DATA_DIRS把系统主题、图标目录补进查找路径保证桌面集成正常exclude则把 man 手册、各包的 README/changelog 从镜像里剔掉纯减重。两条一个管找得到一个管装得下。双架构x86_64 与 ARM64 的构建切换两套配置几乎相同差异只有三行apt.archamd64 / arm64、include包名的架构后缀、AppImage.archx86_64 / arm_64。关键区别在构建环境Flutter 官方没有提供 Linux ARM64 的交叉编译工具链所以 ARM64 的 CI 直接跑在真实的ubuntu-22.04-armrunner 上产物取自build/linux/arm64/release/bundle/。也就是说换架构不是改个参数而是换构建机本地 x86 机器编不出 ARM64 AppImage。排错手册四个高频问题Q在某个发行版上出现库版本冲突配方把 apt 源固定为同一批 LTSjammy源include只列最小运行库并用exclude剔除 adwaita 图标主题这类顺带装上的包。依赖面越小跨发行版冲突概率越低。Q托盘图标不显示、SVG 图标渲染成空白托盘依赖libayatana-appindicator3-1SVG 渲染依赖librsvg2-common两者都必须在include里。另外 CI 会额外把 logo 的 32/128/256 三种 PNG 拷进usr/share/icons/hicolor/...缺了这一步桌面图标会缺省。Q构建报 mksquashfs 找不到配方开头那条which mksquashfs || apt install squashfs-tools就是兜底本地构建机建议直接把 squashfs-tools 装好。Q产物为什么不能写文件只读挂载是 AppImage 的安全设计。应用若需写配置走XDG_DATA_DIRS指向的系统目录或用户主目录即可不要假设 AppDir 可写。发布前检查清单在至少三个发行版Debian、Ubuntu、Fedora/Arch里直接双击或命令行运行产物桌面菜单项、托盘图标在明暗两套主题下都正常版本号与发布号一致对照app_info.version局域网内完整走一遍发送/接收流程ARM64 产物在真机或 ARM runner 上验证不能只信 x86 结果产物体积抽查确认files.exclude生效man/doc 不应在镜像里一页纸模板最小可复制的 AppImageBuilder.ymlversion: 1 script: - which mksquashfs || apt install squashfs-tools AppDir: path: AppDir app_info: id: org.localsend.localsend_app name: LocalSend icon: localsend version: 1.18.2 exec: localsend_app exec_args: $ apt: arch: [amd64] allow_unauthenticated: true sources: - sourceline: deb http://archive.ubuntu.com/ubuntu/ jammy main restricted - sourceline: deb http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted include: - libayatana-appindicator3-1:amd64 - librsvg2-common:amd64 exclude: - adwaita-icon-theme:* runtime: env: XDG_DATA_DIRS: /usr/local/share/:/usr/share/:${XDG_DATA_DIRS} files: include: [] exclude: - usr/share/man - usr/share/doc/*/README.* - usr/share/doc/*/changelog.* AppImage: arch: x86_64 update-information: guess改 ARM64 时只需三处arch: [arm64]、两个包的:arm64后缀、AppImage.arch: arm_64。这套单文件 AppImage 锁定 LTS 依赖 双架构配方的做法最适合需要向异构 Linux 环境分发的 Flutter/Rust 桌面应用——拷一个文件全发行版直接跑。【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考