AnyPS5 relinker报错怎么办？10种常见错误场景与退出码排查清单

AnyPS5 relinker报错怎么办？10种常见错误场景与退出码排查清单

【免费下载链接】AnyPS5Tool for automatic PS5 executables porting to Linux and Windows项目地址: https://gitcode.com/GitHub_Trending/an/AnyPS5

AnyPS5 是一款将 PS5 可执行文件自动移植到 Linux 和 Windows 的开源工具，其中的 relinker 组件负责把 ELF 可执行文件重写为目标平台的原生格式。转换失败时，relinker 会在标准错误输出FAIL: 错误信息并以特定退出码退出。本文整理了10 种常见报错场景和一份退出码速查表，帮你快速定位问题、一次修好。

退出码速查：30秒看懂 relinker 的退出状态

排查前先记住三个数字（源码见 core/relinker/main.cpp）：

退出码	含义	去哪里找原因
0	转换成功	—
1	命令行参数不合法	检查 relinker 的调用参数
2	转换失败	stderr 中的FAIL:行，常带(offset 0x…)
其他	使用了--autorun时，这是启动的程序的退出码	见运行期问题排查

💡 小技巧：转换失败时，offset 0x…指向出错字节在输入文件中的位置，把它报给项目维护者或对照自己的反汇编，能大幅缩短排查时间。

场景1：unknown option 或 unexpected argument（退出码 1）

报错样式：

FAIL: unknown option: --windos FAIL: unexpected argument: extra.elf

原因：拼错参数、多写了参数，或把unused-filter写成了--unused-filter。

解决方法：

• 对照 docs/user/USAGE.md 的选项表逐个核对拼写
• 注意unused-filter=0|1|2不带--前缀，且只能出现一次
• relinker 没有--help标志；不带任何参数运行即可打印用法

参数解析逻辑在 core/relinker/cli/src/CliArgs.cpp。

场景2：参数组合冲突（退出码 1）

报错样式：

FAIL: --windows-diagnostics requires --windows FAIL: --exclude-sce-module conflicts with --skip-sce-module FAIL: unused-filter must be specified once with a value of 0, 1 or 2

原因：--windows-diagnostics和--windows-gui必须搭配--windows；--skip-sce-module与--exclude-sce-module互斥。

解决方法：删掉冲突的选项。同时注意，--skip-sce-module、--exclude-sce-module、--skip-syscall-check、--lazy-binding均已弃用，文档明确说明它们只用于调试，游戏带这些标志运行会极不稳定。

场景3：The input is a SELF container, not an ELF（退出码 2）

报错样式：

FAIL: The input is a SELF container, not an ELF

原因：你直接把 PS5 光盘镜像里加密的.elf（SELF 封装）喂给了 relinker。relinker 要求的是已解密的干净 ELF（检测逻辑在 core/relinker/relinker/src/parsing/ElfReader.cpp）。

解决方法：先通过你已有的 SELF 解密流程拿到明文 ELF，再运行 relinker。

场景4：Invalid ELF magic number（退出码 2）

报错样式：

FAIL: Invalid ELF magic number: 50 4b 03 04

原因：输入文件不是 ELF。括号里的 4 字节是文件头的实际魔数，例如50 4b 03 04是 ZIP 格式——你可能拷错了文件。

解决方法：

• 确认输入是 PS5 主程序对应的 ELF，而不是压缩包、图标或其他资源
• 若文件过小还会报File too small for ELF header，同样是拿错了文件

场景5：sce_module 目录缺失（退出码 2）

报错样式：

FAIL: sce_module/sce_modules/prx was not found beside the input executable: /path/to/source. Use --skip-sce-module only if this game can run without these modules.

原因：relinker 要求在游戏自带的 ELF 模块目录sce_module/（或sce_modules/、prx/）与输入文件同目录存在。正确布局参考 docs/user/USAGE.md：

source/ input.elf sce_module/ <bundled ELF modules>

解决方法：把游戏文件按上述布局重新组织。除非你确定该游戏没有捆绑模块，否则不要使用已弃用的--skip-sce-module绕过（源码见 core/relinker/relinker/src/guest/GuestModuleBuilder.cpp）。

场景6：sce_module 与 sce_modules 同时存在（退出码 2）

报错样式：

FAIL: Both sce_module and sce_modules exist beside the input executable

原因：单数目录sce_module/和复数目录sce_modules/二选一，不能同时存在。

解决方法：只保留其中一个目录名，把模块都放进去，再重新转换。

场景7：--to-intel 指令转换失败（退出码 2）

报错样式：

FAIL: AMD-only instruction without Intel lowering: VPERMPD (offset 0x8a2f3c) FAIL: AMD-only instruction too short for a jump and not followed by an instruction (offset 0x...)

原因：--to-intel用于把 AMD 专有指令替换成 Intel 兼容序列。遇到没有替换方案的指令（VPERMPD、部分 SHA/CLZERO 指令等）时直接报错，相关实现在 core/relinker/codegen/src/Amd64OnlyConverter.cpp。

解决方法：

• 去掉--to-intel（仅在 Intel CPU 上运行游戏时才有必要加它）
• 确认输入确实是 AMD Zen 架构的可执行文件；AMD 平台上保持默认即可

场景8：Windows 目标专属错误（退出码 2）

常见报错：

FAIL: Windows output requires a little-endian ELF64 x86-64 image FAIL: Windows output requires a position-independent ELF image FAIL: No PT_LOAD segments found FAIL: Invalid Windows icon PNG '…/sce_sys/icon0.png': …

原因与解决（检测逻辑在 core/relinker/elfpatcher/src/windows/WindowsLoadImage.cpp）：

• 架构不对：输入不是 x86-64 位置无关 ELF——确认输入是 64 位可执行文件
• 图标损坏：--windows模式会读取输入同目录下sce_sys/icon0.png作为 EXE 图标，换成一张正常的 PNG（≥64x64）
• 另外注意一个警告：输出名以.exe结尾但没加--windows时，产物仍是 Linux ELF 可执行文件——.exe后缀不会自动选择 Windows 输出，务必显式加--windows

场景9：Guest 模块依赖错误（退出码 2）

常见报错：

FAIL: Cyclic guest initialization dependency: sce_module/libX.elf FAIL: Duplicate guest export after stripping #: … in … and … FAIL: Guest output would overwrite an input module: … FAIL: Guest modules require eager binding; --lazy-binding is incompatible

原因与解决：

• 循环依赖：游戏自带模块之间初始化成环，属于游戏自身结构问题，目前无法通过参数修复
• 重复导出：两个模块导出了同名符号，检查sce_module/下是否混入了重复文件
• 输出覆盖输入：输出路径恰好落在输入模块或输入可执行文件上，换一个输出文件名
• --lazy-binding冲突：带捆绑模块时必须用默认的 eager binding，去掉--lazy-binding

场景10：Code analysis 失败（退出码 2，带 offset）

常见报错：

FAIL: Code analysis: invalid dynamic segment (offset 0x…) FAIL: Code analysis: no code entry points (offset 0x…) FAIL: Code analysis: function exceeds executable segment (offset 0x…)

原因：relinker 对代码段做控制流/重定位分析时，发现输入 ELF 的结构不符合预期（dynamic 段未终止、函数范围越界等，见 core/relinker/relinker/src/analysis/CodeInstructionCollector.cpp）。这通常意味着输入文件被裁剪、重打包或损坏，不是 relinker 的选项问题。

解决方法：

• 换一个来源重新提取完整 ELF，确认文件未被手动修改过
• 若换来源后仍报错，把完整 stderr 和 offset 信息反馈给项目维护者

转换成功但游戏跑不起来？

转换阶段和运行阶段是两回事：

• --autorun会在转换成功后直接启动产物，此时退出码是游戏自己的（显示Raw exit code / Unpacked，见 core/relinker/cli/src/Autorun.cpp），退出码非 0 不等于转换失败
• 运行失败大多与目录布局有关：产物旁边必须有libs/*.prx（从build/core/libs/libs/拷贝对应平台版本）和app0/游戏资源，转换结束时 relinker 会打印期望布局，照着装即可
• 已验证可玩的游戏清单见 docs/user/COMPATIBILITY.md；手柄/键鼠映射问题见 docs/user/INPUT_MAPPING.md
• 构建产物本身出问题（relinker 二进制没有/过旧），重新按 docs/dev/BUILD.md 构建

排查清单：按顺序过一遍

1. ✅ 退出码是1还是2？1改参数，2看FAIL:信息
2. ✅ 输入是否为解密的干净 ELF（非 SELF、非压缩包）
3. ✅sce_module/（或sce_modules//prx/）与输入同目录存在，且没有单复数并存
4. ✅ 参数拼写正确，unused-filter=不带--，选项不冲突
5. ✅ 目标 Windows 时显式加了--windows，且输入为 x86-64 位置无关 ELF
6. ✅ 产物旁按提示摆放了libs/与app0/运行布局
7. ✅ 仍失败：记下错误信息与 offset，反馈给项目维护者

按照这份清单排查，绝大多数 relinker 报错都能在第 1～4 步内解决。祝移植顺利 🎮

相关文档

• 用法与选项表：docs/user/USAGE.md
• 入口与退出码逻辑：core/relinker/main.cpp
• 参数解析：core/relinker/cli/src/CliArgs.cpp
• ELF 输入校验：core/relinker/relinker/src/parsing/ElfReader.cpp
• 构建指南：docs/dev/BUILD.md

【免费下载链接】AnyPS5Tool for automatic PS5 executables porting to Linux and Windows项目地址: https://gitcode.com/GitHub_Trending/an/AnyPS5