一堆能装到真机上跑的 iOS 小示例。记的是墙，不是路。
每篇都不是"跟着我做一遍"的教程，而是哪一步会卡住、卡住的时候屏幕上是什么样子、 以及那句报错为什么在骗你。因为这类活儿真正花时间的从来不是"怎么写"， 是卡住的时候完全不知道卡在哪。
这里面绝大多数坑都是静默失败：编译过、签名过、装机过， 然后什么都没发生 —— 或者报一个跟真实原因毫无关系的错。
网上很多教程开口就是"你需要一个付费开发者账号"，这句话劝退了很多人，而且它是错的。
| 想做的事 | 免费 Apple ID |
|---|---|
| 写个 app 装到自己手机上 | ✅ |
| 桌面小组件 | ✅ |
| 灵动岛 / 实时活动 | ✅ |
| 推送、来电、读健康数据 | ❌ |
| App Groups（01 那个示例要用） | ❓ 见 00 |
| 屏幕共享（广播扩展） | ❓ 见 05 |
分界线很清楚：要不要"服务器主动找上你的手机"。
（最后那个 ❓ 不是含糊其辞 —— 是苹果官方两页说法自相矛盾， 而我们只在付费账号上验过。查证过程写在 05 最后一节。） 免费账号真正的代价不是功能，是签出来的 app 七天后过期（插线再 Run 一次就续上）。
同一堆 doesn't include the App Groups capability，我们撞过两次、
两个完全不同的根因：一次是命令行没人替你去苹果后台注册，
一次是那个名字被别人注册走了。报错里一个字都没提。
所以别照着签名报错去搜索。 它描述的是结果，不是原因。
Xcode 界面上的勾、build setting 里的键 —— 都可能根本没进最终的包。
（我们被 INFOPLIST_KEY_UIBackgroundModes 静默丢掉坑了好几个小时。）
plutil -p YourApp.app/Info.plist # 看 Info.plist 真正有什么
codesign -d --entitlements - YourApp.app # 看权限真正有什么别信界面，信包里的。
完整版见 00 · 入门。
① 踩雷记录 —— 主体。每一条都是真机上撞出来的：现象长什么样、 报错说了什么、真正的原因是什么。它不需要配套代码就能成立 —— 你把它丢给 AI，它就知道该避开什么。
② 可跑的示例 —— 加分项，不是每篇都有。 能重写出一个干净示例的就附上，重写代价太大的就只出雷。 没有代码不等于那篇没价值，往往正相反：越难做出干净示例的地方， 雷越多也越值钱。
| 讲什么 | 代码 | 要付费账号 | |
|---|---|---|---|
| 00-getting-started | 从零把一个 app 装到自己手机上：99 刀要不要花、真要花时怎么申请、签名报错为什么全在说谎 | — | 否 |
| 01-live-activity | 把你自己的角色放上灵动岛：fork 下来换张图就是你的桌宠 | ✅ | 否 |
| 02-calls | 系统级来电界面：CallKit + VoIP 推送 + 音频那条链 | — | 是 |
| 03-permissions | 定位 / 天气 / 健康：被拒绝的时候它们都不报错 | — | 部分 |
| 04-push | 推送：APNs、那把只能下载一次的 .p8、沙盒和生产两台服务器 |
— | 是 |
| 05-screen-share | 让它看一眼你的屏幕：ReplayKit 广播扩展、50MB 里塞一帧、"能不能背着 ta 看"这件事（原来那句断言已更正），以及拿到那张图之后还差的三块 | — | ❓ |
（写完一篇放一篇，不预告。「代码」那一列是加分项，不是门槛。）
不用自己啃。把某一篇的 STEPS.md 整个丢给你的 AI，
告诉它你想做什么，让它照着改。
文档写成这样就是为了这个 —— 术语精确、报错贴原文、 每个坑都写清楚「现象是什么 / 报错说了什么 / 真正的原因是什么」。 人读着累的地方，正是 AI 需要的地方。
目录表里「代码」那一列打 ✅ 的，才带 Xcode 工程。 目前只有 01-live-activity：
clone 下来能直接用 Xcode 打开，模拟器上不用改任何标识符就能跑。
其余目录（00、02、03、04）只有一份 README.md ——
它们讲的是在真项目上撞的墙，不配套示例工程（理由见上面"两类东西"）。
带工程的那个目录里有两份文档：
README.md—— 这篇讲什么、怎么跑起来、先改哪几处STEPS.md—— 从零开始的步骤，后半是踩过的坑（这一节才是重点）
com.yourname.xxx）。
Bundle ID 和 App Group ID 都是全球唯一、先到先得的，
示例不可能给你一个能直接用的值 —— 每篇的 README 会写清楚要改哪几处。
Xcode 26.6 / iOS 26 上写的和验的。免费 Apple ID 能走到哪一步，各篇会分别说明—— 不含糊其辞地写"建议付费账号"，那是最没用的一句话。
这个仓库讲的是原生 app：灵动岛、小组件、系统级来电、HealthKit。 它们的门票是一台 Mac、一个 Xcode，其中一部分还要 99 美元的开发者账号。
但很多事不走这条路也能做，而且那几篇都已经写好了：
| 想做的事 | 免费那条路 | 这个仓库（原生） |
|---|---|---|
| 让 iPhone 收到系统推送 | ios-web-push —— PWA + VAPID + Service Worker，不用 APNs 证书、不用上架 | 04-push：APNs 原生推送（要付费账号，但能做 VoIP 来电） |
| 读心率 / 睡眠，让 AI 感知你的状态 | always-here —— Apple Watch + 快捷指令，不用写 app | 03-permissions：原生 HealthKit（要付费账号，能后台自动传） |
| 让 AI 给你打电话 | callhome —— 自建语音通话栈，转写 / TTS / 留言，声音不出你的服务器 | 02-calls：CallKit 系统级来电界面（锁屏全屏、进通话记录） |
| 让 AI 看一眼你的屏幕 | 有，但不是我们做的：快捷指令的「截屏」动作能拍下当前整块屏幕，配一个能被服务器点火的「收到邮件」自动化，不用写一行 app 代码。做法可以看这位老师写的 ai-screen-peek，讲得比我们细（ |
05-screen-share：ReplayKit 广播扩展（实时画面、ta 亲手开、系统红点一直亮着） |
两条路不是替代关系，是叠加的：先用免费那条把事做成， 等你确实需要"锁屏全屏来电"「灵动岛上一直待着」这种只有原生能给的东西，再来看这边。
别一上来就交那 99 美元。
- 代码和文档 —— Matt（Claude Opus，Anthropic）
- 真机、现象、判断 —— Elle
一个人跑真机、报现象、拍板，一个 AI 写代码和文档。两个人一起撞墙。
之所以要说明这件事，是因为它决定了你该怎么读这个仓库： 每一个坑都是在真机上撞出来的，不是从文档里总结的，也不是编的。
- 「灵动岛冻在 0:00、上面盖个转圈」是拿着手机截图查出来的
- 「
com.example.*被人注册走了」是构建真的失败了才知道的 - 「装机时才被拒」是真的装到一半被
installd拒了
所以这里面没有一句"通常来说""建议你"。 凡是我没实测过的（比如免费账号到底能开哪些 capability）， 文档里会直接写"我没验证过，别只听我的"，而不是含糊过去。
- 示例代码与工程文件：PolyForm Noncommercial 1.0.0。
- README、STEPS 与教程：CC BY-NC 4.0。
- 商业使用须另行取得书面授权，请联系 Cheiineeey。
适用范围与旧版本说明见 LICENSING.md。