如何使用check-prefix-template.sh工具：Madeira前缀模板完整自检指南-创锋一号

如何使用check-prefix-template.sh工具：Madeira前缀模板完整自检指南

【免费下载链接】MadeiraRun x86-64 Windows PC games on jailed iOS via FEX-Emu + Wine + DXMT项目地址: https://gitcode.com/GitHub_Trending/mad/Madeira

Madeira可以在免越狱的 iOS 设备上运行 x86-64 Windows PC 游戏，核心是 FEX-Emu 动态翻译 + Wine 11.4 + DXMT/Metal 图形链路。应用首次启动时，会从内置的 prefix-template.tar.gz 解压出一个精简的 Wine 前缀（prefix）作为 Windows 环境骨架。而 check-prefix-template.sh 就是官方的前缀模板自检工具：一条命令即可检查这个压缩包是否混入了会导致设备故障的"绝对路径符号链接"，让坏模板根本无法发版。

什么是 Madeira 前缀模板？为什么需要自检

把 Windows"搬上"iPhone，离不开 Wine 前缀——一个包含注册表（system.reg、user.reg）和目录骨架的"迷你 Windows 系统"。它的生成与使用流程如下：

环节	负责文件	说明
生成模板	build-prefix-snapshot.sh	在 macOS 上运行`wineboot --init`，剔除 DLL/字体等已随包携带的文件，产出精简压缩包
产物位置	app/Madeira/prefix-template.tar.gz	随 App 打包，分发给每台设备
首次解压	WineProcessBridge.m	应用在首次启动时解压模板并补建`dosdevices/c:`链接

问题在于：模板是在开发者的 Mac 上打出来的。如果打包时把开发者机器上的绝对路径符号链接（例如指向/Users/某某/Documents的链接）一并收进压缩包，那么到了任何玩家设备上，这些链接都指向不存在的路径，变成"悬空链接"。

后果非常隐蔽：所有解析 Windows 壳文件夹（My Documents、Desktop 等）的程序都会静默失败。项目注释里就记录过真实案例——某游戏的日志输出目标配置在"我的文档"下，六个链接全部悬空，导致该游戏始终不产生任何日志，排查成本极高（详见 WineProcessBridge.m 中 ml719 的注释）。

check-prefix-template.sh就是为堵死这个坑而生的。

一键检查步骤：如何运行 check-prefix-template.sh

该脚本用 POSIX sh 编写，无第三方依赖，在有tar和grep的任意 macOS/Linux 环境即可运行。

运行前提：位于仓库根目录（脚本默认相对路径为app/Madeira/prefix-template.tar.gz）。

默认检查（检查仓库自带模板）：

sh tools/check-prefix-template.sh

检查指定压缩包（传入一个参数即可）：

sh tools/check-prefix-template.sh /path/to/your-prefix.tar.gz

💡 小技巧：如果你刚用 build-prefix-snapshot.sh 重新生成了模板，可以紧接着运行本脚本，先自检再提交。

脚本内部逻辑只有三行核心：用tar tzvf列出压缩包内的所有符号链接，取出链接目标，筛出以/开头的绝对路径（放行/tmp、/var、/private这类系统目录），有任何命中即判定失败。

查看检查结果：OK 还是 FAIL？

退出码	输出	含义	你应该做什么
0	`check-prefix-template: OK -- no absolute host symlinks in ...`	✅ 压缩包干净，可安全发版	无需操作
1	`check-prefix-template: FAIL -- absolute host symlink target(s) in ...`（随后逐行列出问题链接）	❌ 存在指向构建机主目录的绝对路径符号链接	重新生成模板，确保六个壳文件夹（Documents、Desktop、Downloads、Music、Pictures、Videos）是普通目录而非链接
1	`check-prefix-template: no such archive: ...`	⚠️ 找不到压缩包	确认在仓库根目录运行，或传对路径参数

脚本在失败时的提示信息本身也是一份排查指南，它会提醒你："Shell folders must be ordinary directories（壳文件夹必须是普通目录）"，并解释原因——iOS 容器的 UUID 在每次重装后会改变，所以哪怕指向容器内绝对路径的链接，迟早也会腐化失效，普通目录才是最稳妥的选择。

为什么这个检查值得纳入你的发版流程

一句话总结这条防御链：

悬空链接 = 静默故障。游戏写不进"我的文档"，日志丢失、存档目录创建失败、游戏启动即退出，症状千奇百怪却都查不到报错。
模板只解压一次。已安装设备的旧前缀不会被自动替换，因此坏模板一旦发出，只能靠运行时修补（见 WineProcessBridge.m 中 ml719 的运行时迁移逻辑）兜底——源头拦截才是根本。
退出码为 1 即"不可能发版"。把sh tools/check-prefix-template.sh加进你的发版检查清单或 CI 前置步骤，坏压缩包就永远到不了玩家手里。

企业官网建设流程全解析