UnleashedRecomp Flatpak 构建指南：在 Linux 上从源码打包 Sonic Unleashed 静态重编译移植版-迪斯科星球

UnleashedRecomp Flatpak 构建指南：在 Linux 上从源码打包 Sonic Unleashed 静态重编译移植版

【免费下载链接】UnleashedRecompAn unofficial PC port of the Xbox 360 version of Sonic Unleashed created through the process of static recompilation.项目地址: https://gitcode.com/GitHub_Trending/un/UnleashedRecomp

导读

UnleashedRecomp 是通过静态重编译技术制作的《索尼克释放》（Sonic Unleashed）Xbox 360 版本非官方 PC 移植版。为了在 Linux 桌面与 Steam Deck 上提供开箱即用的安装体验，项目在 flatpak 目录中提供了完整的 Flatpak 打包定义：从flatpak-builder编译构建，到flatpak build-bundle生成可分发的单文件 bundle。本文以 flatpak/README.md 的两条核心命令为主线，逐项拆解其背后的 Manifest 配置、CMake 适配逻辑与桌面集成文件，读完你将能够独立完成该移植版的 Flatpak 打包、分发与安装排错。

一、flatpak 目录的文件布局与各自职责

仓库根目录下的 flatpak 目录共包含四个文件，构成一次完整 Flatpak 打包的全部输入：

文件	作用
README.md	打包与打包分发的两条核心命令说明
io.github.hedge_dev.unleashedrecomp.json	Flatpak Manifest，描述运行时、权限与构建步骤
io.github.hedge_dev.unleashedrecomp.desktop	桌面入口文件（`.desktop`），用于应用菜单集成
io.github.hedge_dev.unleashedrecomp.metainfo.xml	AppStream 元数据，供软件中心展示应用信息

其中 Manifest 是构建的"蓝图"，README 中的命令则是调用flatpak-builder与flatpak build-bundle的标准姿势。

二、打包前置条件

在动手之前，需要确认以下条件满足：

安装 Flatpak 工具链：需要flatpak与flatpak-builder两个命令。Debian/Ubuntu 系可用sudo apt install flatpak flatpak-builder安装；Arch 系可用sudo pacman -S flatpak flatpak-builder。
注册 Flathub 远程仓库：构建时--install-deps-from=flathub会从 Flathub 拉取运行时依赖（org.freedesktop.Platform等），需要先执行flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo。
完整的游戏文件：Flatpak 打包只编译移植版本体，游戏资源（default.xex、default.xexp、shader.ar）需要在安装时由用户自行提供。获取与校验方法详见 docs/BUILDING.md 与 README.md 的安装章节，这些文件必须来自你合法拥有的美版或欧版（日版不支持）。
构建期网络访问：Manifest 中为构建步骤单独授予了--share=network（见下文 build-options），因为 CMake 配置阶段需要下载 vcpkg 依赖。
磁盘与内存：vcpkg 依赖、中间产物与最终 builddir 合计占用数 GB 空间，请预留充足磁盘。

三、构建命令逐项解析

flatpak/README.md 给出的构建命令为：

flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo --install builddir io.github.hedge_dev.unleashedrecomp.json

各参数含义如下：

参数	含义
`--force-clean`	构建前清空`builddir`，保证每次都是干净构建，避免脏状态导致的偶发失败
`--user`	以用户级安装方式安装应用（安装到`~/.local/share/flatpak`），无需 root 权限
`--install-deps-from=flathub`	自动从名为`flathub`的远程仓库安装 Manifest 声明的运行时与 SDK 依赖
`--repo=repo`	将构建产物导出到当前目录下名为`repo`的 OSTree 仓库，该仓库是下一步`build-bundle`的输入
`--install`	构建完成后直接将应用安装到系统（配合`--user`即用户级安装），可立即在应用菜单或命令行中启动
`builddir`	构建过程中的临时工作目录，由`--force-clean`管理
`io.github.hedge_dev.unleashedrecomp.json`	本次构建使用的 Manifest 文件

命令执行完毕后，builddir中是中间产物，repo/目录中则是可被flatpak客户端直接使用的本地 OSTree 仓库。若只想构建而不安装，可去掉--install，之后通过flatpak install --user repo io.github.hedge_dev.unleashedrecomp手动安装。

从 CMakePresets.json 可知，Linux 平台可用 preset 包括linux-debug、linux-relwithdebinfo与linux-release，Flatpak 打包固定使用 release 配置以保证性能与体积。

四、Manifest 深入解析：运行时、权限与构建步骤

io.github.hedge_dev.unleashedrecomp.json 是整条打包链的核心，下面逐段解读。

4.1 应用 ID 与运行时

"id": "io.github.hedge_dev.unleashedrecomp", "runtime": "org.freedesktop.Platform", "runtime-version": "24.08", "sdk": "org.freedesktop.Sdk", "sdk-extensions": [ "org.freedesktop.Sdk.Extension.llvm18" ]

应用 ID 使用反向域名形式，与 .desktop 和 metainfo.xml 中的 ID 保持一致，这是 Flatpak 应用标识与集成文件匹配的前提。
运行时基于freedesktop 平台 24.08，这是 Flatpak 生态常用的通用 Linux 桌面运行时。
SDK 扩展llvm18提供了 LLVM/Clang 18 工具链。从 Manifest 的build-options可见，构建时通过append-path与prepend-ld-library-path将/usr/lib/sdk/llvm18/bin和/usr/lib/sdk/llvm18/lib注入构建环境，确保 CMake 使用仓库期望的 Clang 工具链完成编译。

4.2 运行时权限（finish-args）

"finish-args": [ "--share=network", "--socket=wayland", "--socket=fallback-x11", "--socket=pulseaudio", "--device=all", "--filesystem=host", "--filesystem=/media", "--filesystem=/run/media", "--filesystem=/mnt" ]

这些参数决定应用在 Flatpak 沙箱内的能力：

参数	授予的能力	必要性分析
`--share=network`	完整网络访问	支持更新检查（install/update_checker.cpp）等联网功能
`--socket=wayland`/`--socket=fallback-x11`	Wayland / X11 显示服务	渲染窗口与 UI 的基础，`fallback-x11`保证无 Wayland 会话时自动回退
`--socket=pulseaudio`	PulseAudio 音频服务	游戏音频输出，对应 apu/audio.cpp 与 SDL_mixer 音频后端
`--device=all`	访问所有设备节点	允许游戏读取手柄等输入设备
`--filesystem=host`及`/media`、`/run/media`、`/mnt`	访问主机文件系统与可移动存储	允许用户在安装向导中直接浏览主机目录、从外置硬盘/U 盘提供游戏文件；`/run/media`正是 Steam Deck 挂载 microSD 卡的路径

这套权限设计服务于"游戏文件需用户自行提供"的安装模型：沙箱需要看到主机上的游戏镜像或目录，同时保留必要的图形、音频与输入能力。

4.3 构建步骤（build-commands）

"build-commands": [ "cmake --preset linux-release -DUNLEASHED_RECOMP_FLATPAK=ON -DSDL2MIXER_VORBIS=VORBISFILE -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER_LAUNCHER=ccache", "cmake --build out/build/linux-release --target UnleashedRecomp", "mkdir -p /app/bin", "cp out/build/linux-release/UnleashedRecomp/UnleashedRecomp /app/bin/UnleashedRecomp", "install -Dm644 UnleashedRecompResources/images/game_icon.png /app/share/icons/hicolor/128x128/apps/${FLATPAK_ID}.png", "install -Dm644 flatpak/io.github.hedge_dev.unleashedrecomp.metainfo.xml /app/share/metainfo/${FLATPAK_ID}.metainfo.xml", "install -Dm644 flatpak/io.github.hedge_dev.unleashedrecomp.desktop /app/share/applications/${FLATPAK_ID}.desktop" ]

逐条拆解：

CMake 配置：使用linux-releasepreset 并追加三个关键变量：
- -DUNLEASHED_RECOMP_FLATPAK=ON：启用 Flatpak 兼容编译定义（见第五章）；
- -DSDL2MIXER_VORBIS=VORBISFILE：指示 SDL_mixer 使用 VORBISFILE 后端解码 Ogg Vorbis 音频，这是 Flatpak 沙箱环境下依赖链接更干净的选择；
- -DCMAKE_(C|CXX)_COMPILER_LAUNCHER=ccache：启用 ccache 加速增量构建，对反复打包的场景收益明显。
构建目标：cmake --build out/build/linux-release --target UnleashedRecomp，产物输出到out/build/linux-release/UnleashedRecomp/，与 CMakePresets.json 中linux-base的binaryDir约定一致。
安装可执行文件：将编译出的UnleashedRecomp复制到/app/bin/，即 Flatpak 应用的运行时根目录。
安装图标、AppStream 元数据与桌面入口：分别安装到/app/share/icons/hicolor/128x128/apps/、/app/share/metainfo/与/app/share/applications/，文件名的app前缀统一替换为${FLATPAK_ID}。这三步是应用在软件中心与桌面环境中"可见"的基础。

4.4 源码与构建环境

"sources": [ { "type": "dir", "path": "../" } ], "build-options": { "append-path": "/usr/lib/sdk/llvm18/bin", "prepend-ld-library-path": "/usr/lib/sdk/llvm18/lib", "build-args": [ "--share=network" ] }

源码以dir类型直接引用仓库根目录（Manifest 所在flatpak/的上级），因此无需下载 tarball，仓库克隆后即可打包；
build-args: ["--share=network"]单独为构建阶段授予网络，供 CMake/vcpkg 拉取依赖；
buildsystem: "simple"表示不使用任何外部构建系统包装，直接逐条执行build-commands。

五、CMake 侧的 Flatpak 适配

Manifest 中的UNLEASHED_RECOMP_FLATPAK=ON会触发 UnleashedRecomp/CMakeLists.txt 中的逻辑：

if (UNLEASHED_RECOMP_FLATPAK) target_compile_definitions(UnleashedRecomp PRIVATE "UNLEASHED_RECOMP_FLATPAK" "GAME_INSTALL_DIRECTORY=\"/var/data\"" ) endif()

该选项在 UnleashedRecomp/CMakeLists.txt 中定义，且仅在 Linux 平台暴露（CMAKE_SYSTEM_NAME MATCHES "Linux"）：

编译期定义UNLEASHED_RECOMP_FLATPAK宏，供源码分支判断当前是否运行在 Flatpak 环境；
定义GAME_INSTALL_DIRECTORY常量指向/var/data，作为沙箱内游戏数据的安装路径锚点。

与之对应，从项目 README.md 的 FAQ 可确认最终用户视角的数据位置：Flatpak 版本的游戏数据安装在~/.var/app/io.github.hedge_dev.unleashedrecomp/data，且该构建只认可这一数据目录；如果将来想切换回原生 Linux 构建，这个数据目录可以直接复用。若需迁移数据位置，可通过创建符号链接将上述目录指向新的安装位置。

六、Bundle：生成可分发、可离线安装的单文件包

构建完成后，flatpak/README.md 给出的第二条命令将本地 OSTree 仓库导出为单一 bundle 文件：

flatpak build-bundle repo io.github.hedge_dev.unleashedrecomp.flatpak io.github.hedge_dev.unleashedrecomp --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo

参数	含义
`repo`	输入仓库，即上一步`--repo=repo`生成的本地 OSTree 仓库
`io.github.hedge_dev.unleashedrecomp.flatpak`	输出的 bundle 文件名
`io.github.hedge_dev.unleashedrecomp`	要打包进 bundle 的应用 ID
`--runtime-repo=https://flathub.org/repo/flathub.flatpakrepo`	声明运行时依赖（如`org.freedesktop.Platform 24.08`）需从 Flathub 获取，因此 bundle 本体只包含应用自身，体积更小

bundle 文件适合拷贝到其他机器离线安装：

flatpak install --user io.github.hedge_dev.unleashedrecomp.flatpak

首次安装时若本机缺少运行时，Flatpak 会提示并尝试从 Flathub（即 bundle 中声明的--runtime-repo）拉取。分发的机器上需先执行flatpak remote-add flathub ...完成远程仓库注册。

七、桌面集成与软件中心元数据

7.1 桌面入口文件

io.github.hedge_dev.unleashedrecomp.desktop 定义了应用在桌面环境中的启动方式：

[Desktop Entry] Name=Unleashed Recompiled Exec=/app/bin/UnleashedRecomp Type=Application Icon=io.github.hedge_dev.unleashedrecomp Categories=Game; Comment=Static recompilation of Sonic Unleashed. MimeType=x-scheme-handler/unleashedrecomp

Exec指向/app/bin/UnleashedRecomp，与 Manifest 构建步骤中的复制目标一致；
Icon对应 Manifest 安装的game_icon.png（安装后被重命名为${FLATPAK_ID}.png）；
Categories=Game;让应用出现在游戏分类；
自定义的x-scheme-handler/unleashedrecompMimeType 注册了unleashedrecomp://协议处理，为将来的链接式启动预留能力。

7.2 AppStream 元数据

io.github.hedge_dev.unleashedrecomp.metainfo.xml 提供软件中心（如 GNOME Software / KDE Discover）展示所需的描述信息：

应用名称Unleashed Recompiled，摘要为 "An unofficial PC port of Sonic Unleashed."；
许可声明：metadata_license为 CC0-1.0，项目代码许可为 GPL-3.0+；
supports声明支持鼠标（pointing）、键盘（keyboard）与触控（touch）三种输入方式；
launchable指向io.github.hedge_dev.unleashedrecomp.desktop，与桌面入口文件形成闭环。

7.3 安装目录规范

Manifest 将所有集成文件安装到标准位置，这是 Flatpak 应用能被正确识别的硬性要求：可执行文件在/app/bin，图标在/app/share/icons，元数据在/app/share/metainfo，桌面入口在/app/share/applications。构建步骤中的install -Dm644会按需创建缺失目录。

八、运行验证、数据目录与 Steam Deck 使用

构建并安装完成后，可用以下方式启动：

flatpak run io.github.hedge_dev.unleashedrecomp

首次启动时，游戏的安装向导会引导你提供合法获取的游戏文件（Xbox 360 镜像/容器或已解包的原始文件）。相关的游戏文件获取流程（硬盘/ U 盘导出）见 docs/DUMPING-en.md 与 docs/DUMPING-USB-en.md。

几个与本打包方式直接相关的使用要点：

数据目录：如前所述，Flatpak 版本的游戏数据固定位于~/.var/app/io.github.hedge_dev.unleashedrecomp/data（保存数据与配置config.toml均在~/.config/UnleashedRecomp/体系内，Flatpak 环境下映射到该data目录）。
Steam Deck：项目 README 明确推荐 Flatpak 构建用于 Steam Deck——它可以在桌面模式下直接安装并作为非 Steam 游戏添加。由于沙箱授予了--filesystem=/run/media，从 microSD 卡提供游戏文件完全可行；安装过程建议在桌面模式下进行，以避免游戏模式下文件选择器不可用的问题。
窗口系统调试：若在 Wayland/X11 会话间切换遇到显示问题，可用 SDL 视频驱动参数强制指定，例如flatpak run io.github.hedge_dev.unleashedrecomp --sdl-video-driver wayland。
更新应用：已安装的 Flatpak 应用可用flatpak update io.github.hedge_dev.unleashedrecomp更新；重新打包时建议配合--force-clean保证干净构建。

九、常见问题与排查建议

构建提示缺少运行时/SDK：确认已执行flatpak remote-add --if-not-exists flathub ...，且--install-deps-from=flathub参数拼写正确；构建期网络由 Manifest 的build-args: ["--share=network"]保障，无需额外处理。
ccache 缓存目录不可写：ccache默认缓存位于用户主目录，在 Flatpak 构建沙箱中如遇权限问题，可通过设置CCACHE_DIR环境变量指向可写位置。
CMake 阶段下载 vcpkg 依赖失败：多为网络波动，可重新执行flatpak-builder命令（配合--force-clean从干净状态重试）。
安装向导提示文件无效：请检查游戏文件来源是否合法且未被修改、区域是否一致（美版/欧版），以及是否误将.zip/.7z等压缩包直接传入；详细校验规则见 README.md 的 FAQ。
数据目录不被识别：Flatpak 构建只认可~/.var/app/io.github.hedge_dev.unleashedrecomp/data，请勿把游戏数据放在仓库目录或安装目录中。

结语

本文完整还原了 flatpak/README.md 的构建与打包流程，并将其与 Manifest、CMake 适配、桌面入口与 AppStream 元数据逐一对齐。理解这套打包链后，你既可以自行产出可分发的 Flatpak bundle，也能为后续移植其他游戏或扩展沙箱权限提供直接的参考模板。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析