第一次开环境就翻车?大概率漏了这一步校验
第一次开环境就翻车?大概率漏了这一步校验
第一次跑起来就失败,是所有折腾系统、刷机、改配置类项目里最常见也最令人沮丧的一幕:命令退出码是 0,日志里没有被标红的异常,可功能就是不工作。多数人会把时间花在"再试一次"和"换个参数再试一次"上,却很少回头问一句:我到底是凭什么判断这一步已经成功了?
HermesEnabler(在任意 Apple Watch 上启用 Hermès 表盘的工具)给出了一个罕见的正例:它几乎把"校验"当成了和业务逻辑同等重要的功能来写。代码里到处是前置断言、布局白名单、写后回读和崩溃守门。本文就用这套真实工程代码,把"第一次开环境为什么容易翻车"拆成三件事:失败现场怎么定位、校验顺序为什么不能颠倒、以及如何把校验固化成可重复执行的脚本。
一、失败现场:三种"看起来成功"的假象
先把实验对象摆出来。项目 README 描述的用途是在非 Hermès 版本的 Apple Watch 上启用对应表盘,实际效果如下:
要让这个效果出现,应用必须越过一串系统边界:读取自己的 App Group 权限、向 MCM(MobileContainerManager)申请沙箱扩展、打开 systemgroup.com.apple.mobilegestaltcache 容器、改写 com.apple.MobileGestalt.plist。任何一环"看起来通了但实际没通",表现出来都只是开关拨不动。
假象一:初始化返回了,但能力根本没就位
BQCoreInit() 的实现(HermesEnabler2/BQCore.m)里最关键的一行不是目录创建,而是这个合取判断:
ok = (g.create && g.get_one && g.copy_token && g.consume && g.release);
BQLog(@"core init ok=%d", ok);
五个 MCM 私有符号必须全部通过 dlsym 拿到,才算初始化成功。少任意一个,后续所有调用都会在 ContentModel.perform(_:) 的第一道闸门被拦下:
if !BQCoreInit() {
result = "MobileGestalt access is unavailable on this device."
}
注意它用的是 dispatch_once 的静态 BOOL ok。这意味着校验只跑一次,结果被永久缓存——好处是不会每次点开关都重新探测,代价是如果第一次探测时环境没准备好(比如侧载还没点信任、App Group 还没生效),这个进程的整个生命周期都会认为设备"不支持"。第一次开环境翻车,经常就翻在这里:不是设备不支持,而是校验发生在环境就绪之前。
假象二:拿到了沙箱 token,但目标目录打不开
这是全项目最值得抄的一段工程习惯。在 bq_escape_class2_subpath 和 bq_escape_class2_stage 里,MCM 已经把扩展句柄返回了(h >= 0),换成一般的写法,这里就该 return h 宣布成功了。但代码多做了一步:
int64_t h = bq_query_escape(2, bid, NO, 3, domain, 0x8100000000ULL, ..., &path);
if (h >= 0) {
// A token for the symlink path is not enough: the editor needs the
// resolved target. Verify before reporting success.
DIR *d = opendir(target.fileSystemRepresentation);
if (!d) {
BQLog(@"class2-subpath: token did not open target (%@)", path ?: @"(null)");
if (g.release) g.release(h);
last = -5;
continue;
}
closedir(d);
...
}
注释写得很直白:句柄有效不等于路径可达。拿到的是一个指向符号链接的凭据,而真正要编辑的是链接解析之后的目标。不做这一步 opendir,失败会推迟到写入阶段爆发,那时错误信息只会告诉你"写失败",而不会告诉你"第 1 条逃逸策略其实从头就没生效"。
假象三:错误码被翻译成了"操作建议",但没人看
项目里有一个专门的错误常量:
NSString * const BQNoSandboxTokenError = @"the MCM query returned no sandbox token — send Documents/bqtool.log";
ContentModel.perform(_:) 在收尾处判断这个字符串并弹出提示,ContentView 里的弹窗正文也不是无意义的"发生未知错误",而是明确指向两个可检查项:App Group 配置是否缺失、watchOS 版本是否兼容。
这里对应一个非常现实的翻车点:HermesEnabler2.entitlements 里 App Group 是模板化的——
<key>com.apple.security.application-groups</key>
<array><string>group.$(COMPANION_BUNDLE_IDENTIFIER)</string></array>
而 scripts/create_ipa.sh 允许你用 --bundle-id 改 Bundle ID。改了 ID 却没在签名时同步 group 前缀,BQGroupID() 就取不到任何 group,bq_escape_symlink 直接返回 -6,最终落到那句"no sandbox token"上。参数变了、配置没跟着变,是第一次开环境最经典的死法,而它的报错信息只有在你事先把错误码翻译成人话之后才有用。
二、校验顺序为什么不能颠倒
把上面三个现场放在一起,能看出一个共同结构:失败点都不在"写"这个动作上,而在"写之前的判断"和"写之后的确认"上。而这两件事的顺序,是不能换的。
一个可信的写入链路,在 HermesEnabler 里被拆成了严格的阶段,且每阶段都有独立的失败出口:
第一阶段:能力探测。 BQCoreInit() 只回答"这套私有接口在不在",不回答"能不能写"。
第二阶段:前提确认。 所有写操作第一句都是同一句话:
if (!BQBackupExists()) {
if (err) *err = @"Back up MobileGestalt first.";
return NO;
}
BQSetHermesEnabled、bq_setMGCacheExtraKeys、bq_setMGCacheExtraStrings、BQSetSalesRegion、BQSetScreenResolution 无一例外。而 BackupView 在 UI 层做了同一件事——没有备份时 ContentView 根本不渲染功能列表,只显示首次备份页。
关键在于 BQBackupExists() 的判定不是"文件存在":
NSDictionary *plist = [NSDictionary dictionaryWithContentsOfFile:BQBackupPath()];
return [plist[@"CacheExtra"] isKindOfClass:[NSDictionary class]] &&
[plist[@"CacheData"] isKindOfClass:[NSData class]];
它要求文件能被解析成 plist,且 CacheExtra 是字典、CacheData 是二进制数据。这是结构校验而不是存在性校验。存在性校验会放过一个 0 字节的文件或半截写入的文件,而那正是崩溃后最常见的残留状态。
第三阶段:基线固化,且不可覆盖。 初始备份只允许成功一次:
if (initial && [[NSFileManager defaultManager] fileExistsAtPath:BQBackupPath()]) {
if (err) *err = @"An initial backup already exists and will not be overwritten.";
return nil;
}
并且备份写完要回读比对:
if (![data writeToFile:path atomically:YES] ||
![[NSData dataWithContentsOfFile:path] isEqualToData:data]) {
if (err) *err = @"Backup could not be verified.";
return nil;
}
顺序为什么不能反? 因为"原始基线"这种东西一旦被污染就没有第二份。如果你先写入再备份,备份下来的就是已经被改过的 MobileGestalt,此后所有"恢复出厂"操作都只是把错误状态再写一遍。这也是为什么 BQSaveGestalt 把自动备份放在逃逸和写入之前:
if (!bq_auto_backup(err)) return NO;
NSString *link = nil;
int64_t h = BQEscape(kMGCaches, &link);
第四阶段:布局白名单,比版本号更硬。 这是全项目最能解释"为什么第一次就翻车"的部分。启用 Hermès 需要直接改 CacheData 里的字节,而字节偏移随 watchOS 构建而变。项目没有用"系统版本 ≥ x 就支持"这种脆弱判断,而是列了一张四元组表:
static const BQDeviceBrandLayout kDeviceBrandLayouts[] = {
{"24S5284h", "DB380F61-0014-418D-9799-876666B459E3", 0x1950, 0x348, 0x16e9},
{"24R359", "6F8372B0-1583-4031-A4BC-A54A18B0DD5A", 0x1947, 0x348, 0x16e1},
...
};
命中条件必须全部满足:kern.osversion 对应的 build 串相同、当前 plist 与备份 plist 的 CacheUUID 都等于表中值、两边 CacheData 长度都等于表中长度、偏移量在合法范围内:
if (!layout) {
if (err) *err = [NSString stringWithFormat:@"DeviceBrand CacheData layout is not verified for build %s.", build];
return NO;
}
注意文案用的是 "not verified"(未经验证),而不是 "unsupported"(不支持)。这个措辞区别很有价值:未知的构建不是被判定为不可行,而是被判定为不可信。默认拒绝,永远比默认放行安全。
有意思的是,工程文件与文档在这里存在一处真实的不一致:README 声明"仅支持 watchOS 27.0 至 27.3 beta 1",但 HermesEnabler2.xcodeproj/project.pbxproj 里 WATCHOS_DEPLOYMENT_TARGET = 26.0。也就是说版本限制并没有落在构建层,构建不会因为系统版本不符而失败,真正的把关完全交给了运行时的布局表。这恰好反证了上面的观点:能靠结构校验的地方,不要靠版本文案。
第五阶段:写后回读,逐字节复述。 BQSaveGestalt 写完立即重新解析:
BOOL ok = bq_write_data(plist, data, err);
if (ok) {
NSMutableDictionary *check = [NSMutableDictionary dictionaryWithContentsOfFile:plist];
if (!check) {
ok = NO;
if (err) *err = @"post-write verification failed";
}
}
Hermès 开关更进一步,把"我期望的状态"和"磁盘上的状态"做逐字节比对:开启时要求 present 字节为 1 且 4 字节值为 {1,0,0,0};关闭时要求这两个位置与备份完全一致;同时 CacheExtra 里的 override 键要么不存在、要么等于原始值。任一项不符就返回"The cache was written, but DeviceBrand could not be verified."
这条文案值得单独强调:它明确区分了"写失败"和"写成功但校验失败"。前者是权限/IO 问题,后者是布局假设错了。如果校验被省掉,这两种情况会被合并成一个"好像成功了",而用户只会在重启后看到一个毫无变化的表盘。
第六阶段:恢复也要先验。 BQRestoreGestaltBackup 在真正写回之前,先比对 CacheUUID 与 CacheData 长度是否与备份一致,然后在自动备份之后再比对一次:
if (![current[@"CacheUUID"] isEqual:backupPlist[@"CacheUUID"]] ||
[current[@"CacheData"] length] != [backupPlist[@"CacheData"] length]) {
BQEndEscape(h);
if (err) *err = @"MobileGestalt layout changed before restore; no data was written.";
return NO;
}
为什么要比两次?因为两次比对之间隔着一次自动备份和一次沙箱逃逸,而系统可能在这段时间里重建缓存。校验不是一次性动作,它必须紧贴着危险操作。写回后再用 isEqualToData 确认整个文件与备份一致,才算完成。
顺带一提,写入本身也做了顺序保护:bq_write_data 优先用 O_RDWR | O_NOFOLLOW 原地截断写入并 fsync,失败时用原始字节回滚,再退化到"临时文件 + fsync + rename"的原子替换。加上 O_NOFOLLOW 是防止目标路径被替换成符号链接——这是上一节符号链接逃逸策略的必然副作用,也是"改造环境"类工具必须承担的自我防御。
三、把校验写成脚本:最小可重复骨架
上面的校验逻辑都在运行时。但"第一次开环境"的失败,有一半发生在运行时之前:编译不出、装不上、装上了但手表端没嵌入。scripts/create_ipa.sh 就是把这部分校验前置成脚本的例子,它的结构可以直接当模板抄。
第一步是让脚本对错误敏感,而不是对错误宽容:
#!/bin/bash
set -euo pipefail
-e 让任意命令失败即中止,-u 让未定义变量报错,-o pipefail 让管道中任一环失败都算失败。没有这三件套,xcodebuild ... | tail 这种写法会把构建失败吞成成功。
第二步是参数校验,且校验规则要写在使用参数之前:
if [[ ! "$bundle_id" =~ ^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$ ]]; then
echo "Invalid bundle identifier: $bundle_id" >&2
exit 2
fi
这个正则要求至少两段、每段只允许字母数字和连字符。它挡住的不只是拼写错误——Bundle ID 会通过 COMPANION_BUNDLE_IDENTIFIER 派生出 .watchkitapp 后缀和 group.$(COMPANION_BUNDLE_IDENTIFIER) 的 App Group 前缀,一个非法字符会在三个地方同时炸开,而且报错点离原因很远。
第三步是环境校验,且把结论说清楚:
if [[ "$(uname -s)" != "Darwin" ]]; then
echo "This script needs macOS and Xcode to compile iOS and watchOS apps." >&2
echo "It does not need a signing certificate, provisioning profile, or Apple account." >&2
exit 1
fi
第二行是很多人会忽略的细节:它不仅说了"缺什么",还说了"不需要什么"。第一次上手的人最容易在"我是不是得先买开发者账号"这一步卡住。
第四步,也是最容易被跳过的一步——构建后的断言。脚本在 xcodebuild 成功返回之后并没有直接打包,而是继续检查三件事:
if [[ ! -d "$app_path" ]]; then
echo "Build succeeded but the iPhone app was not found at: $app_path" >&2
exit 1
fi
watch_app="$(find "$app_path/Watch" -maxdepth 1 -type d -name '*.app' -print -quit 2>/dev/null || true)"
if [[ -z "$watch_app" ]]; then
echo "The built iPhone app does not contain an embedded Watch app." >&2
exit 1
fi
if find "$app_path" -name embedded.mobileprovision -print -quit | grep -q .; then
echo "A provisioning profile was embedded; refusing to label this IPA unsigned." >&2
exit 1
fi
这三段分别对应三种真实翻车:产物路径变了、Watch App 没嵌进去、签名配置把描述文件带了进来。第三种最值得学——它发现异常后选择的是拒绝继续,而不是打个警告继续打包。因为一旦脚本在不满足前提的情况下产出了名为 "unsigned" 的 IPA,后续所有排查都会被这个错误标签带偏。
把这个脚本的结构抽出来,就是一个可以复用到任何"首次搭环境"场景的最小骨架:
#!/bin/bash
set -euo pipefail
preflight() {
# 1. 平台/运行时是否匹配
# 2. 必需工具是否在 PATH 中
# 3. 参数格式是否合法(在消费参数之前)
# 4. 依赖产物是否就位(不只看存在,还看结构)
:
}
postcheck() {
# 1. 产物是否在预期路径
# 2. 子产物是否真的被嵌入
# 3. 是否混入了不该出现的东西
:
}
preflight
run_the_actual_work
postcheck
三条工程约束值得写进注释:
- 单一职责的退出码:
scripts/create_ipa.sh用1表示环境不满足、2表示参数非法。调用方(或 CI)可以据此区分"我的机器不对"和"我的参数不对",而不必去正则匹配 stderr。 trap清理临时目录:脚本用mktemp -d建临时构建目录,再用trap cleanup EXIT兜底。否则校验失败中途退出时,/tmp里会留下几 GB 的DerivedData,第二次运行时磁盘不足又变成一个新的"神秘失败"。- 输出结论而不只是输出日志:脚本结尾明确打印出产物路径、嵌入的 Watch App 路径、两个 Bundle ID,以及"请用你自己的证书重新签名"。这是"校验通过"应该给出的信息粒度——可被复述、可被核对。
运行时也需要同一种"守门"思路
脚本能守住构建期,守不住运行期。HermesEnabler 里有一个可以直接借鉴的模式:给不可靠操作加一对"起跑前标记 / 结束后清除"的崩溃守门。在 BQCoreInit() 里:
if (gClass2ParentEnabled && [defs boolForKey:@"BQClass2ParentCrashGuard"]) {
gClass2ParentEnabled = NO;
[defs setBool:NO forKey:@"BQClass2ParentEnabled"];
[defs setBool:NO forKey:@"BQClass2ParentCrashGuard"];
BQLog(@"class2-parent disabled after a previous attempt did not finish");
} else if (gClass2ParentEnabled) {
[defs setBool:YES forKey:@"BQClass2ParentCrashGuard"];
}
BQCore.h 里对这条路径的注释说明了原因:某些构建上移动应用自身的 Library 目录会导致进程被沙箱杀掉。于是策略变成——上次如果没走完(标记还在),这次就自动关闭该路径。这本质上是一次跨进程的校验:不信任"上次应该成功了",而是检查"上次有没有留下未完成的证据"。
同样的思路也体现在可观测性上。BQLog() 用 NSLock + NSFileHandle 把每一行同时写进 NSLog 和 Documents/bqtool.log,并且在两处关键决策点打印足够的信息:
BQLog(@"app group: id=%@ root=%@", gid ?: @"(none)", root ?: @"(none)");
BQLog(@"strategy %@: cls=%llu ident=%@ part=%llu result=%p path=%@ token=%s consume=%lld",
label, cls, ident, part, res, path ?: @"(null)", tok ? "YES" : "NO", (long long)h);
第一行告诉你"我以什么身份在跑",第二行为每一条逃逸策略记录输入、输出和句柄结果。翻车时你不需要猜哪条策略生效了,日志里写得很清楚。这也是为什么那个错误常量直接把日志路径写进了文案里——校验失败的提示必须指向下一步动作,否则校验只是把崩溃换了个说法。
落地清单
如果只记三句话:
- 判断"能不能"和判断"成不成"是两件事。 前者在动作前,不能缓存太久;后者在动作后,必须读回磁盘确认。HermesEnabler 用
BQCoreInit()做前者,用BQSaveGestalt和逐字节memcmp做后者。 - 默认拒绝优于默认放行。 未知 build 是 "not verified" 而不是 "unsupported";脚本发现
embedded.mobileprovision是exit 1而不是继续。任何"先跑起来再说"的宽容,都会把问题推到最难排查的那一层。 - 把校验写成能重复执行的代码,而不是记在脑子里的步骤。 一次
set -euo pipefail加三段构建后断言,省下的是第二次、第三次开环境时的全部猜测成本。
第一次开环境翻车并不可怕,可怕的是翻车之后你无法回答"到底哪一步没过"。把这个问题变成一条 exit 1 和一个明确的错误字符串,翻车就从玄学变成了工程问题。
