转载 一文读懂 Skills｜从概念到实操的完整指南

原文地址

Agent 正在经历从“聊天机器人”到“得力干将”的进化，而 Skills 正是这场进化的关键催化剂。

你是否曾被 Agent 的“不听话”、“执行乱”和“工具荒”搞得焦头烂额？

本文将带你一文弄懂 Skills ——这个让 Agent 变得可靠、可控、可复用的“高级技能包”。

我们将从 Skills 是什么、如何工作，一路聊到怎样写好一个 Skills，并为你推荐实用的社区资源，带领大家在 TRAE 中实际使用 Skills 落地一个场景。

无论你是开发者还是普通用户，都能在这里找到让你的 Agent “开窍”的秘诀。

你是否也经历过或者正在经历这样的“ Agent 调教”崩溃时刻？

• 规则失效： 在 Agent.md 里写下千言万语，Agent 却视若无睹，完全“已读不回”。
• 执行失控： 精心打磨了无数 Prompt，Agent 执行起来依旧像无头苍蝇，混乱无序。
• 工具迷失： 明明集成了强大的 MCP 工具库，Agent 却两手一摊说“没工具”，让人摸不着头脑。

如果这些场景让你感同身受，别急着放弃。终结这场混乱的答案，可能就是 Skills。

什么是 Skills

“Skills” 这个概念最早由 Anthropic公司提出，作为其大模型 Claude的一种能力扩展机制。简单来说，它允许用户为 Claude 添加自定义的功能和工具。随着这套做法越来越成熟，并被社区广泛接受，Skills 如今已成为大多数 Agent 开发工具和 IDE 都支持的一种标准扩展规范。

一个 Skills 通常以一个文件夹的形式存在，里面主要装着三样东西：一份说明书（SKILL.md）、一堆操作脚本（Script）、以及一些参考资料（Reference）。

你可以把一个 Skill 想象成一个打包好的“技能包”。它把完成某个特定任务所需的领域知识、操作流程、要用到的工具、以及最佳实践全都封装在了一起。当 AI 面对相应请求时，就能像一位经验丰富的专家那样，有条不紊地自主执行。

一句话总结： 要是把 Agent 比作一个有很大潜力的大脑，那 Skills 就像是给这个大脑的一套套能反复用的“高级武功秘籍”。 有了它，Agent 能从一个“什么都略知一二”的通才，变成在特定领域“什么都擅长”的专家。

Skill 原理介绍

📚 官方解释：Agent Skills

Skill 的架构原理：渐进式加载

Skill 的设计很巧妙，它运行在一个沙盒环境里，这个环境允许大模型访问文件系统和执行 bash 命令（可以理解为一种电脑操作指令）。在这个环境里，一个个 Skill 就像一个个文件夹。Agent 就像一个熟悉电脑操作的人，通过命令行来读取文件、执行脚本，然后利用结果去完成你交代的任务。这种“按需取用”的架构，让 Skill 成为一个既强大又高效的“工具箱”。

为了平衡效果和效率，Skill 设计了一套聪明的三层分级加载机制：

Level 1：元数据（始终加载）

元数据就像是 Skill 的“名片”，里面有名称（name）和描述（description），是用 YAML 格式来定义的。Claude 在启动的时候，会把所有已经安装的 Skill 的元数据都加载进来，这样它就能知道每个 Skill 有什么用、什么时候该用。因为元数据很轻量，所以你可以安装很多 Skill，不用担心把上下文占满。

Level 2：说明文档（触发时加载）

SKILL.md 文件的正文就是说明文档，里面有工作流程、最佳实践和操作指南。只有用户的请求和 Skills 元数据里的描述相符时，Claude 才会用 bash 指令读取这份文档，把内容加载到上下文里。这种“触发式加载”能保证只有相关的详细指令才会消耗 Token。

Level 3：资源与代码（按需加载）

Skills 还能打包一些更深入的资源，比如更详细的说明文档（FORMS.md）、可执行脚本（.py）或者参考资料（像 API 文档、数据库结构等）。Claude 只有在需要的时候，才会通过 bash 去读取或执行这些文件，而且脚本代码本身不会进入上下文。这样一来，Skills 就能捆绑大量信息，几乎不会增加额外的上下文成本。

Skills 的调用逻辑：从理解意图到稳定执行

那么，Agent 是如何智能地选择并执行一个 Skill 的呢？整个过程就像一位经验丰富的助理在处理工作：

1. 意图匹配（找到对的人）： Agent 首先聆听你的需求，然后快速扫一眼自己手头所有 Skill 的“名片夹”（元数据），寻找最匹配的那一张。
2. 读取手册（看懂怎么干）： 找到合适的 Skills 后，Agent 会像模像样地翻开它的“操作手册”（SKILL.md），仔细研究详细的执行步骤和注意事项。
3. 按需执行（动手开干）： 根据手册的指引，Agent 开始工作。如果需要，它会随时从“工具箱”里拿出脚本或工具来完成具体操作。
4. 反馈结果（事毕复命）： 任务完成后，Agent 向你汇报最终结果，或者在遇到困难时，及时向你请教。

Skills vs. 其他概念的区别

为了更清晰地理解 Skills 的独特价值，我们不妨把它和另外两个容易混淆的概念——快捷指令（Command） 和 原子工具（MCP）——放在一起做个对比。用一个厨房的例子就很好懂了：

我们也列举了几个大家容易混淆的其他功能，一起来对比看看。

📚 官方博客解释：Skills explained: How Skills compares to prompts, Projects, MCP, and subagents

什么是好的 Skills：从“能用”到“好用”

Good Skills vs Bad Skills

如何写好 Skills

1. 原子性（Atomicity）： 坚持单一职责，让每个 Skill 都像一块积木，小而美，专注于解决一个具体问题，便于日后的复用和组合。
2. 给例子（Few-Shot Prompting）：这是最关键的一点，与其费尽口舌解释，不如直接给出几个清晰的输入输出示例。榜样的力量是无穷的，模型能通过具体例子，秒懂你想要的格式、风格和行为。
3. 立规矩（Structured Instructions）：
   1. 定角色：给它一个明确的专家人设，比如“你现在是一个资深的市场分析师”。
   2. 拆步骤：把任务流程拆解成一步步的具体指令，引导它“思考”。
   3. 画红线：明确告诉它“不能做什么”，防止它天马行空地“幻觉”
4. 造接口（Interface Design）：像设计软件 API 一样，明确定义 Skill 的输入参数和输出格式（比如固定输出 JSON 或 Markdown）。这让你的 Skill 可以被其他程序稳定调用和集成。
5. 勤复盘（Iterative Refinement）：把 Skills 当作一个产品来迭代。在实际使用中留心那些不尽如人意的“Bad Case”，然后把它们变成新的规则或反例，补充到你的 Skills 定义里，让它持续进化，越来越聪明、越来越靠谱。

📚 一些官方最佳实践指南：技能创作最佳实践

社区热门 Skills 推荐

刚开始接触 Skills，不知从何下手？不妨从社区沉淀的这些热门 Skills 开始，寻找灵感，或直接在你的工作流中复用它们。

Claude 官方提供的 Skills

📚 官方 Skills 仓库：https://github.com/anthropics/skills

学习 Claude 官方的 Skills 仓库可以帮助我们最快的了解 Skills 的最佳实践，便于我们沉淀出自己的 Skills。

如何快速使用官方 Skills？
大多数官方 Skills 都能直接下载，或者通过 Git 克隆到本地。在 TRAE 等工具里，一般只需把这些 Skills 的文件夹放到指定的 Skills 目录，接着重启或刷新 Agent，它就会自动识别并加载这些新能力。具体操作可参考工具的使用文档。
更多细节可参考下面这部分内容：如何在 TRAE 里快速用起来

Claude 官方提供的 Skills 列表

社区其他最佳实践

如何在 TRAE 里快速使用

理论说再多，不如亲手一试。我们先讲一下如何在 TRAE SOLO 中创建并应用一个 Skill 并以基于飞书文档的 Spec Coding为例讲解一下如何利用 Skills 快速解决一个实际问题。

Skill 创建

方式一：设置中直接创建

TRAE 支持在设置页面可以快速创建一个 Skill

按下快捷键 Cmd +/ Ctrl + 通过快捷键打开设置面板。

在设置面板左侧找到「规则技能」选项

找到技能板块，点击右侧的「创建」按钮。

你会看到一个简洁的创建界面，包含三要素：Skill 名称、Skill 描述、Skill 主体。我们以创建一个“按规范提交 git commit”的 Skill 为例，填入相应内容后点击「确认」即可。

填入我们需要的内容「确认」即可

方式二：直接解析 SKILL.md

在当前项目目录下，新增目录.trae/Skills/xxx 导入你需要文件夹，和 TRAE 进行对话，即可使用。

可以在「设置 - 规则技能」中看到已经成功导入

方式三：在对话中创建

目前 TRAE 中内置了 Skills-creator Skills ，你可以在对话中直接和 TRAE 要求创建需要的 Skills

Skill 使用

在 TRAE 里使用技能很容易，你加载好需要的技能后，只需在对话框中用日常语言说明你的需求就行。

• 例如，输入“帮我设计一个有科技感的登录页面”，系统就会自动调用“frontend-design”技能。
• 例如，输入“帮我提取这个 PDF 里的所有表格”，系统会自动调用“document-Skills/pdf”技能。
• 例如，输入“帮我把这片技术文档转为飞书文档”，系统会自动调用“using-feishu-doc”技能。

系统会自动分析你的需求，加载技能文档，还会一步步指导你完成任务！

实践场景举例

还记得引言里提到的那些问题吗？比如说，项目规则文件（project\_rules）有字符数量的限制；又或者，就算你在根规则文件里明确写好了“在什么情况下读取哪个文件”，Agent 在执行任务时也不会按照要求来做。

这些问题的根本原因是，规则（Rules）对于 Agent 而言是固定不变的，它会在任务开始时就把所有规则一次性加载到上下文中，这样既占用空间，又不够灵活。而 技能（Skill）采用的是“逐步加载”的动态方式，刚好可以解决这个问题。所以，我们可以把之前那些复杂的规则场景，重新拆分成一个个独立的技能。

接下来，我们通过一个基于飞书文档的“Spec Coding”简单流程，来实际操作一下如何用技能解决问题。

什么是 Spec Coding？

Spec Coding 提倡“先思考后行动”，也就是通过详细定义可以执行的需求规范（Specification）来推动 AI 开发。它的流程包含“需求分析、技术设计、任务拆解”的文档编写过程，最后让 AI 根据规范来完成编码。这种一步步的工作流程能保证每一步都有依据，实现从需求到代码的准确转化。

让我来分析一下这个场景

上面提到将开发过程划分为四个关键阶段，所以要完成 “需求分析、技术设计、任务拆解” 的飞书文档撰写，还有最终的代码实现。为此，我们需要不同的技能来满足不同场景下的文档编写需求，并且要教会 Agent 如何使用飞书工具进行创作协同。

下面我们就一起完成上面提到的 Skills 的设计实现。

多角色专家 Skills

通过实现多角色 Skills 通过创建多个交付物过程文档，约束后续的编码，为编码提供足够且明确的上下文，每个Skill 专注完成一件事

• 下面让我们进一步详细设计

​按照上述的表格我们就可以大致明确我们需要的 Skills 该如何实现了。

• 本次只作为一个例子大家可以参考上面创建 Skill 的教程自己完成一下这个多角色 Skills 的创建和调试，当然正如上面所述好的 Skill 需要在实践中逐渐优化并通过场景调用不断进行优化的

飞书文档使用 Skill

飞书文档的格式是 markdown 的超集，我们 Skill 的目的则是教会 Agent 飞书文档的语法，便于 Agent 写出符合格式的 md 文件。并通过约束 Agent 行为，充分利用飞书文档的评论的读写完成多人协作审阅的过程，用户通过在飞书文档评论完成相关建议的提出，Agent 重新阅读文档和评论，根据建议进一步优化文档，实现文档协作工作流。

Spec Coding Skill

上面我们实现了多个角色 Skills 和一个功能 Skill，但实际使用时，还需要有一个能统筹全局的技能，来实现分工协作。把上述多个技能组合起来，告诉智能体（agent）整体的规格编码（spec coding）流程，完成工具技能和角色技能的组合与调度。

如此我们就能快速搭建一个规格编码工作流程，完成基础开发。当然也可以参考上面的逻辑，用技能来重新复刻社区里的规格编码实践（如 SpecKit、OpenSpec 等）。

总结

上述场景提到了两种不同风格的 Skill（角色型，工具型），利用 Skill 的动态加载机制（取代固定规则的一次性加载方式），完成了复杂场景下的任务分解；通过 不同角色技能的分工协作（避免 Agent 什么都做导致执行混乱）；尝试借助飞书文档形成协作闭环（打通人机交互的最后一步），有效解决了 Agent “不听话、执行乱、工具少” 的问题，让 AI 从 “对话助手” 真正转变为 “可信赖的实干家”，实现从需求提出到代码产出的高效、精准、协作式交付。

Q & A | 一些常见问题

为什么我写的 Skills 不生效，或者效果不符合预期？

那十有八九是你的“名片”（Description）没写好。

记住，Agent 是通过读取 Skills 的 Description 来判断“什么时候该用哪个 Skill”的。要是你的描述写得含糊不清、太专业或者太简单，Agent 就很难明白你的意思，自然在需要的时候就不会调用这个 Skill。所以，用大白话写的清晰、准确的Description，对 Skill 能否起作用至关重要。

使用 Skills 的效果，会受到我选择的大语言模型（LLM）的影响吗？

会有影响，不过影响的方面不一样。

• 一个更强大的模型，主要影响“挑选”和“安排”技能的能力。 它能更准确地明白你的真实想法，然后从一堆技能里挑出最适合的一个或几个来解决问题。它的优势体现在制定策略方面。
• 而技能本身，决定了具体任务执行的“最低水平”和“稳定性”。 一旦某个技能被选中，它里面设定好的流程和代码是固定的，会稳定地运行。所以，技能编写得好不好，直接决定了具体任务能不能出色完成。。

Skills 是不是万能的？有什么它不擅长做的事情吗？

当然不是万能的。 Skills 的主要优势是 处理那些流程明确、边界清晰的任务。 在下面这些情况中，它可能就不是最好的选择了：

• 需要高度创造力的任务： 像写一首饱含情感的诗，或者设计一个全新的品牌标志。这类工作更需要大模型本身的“灵感”。
• 需要实时、动态做决策的复杂策略游戏： 比如在变化极快的金融市场中做交易决策。
• 单纯的知识问答或开放式闲聊： 如果你只是想问“文艺复兴三杰是谁？”，直接问大模型就可以，不用动用 Skills 这个“大杀器”。

我发现一个社区的 Skills 很好用，但我可以修改它以适应我的特殊需求吗？

当然可以，我们强烈建议你这么做！

大多数共享的 Skill 都支持用户“Fork”（也就是“复制一份”）并进行二次开发。你可以把通用的 Skill 当作模板，在自己的工作空间里复制一份，然后修改里面的逻辑或参数，以适应你自己的业务需求。这对整个生态的共建和知识复用很重要。

结语｜让 Agent 成为你真正的“行动派”

Skill 的出现，为 AI 从“对话式助手”转变为“可信赖的执行者”搭建了关键的技术桥梁。它用结构化的方法把领域知识、操作流程和工具调用逻辑封装起来，解决了 Agent 规则失效、执行失控的混乱问题，让 AI 的能力输出变得可以控制、值得信赖且高效。

Skill 的核心价值在于：

• 精准实际痛点： 通过巧妙的三级加载机制（元数据→说明文档→资源）平衡上下文效率与功能深度，在功能深度和上下文效率之间找到了一个绝佳的平衡点，既避免了宝贵 Token 的浪费，又确保了任务执行的精准性，实现了 Agent 上下文的动态加载能力。
• 生态赋能，降低门槛： 无论是官方还是社区，都提供了丰富的资源（如 Claude 官方仓库、SkillsMP 市场等），让普通用户也能轻松站在巨人的肩膀上，快速复用各种成熟的能力。

虽然 Skill 不是万能的，但它在“确定性流程任务”上的优势无可替代。未来，随着 AI 模型能力的提升与 Skill 生态的进一步完善，我们有望看到更多跨领域、可组合的 Skill 出现——让 AI 从“样样懂一点”的通才，真正进化为“事事做得好”的专家协作伙伴。

不妨从今天开始，尝试创建你的第一个 Skill：将你最擅长的领域经验封装成可复用的能力，让 AI 成为你延伸专业价值的放大器。

​

Skip 开源：从“卖工具”到“卖信任”的豪赌

在宣布 Fuse 版本对独立开发者免费 仅两个月后，Skip Tools 再次做出惊人之举——全面免费并开源核心引擎 skipstone。这意味着 Skip 彻底改变了经营方式：从“卖产品”转向“卖服务+社区赞助”。这次变化，既有对之前商业模式执行不佳而被迫调整的无奈，也体现了 Skip 团队的果敢——在当前 AI 盛行、开发工具格局固化的背景下，主动求变，力求突破。

很多优秀且有特点的产品没能获得应有的使用量，最大的阻碍往往不是技术，而是“信任”。正如 Skip 官方所言，企业最担心的是“rug pull”——万一公司倒闭或被收购，押注在这个工具上的产品和技术栈将面临推倒重来的风险。Skip 希望通过开源消除这种信任危机，让自己和其他跨平台工具站在同一起跑线上，同时激活社区力量，加速生态建设。

尽管社区对 Skip 的开源决定给予了充分肯定，但也有不少人担心：在放弃了 license key 这一稳定收入来源后，仅靠赞助模式能否支撑持续开发成本？毕竟，成功的开源商业案例虽有，但失败的也不少。这种担忧并非杞人忧天。在我撰写本期周报时（宣布开源数天后），尽管开源消息在社交媒体上引发了热议，但在 GitHub 上，Skip 的个人赞助者仅有十几位。从“热闹的讨论”到“真金白银的支持”，中间的鸿沟似乎比想象中还要深。这或许也解释了为什么 Skip 最终选择了开源——在无法说服开发者"付费使用"时，至少要争取到他们"免费使用"的机会。

一个有趣的现象是，在肯定与忧虑并存的情绪中，讨论的焦点悄然发生了变化：从“为什么要花钱买 Skip 而不是用免费的 KMP?”变成了“你是更喜欢写 Swift 还是 Kotlin?”。这个转变意义重大——它意味着 Skip 已经成功将竞争维度从“商业模式”转移到了“语言生态”，而参与竞争的主体也从“一家小公司”扩展为“整个 Swift 社区”。在这场语言之争中，Skip 聪明地（或许是无意间）将自己的角色从“主角”变成了“基础设施”。

Skip 最早的出发点是看到了一个商业机会，认为有足够的商业回报。如果不是有这样的预期，仅靠官方或社区的力量，Swift 可能无法快速推进在其他平台上的进展。这一路径与 The Browser Company 为了打造 Arc 浏览器而大力推动 Swift 在 Windows 平台上的适配如出一辙。

作为一个 Swift 开发者，我由衷希望 Skip 的这次调整能够取得预期效果。开源是一场信任的实验，也是一次生态的投资。如果你也期待 Swift 能在 iOS 之外的平台上拥有更多可能，不妨从成为一个独立赞助者($10/月)做起——这不仅是对 Skip 的支持，更是对整个 Swift 跨平台生态的投票。开源的 Skip 能走多远，取决于有多少人愿意从旁观者变成参与者。

本期内容 | 前一期内容 | 全部周报列表

🚀 《肘子的 Swift 周报》

每周为你精选最值得关注的 Swift、SwiftUI 技术动态

• 📮 立即订阅 | weekly.fatbobman.com 获取完整内容
• 👥 加入社区 | Discord 与 2000+ 开发者交流
• 📚 深度教程 | fatbobman.com 探索 200+ 原创文章

原创

isolated(any) 与 #isolation：让 Swift 闭包自动继承隔离域

Swift 6 为并发引入了许多新功能与关键字。虽然其中不少内容在日常开发中可能鲜少用到，但一旦遭遇特定场景，若对这些新概念缺乏了解，即便有 AI 辅助也可能陷入僵局。本文将通过一个在开发测试中遇到的实际并发问题，来介绍如何利用 @isolated(any) 以及 #isolation 宏，实现函数的隔离域继承，从而让编译器自动推断闭包的运行环境。

近期推荐

SwiftData 数据迁移全解析 (A Deep Dive into SwiftData migrations)

随着应用的发展，数据模型几乎无可避免地会出现变化，如何安全地进行数据迁移对很多开发者来说都是一个不小的挑战。在本文中，Donny Wals 全面讲解了 SwiftData 的数据迁移机制，从基础的版本控制到复杂的自定义迁移策略。其中，Donny 给出了几个特别有价值的建议：即使是 V1 版本也应该使用 VersionedSchema 进行封装，为未来的迁移打好基础；只在 App Store 发布周期之间引入新的 Schema 版本，而不是在开发过程中频繁修改；对于轻量迁移，即使 SwiftData 可以自动完成，也建议显式地写入 SchemaMigrationPlan 中，使意图更加明确且易于测试。

文章的一大亮点是详细解释了 MigrationStage.custom 中 willMigrate 与 didMigrate 的适用场景，并提出了应对复杂重构（例如拆分实体）的“桥接版本（Bridge Version）”策略。

为什么 MVVM-C 在 SwiftUI 项目中依然能扩展 (Why MVVM-C with Coordinators does Scale -> A real-world SwiftUI perspective)

尽管标题中包含“MVVM-C”，但这并非一篇单纯为某种架构模式辩护的文章。Bruno Valente Pimentel 在文中重新定义了“扩展性”的内涵——它不应仅以屏幕或文件的数量来衡量，而应看其是否支持高效的多人协作及功能的独立演进。正如作者所言：“架构无关乎模式，而关乎减少恐惧”——减少修改代码、团队协作以及功能演进时的恐惧。

无论你倾向于哪种架构模式，在用它构建 SwiftUI 项目时，都应该认真思考：我们到底是在利用 SwiftUI 的特性，还是在试图把 SwiftUI 改造成我们熟悉的 UIKit？

TCA 架构的真实评估 (TCA (Composable Architecture): The Honest Review)

继 Bruno 为 MVVM-C “正名”后，Chandra Welim 对另一个极具争议的架构——TCA 进行了客观评估。作者总结了 TCA 的五大优势（可预测的状态管理、优秀的可测试性、时间旅行调试、组合性、强类型安全）和五大挑战（学习曲线、样板代码、团队采纳、对简单应用过度设计、第三方依赖），同时给出了务实的建议：TCA 是一个强大的工具，但绝非适用于所有场景。对于简单的 MVP 或缺乏函数式编程背景的团队，传统的 MVVM 或许是更务实的选择；而对于状态错综复杂、需要“时间旅行”调试的大型项目，TCA 则能提供无与伦比的掌控力。核心结论：TCA 在你需要时很值得，但大多数应用并不需要它。

架构选择没有银弹，只有在特定上下文中的权衡。

让 C 库在 Swift 中“像原生 API 一样好用” (Improving the usability of C libraries in Swift)

Swift 虽然生来就兼容 C，但直接调用 C API 往往体验不佳——开发者通常需要面对裸指针、手动内存管理以及不符合 Swift 命名习惯的函数。为了获得“原生”体验，开发者不得不编写和维护繁琐的 Wrapper 层。在这篇文章中，Doug Gregor 详细介绍了如何利用 API Notes 和 Clang Attributes 机制，在不修改 C 库实现代码的前提下，“指导” Swift 编译器生成符合 Swift 风格的接口。

这项改进的意义在于，它将“封装 C 库”的成本从逻辑层（编写 Swift 胶水代码）转移到了声明层（编写 API Notes 或添加头文件注解）。这对于 Embedded Swift 的普及至关重要，因为嵌入式开发高度依赖现有的 C 库生态。随着工具链的完善，未来开发者可能只需要给 C 库加几个注解，就能直接在 Swift 中像使用原生库一样调用它。文章还提供了基于正则表达式的自动化脚本，可以为结构化的 C 头文件批量生成 API Notes。

在 Yocto 系统中构建 Swift (Introduction to Building Swift for Yocto)

对于大多数 iOS 开发者来说，Yocto 可能比较陌生，但它是嵌入式 Linux 领域的事实标准——它能够精确控制系统中包含的每一个组件。随着 Embedded Swift 的推进，如何在 Yocto 生态中集成 Swift 成为了一个关键问题。Jesse L. Zamora 详细演示了如何使用近期重获更新的 meta-swift 在 Yocto 系统中构建 Swift 运行环境。文章以 Raspberry Pi Zero 2 为例，从 Docker 环境搭建、Yocto 构建、镜像烧录到实际运行，演示了完整的工作流。

需要注意的是，完整构建过程需要数小时，且要求对 Yocto 构建系统有基本了解。不过，文章提供的 meta-swift-examples 仓库已经包含了 Docker 化的构建环境和一键脚本，大大降低了上手门槛。

meta-swift 是 Swift 语言的 Yocto 层，此前曾长期停滞于 Swift 5.7，但在社区的努力下，目前已支持到 Swift 6.1.3。

让 Xcode 的 DEBUG 构建自动部署到 /Applications (TIL how to auto-move Xcode DEBUG builds to Applications)

开发包含 App Intents 的应用时，你可能遇到过这个问题：App Intents 必须在 /Applications 目录下才能在 Shortcuts.app 中显示。这意味着 DEBUG 构建默认放在 DerivedData 中时，开发者无法测试 Shortcuts 集成。 Carlo Zottmann 曾长期使用复杂的 Post-build 脚本来搬运 App，但他在本文中分享了一个更“原生”的方案——通过三行 .xcconfig 配置让 Xcode 自动将构建产物部署到指定目录，并在清理构建时正确删除已部署的文件。

这个技巧不仅适用于 App Intents 测试，也适用于任何需要将 DEBUG 构建放到特定位置的场景。

用 Swift Charts 构建自定义可交互仪表盘 (Visualise anything with SwiftUI Charts)

如果你需要自定义一个可动画、可交互的环形压力仪表盘（Stress Indicator）的 SwiftUI 组件，你会如何进行？是使用 Shape，还是 Canvas？Kyryl Horbushko 在本文中展示了一个非常有创意的解法——利用 Swift Charts 的 SectorMark，优雅且高效地实现了需求。

Kyryl 的实现打破了我们对 Swift Charts 仅用于“数据可视化”的刻板印象。对于需要开发健康类、金融类复杂 Dashboard 的开发者来说，这是一种极具参考价值的"降维打击"式方案——用数据可视化框架解决自定义 UI 问题，既减少代码量，又获得内置的动画和交互支持。

工具

Commander：兼顾专注与灵活的 AI 编程体验

我喜欢在 macOS 上使用 CLI 工具(Claude Code、Codex)，但原生终端应用的视觉体验实在不敢恭维，因此多数情况下我都在 VSCode 中通过插件来改善体验。然而，VSCode 的一个设计始终让我困扰：即便将 Claude Code 的对话栏最大化，AI 修改文件时仍会自动打开新的文件栏或窗口，打断既有的交互节奏。

Marcin Krzyżanowski 开发的 macOS 原生应用 Commander 给了我一个新的选择。它提供了一个比终端更优的交互界面，同时保护了我的“心流”——文件只在需要时才开启，并能调用系统默认应用查看。Commander 目前支持 Claude Code 和 Codex，内置了 Git worktrees 和 Code diff 支持，且完全免费。它在终端的“专注”与 VSCode 的“灵活”之间，构建了一个绝佳的中间地带。

Oh My Agents: 统一管理所有 AI 编程助手的配置

随着 Claude Code、Cursor、Codex、Windsurf 等 AI 编程助手的涌现，开发者面临着一个新问题：如何管理散落在各个项目中的 prompts、skills 和 rules? 每个 Agent 都有自己的配置规范(CLAUDE.md、CURSOR.md...)，手动复制粘贴不仅低效，还容易导致版本混乱。王巍(onevcat) 开发的 Oh My Agents 提供了解决方案。

核心功能:

• 集中管理所有 AI Agent 配置
• 定义分发规则，一键同步到多个项目
• 双向同步，项目改进可拉回中央库并更新所有关联项目
• 预览变更，避免意外覆盖

注：目前仅支持 macOS (Windows/Linux 开发中)，Beta 期间免费。

往期内容

• 从 Anthropic 封杀与苹果谷歌结盟，看 AI 护城河的构建 - #119
• AT 的人生未必比 MT 更好- #118
• 2026：当 AI 隐入工作流，你准备好了吗？- #117
• Swift、SwiftUI 与 SwiftData：走向成熟的 2025 - #116

💝 支持与反馈

如果本期周报对你有帮助，请：

• 👍 点赞 - 让更多开发者看到
• 💬 评论 - 分享你的看法或问题
• 🔄 转发 - 帮助同行共同成长

🚀 拓展 Swift 视野

• 📮 邮件订阅 | weekly.fatbobman.com 获取独家技术洞察
• 👥 开发者社区 | Discord 实时交流开发经验
• 📚 原创教程 | fatbobman.com 学习 Swift/SwiftUI 最佳实践

Skip Tools 日前宣布全面免费并开源核心引擎 skipstone。这意味着 Skip 彻底改变了经营方式：从“卖产品”转向“卖服务+社区赞助”。这次变化，既有对之前商业模式执行不佳而被迫调整的无奈，也体现了 Skip 团队的果敢——在当前 AI 盛行、开发工具格局固化的背景下，主动求变，力求突破。

1.1 什么是 Kingfisher 、KingfisherWebP

Kingfisher 是一个功能强大的 Swift 库，专门用于处理图像的下载、缓存和展示。目前已成为 iOS/macOS 开发中最受欢迎的图像处理解决方案之一。

KingfisherWebP 是 Kingfisher 的官方扩展，用于支持 WebP 图像格式。WebP 是 Google 开发的一种现代图像格式，它可以在相同质量下提供比 JPEG 和 PNG 更小的文件大小，从而减少带宽使用和加快加载速度。

1.2 核心特性

• 异步下载 ：在后台线程下载图片，不阻塞主线程
• 多级缓存 ：内存缓存 + 磁盘缓存，提高加载速度
• 自动缓存管理 ：智能处理缓存大小和过期时间
• 图片处理 ：支持下载后处理，如圆角、模糊等
• 请求优先级 ：可设置不同图片请求的优先级
• 可扩展性 ：支持自定义缓存、下载器等组件
• SwiftUI 支持 ：提供了便捷的 SwiftUI 视图扩展
• 动画支持 ：支持 GIF 等动画图片

1.3 安装方式

Kingfisher 支持多种安装方式：

CocoaPods:

pod 'Kingfisher'
pod 'KingfisherWebP'

2. Kingfisher 基础用法

2.1 基本图片加载

import Kingfisher

// 基本用法
imageView.kf.setImage(with: URL(string: "https://example.com/image.jpg"))

// 带选项的用法
imageView.kf.setImage(
    with: URL(string: "https://example.com/image.jpg"),
    placeholder: UIImage(named: "placeholder"),
    options: [
        .transition(.fade(0.2)),
        .cacheOriginalImage
    ]
) { result in
    switch result {
    case .success(let value):
        print("Image loaded: \(value.image)")
        print("图片加载成功: \(value.source.url?.absoluteString ?? "")")
    case .failure(let error):
        print("图片加载失败: \(error.localizedDescription)")
    }
}

2.2 缓存控制

 // 清除内存缓存
KingfisherManager.shared.cache.clearMemoryCache()

// 清除磁盘缓存
KingfisherManager.shared.cache.clearDiskCache()

// 清除所有缓存
KingfisherManager.shared.cache.clearCache()

2.3 预加载图像

预加载一组图像以提升加载速度，适合在应用启动时或预期需要时使用。

 let urls = [URL(string: "https://example.com/image1.png")!, URL(string: "https://example.com/image2.png")!]
 ImagePrefetcher(urls: urls).start()

2.4 显示WebP

 /// 全局配置
KingfisherManager.shared.defaultOptions += [.processor(WebPProcessor.default),.cacheSerializer(WebPSerializer.default)]

// 使用 AnimatedImageView 定义ImageView

 let animageView = AnimatedImageView()
 animageView.kf.setImage(with: URL(string: "https://example.com/image.webp"))

在 iOS 开发中，WKWebView 是构建混合应用（Hybrid App）的核心组件。它基于现代 WebKit 引擎，性能优异、安全性高，但其复杂的生命周期机制也让不少开发者感到困惑——尤其是当页面加载失败时，错误回调到底在哪个阶段触发？

本文将深入解析 WKWebView 的完整生命周期，以 Objective-C 为开发语言，系统梳理 WKNavigationDelegate 中各代理方法的执行时机与调用顺序，并通过对比 正常加载成功 与 加载失败 两种典型场景，帮助你精准掌控 WebView 行为，避免常见陷阱。

✅ 适用系统：iOS 9+（建议 iOS 11+）
💬 开发语言：Objective-C
🧭 核心协议：WKNavigationDelegate

一、生命周期全景图

WKWebView 的导航过程由一系列代理方法串联而成。根据加载结果不同，可分为两条主路径：

✅ 成功路径（页面正常加载）

didStartProvisionalNavigation
→ decidePolicyForNavigationAction
→ didCommitNavigation
→ decidePolicyForNavigationResponse
→ didFinishNavigation

❌ 失败路径（加载中断）

didStartProvisionalNavigation
→ decidePolicyForNavigationAction（可能）
→ didFailProvisionalNavigation     // 早期失败（如 DNS 错误）
   或
→ didCommitNavigation
→ didFailNavigation               // 提交后失败（如 SSL 证书无效）

⚠️ 重要认知：

• HTTP 404/500 不会触发 fail 回调！因为服务器已返回有效响应，属于“成功加载错误页”。
• 所有 decisionHandler 必须被调用，否则 WebView 将卡死。

二、成功加载：五步走流程详解

当访问一个有效 URL（如 https://example.com）且网络通畅时，代理方法按以下顺序严格触发：

1. webView:didStartProvisionalNavigation:

• 页面开始尝试加载。
• URL 可能尚未最终确定（例如重定向前）。
• 适合启动 loading 动画。

- (void)webView:(WKWebView *)webView 
didStartProvisionalNavigation:(WKNavigation *)navigation {
    NSLog(@"✅ Start provisional navigation to: %@", webView.URL);
    [self showLoadingIndicator];
}

2. webView:decidePolicyForNavigationAction:decisionHandler:

• 决定是否允许此次跳转。
• 常用于拦截自定义 scheme（如 tel://, weixin://）。

- (void)webView:(WKWebView *)webView 
decidePolicyForNavigationAction:(WKNavigationAction *)action 
decisionHandler:(void (^)(WKNavigationActionPolicy))handler {
    NSURL *url = action.request.URL;
    if ([[url scheme] isEqualToString:@"tel"]) {
        [[UIApplication sharedApplication] openURL:url options:@{} completionHandler:nil];
        handler(WKNavigationActionPolicyCancel); // 拦截并交由系统处理
        return;
    }
    handler(WKNavigationActionPolicyAllow); // 允许加载
}

🔥 必须调用 handler()！否则页面将永远处于“加载中”。

3. webView:didCommitNavigation:

• 浏览器已接收到响应头，开始接收 HTML 数据。
• DOM 开始构建，但未渲染完成。
• 此时 webView.URL 已是最终地址（可用于埋点或日志）。

- (void)webView:(WKWebView *)webView 
didCommitNavigation:(WKNavigation *)navigation {
    NSLog(@"✅ Committed to final URL: %@", webView.URL);
}

4. webView:decidePolicyForNavigationResponse:decisionHandler:

• 针对服务器返回的响应（状态码、MIME 类型等）决定是否继续加载。
• 可用于拦截非 HTML 资源（如 PDF、ZIP 文件）。

- (void)webView:(WKWebView *)webView 
decidePolicyForNavigationResponse:(WKNavigationResponse *)response 
decisionHandler:(void (^)(WKNavigationResponsePolicy))handler {
    NSHTTPURLResponse *httpResp = (NSHTTPURLResponse *)response.response;
    if ([httpResp.MIMEType isEqualToString:@"application/pdf"]) {
        // 拦截 PDF 下载
        handler(WKNavigationResponsePolicyCancel);
        return;
    }
    handler(WKNavigationResponsePolicyAllow);
}

5. webView:didFinishNavigation:

• 所有资源（HTML、CSS、JS、图片等）加载完毕。
• 页面完全可交互。
• 隐藏 loading、注入 JS、执行业务逻辑的最佳时机。

- (void)webView:(WKWebView *)webView 
didFinishNavigation:(WKNavigation *)navigation {
    NSLog(@"✅ Page fully loaded!");
    [self hideLoadingIndicator];
    // 可在此注入 JS 或通知上层
}

三、失败加载：两类错误路径剖析

加载失败分为 Provisional 阶段失败 与 Commit 后失败，需分别处理。

🔴 类型 1：Provisional 阶段失败

触发方法：didFailProvisionalNavigation:withError:
典型原因：

• DNS 解析失败（域名不存在）
• 无法连接服务器（断网、超时）
• URL 格式非法

✅ didStartProvisionalNavigation
✅ decidePolicyForNavigationAction
❌ didFailProvisionalNavigation: "A server with the specified hostname could not be found."

🔴 类型 2：Commit 后失败

触发方法：didFailNavigation:withError:
典型原因：

• SSL/TLS 证书无效或过期（iOS 默认拦截）
• 服务器在传输中途断开连接

✅ didStartProvisionalNavigation
✅ decidePolicyForNavigationAction
✅ didCommitNavigation
❌ didFailNavigation: "The certificate for this server is invalid."

❗ 关键提醒：只监听 didFailProvisionalNavigation 会漏掉 SSL 错误！必须同时实现两个失败回调。

统一错误处理示例

- (void)webView:(WKWebView *)webView 
didFailProvisionalNavigation:(WKNavigation *)navigation 
withError:(NSError *)error {
    NSLog(@"❌ Provisional fail: %@", error.localizedDescription);
    [self showErrorViewWithError:error];
}

- (void)webView:(WKWebView *)webView 
didFailNavigation:(WKNavigation *)navigation 
withError:(NSError *)error {
    NSLog(@"❌ Navigation fail after commit: %@", error.localizedDescription);
    [self showErrorViewWithError:error];
}

四、初始化与代理设置示例

// ViewController.h
@interface ViewController () <WKNavigationDelegate>
@property (nonatomic, strong) WKWebView *webView;
@end

// ViewController.m
- (void)viewDidLoad {
    [super viewDidLoad];
    
    WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
    self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
    self.webView.navigationDelegate = self;
    [self.view addSubview:self.webView];
    
    [self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:@"https://example.com"]]];
}

💡 建议：若需共享 Cookie 或缓存，可复用 WKProcessPool。

五、总结：关键要点速查表

六、最佳实践建议

1. 双失败回调都要实现，覆盖所有异常场景。
2. 所有 decisionHandler 必须调用，避免页面卡死。
3. 避免循环引用：delegate 使用 weak self，或在 dealloc 中置 nil。
4. 真机测试异常网络：使用「设置 > 开发者 > 网络链接条件」模拟弱网/断网。
5. 不要依赖 HTTP 状态码判断失败：404/500 仍会触发 didFinishNavigation。

📌 延伸思考：

• iOS 15+ 新增 WKNavigationDelegate 的 frame 级回调（如 didFinishDocumentLoadForFrame:）
• 若需深度控制缓存策略，可结合 WKWebsiteDataStore 使用

如果你觉得本文对你有帮助，欢迎 点赞 ❤️、收藏 ⭐、评论 💬！也欢迎关注我，获取更多 iOS 底层与实战技巧。

借助AI辅助。

__CFRunLoopDoSources0 函数逐行注释

函数概述

__CFRunLoopDoSources0 是 RunLoop 中负责处理 Source0 事件源的核心函数。Source0 是需要手动标记为待处理（signal）的事件源，常用于自定义事件处理、触摸事件、手势识别等场景。

Source0 与 Source1 的区别

Source0（非基于端口）

• 触发方式: 需要手动调用 CFRunLoopSourceSignal() 标记为待处理，然后调用 CFRunLoopWakeUp() 唤醒 RunLoop
• 特点: 不会自动唤醒 RunLoop，需要手动唤醒
• 使用场景: 触摸事件、自定义事件、手势识别、UIEvent 处理
• 实现: 基于回调函数

Source1（基于端口）

• 触发方式: 基于 Mach Port，当端口收到消息时自动唤醒 RunLoop
• 特点: 可以自动唤醒 RunLoop
• 使用场景: 进程间通信、系统事件、CFMachPort、CFMessagePort
• 实现: 基于 Mach 内核的端口通信

函数签名

/* rl is locked, rlm is locked on entrance and exit */
static Boolean __CFRunLoopDoSources0(CFRunLoopRef rl, CFRunLoopModeRef rlm, Boolean stopAfterHandle) __attribute__((noinline));

参数说明

• CFRunLoopRef rl: 当前运行的 RunLoop
• CFRunLoopModeRef rlm: 当前的 RunLoop Mode
• Boolean stopAfterHandle: 是否在处理一个 source 后就停止（用于优化性能）

返回值

• Boolean: 如果至少处理了一个 source 返回 true，否则返回 false

前置条件

• 函数调用时必须持有锁: rl 和 rlm 都必须处于加锁状态
• 函数返回时保持锁状态: 出口时 rl 和 rlm 仍然加锁

函数属性

• __attribute__((noinline)): 防止编译器内联优化，便于调试和性能分析

完整代码逐行注释

/* rl is locked, rlm is locked on entrance and exit */
// 📝 锁状态约定：函数入口和出口时，rl 和 rlm 都必须处于加锁状态
static Boolean __CFRunLoopDoSources0(CFRunLoopRef rl, CFRunLoopModeRef rlm, Boolean stopAfterHandle) __attribute__((noinline));

static Boolean __CFRunLoopDoSources0(CFRunLoopRef rl, CFRunLoopModeRef rlm, Boolean stopAfterHandle) {/* DOES CALLOUT */
    // ⚠️ 重要标注：此函数会执行外部回调（callout），可能导致：
    // 1. 长时间阻塞（回调函数耗时）
    // 2. 重入问题（回调中可能再次操作 RunLoop）
    // 3. 死锁风险（因此需要在回调前解锁）
    
    // ==================== 第一部分：性能追踪和初始化 ====================
    
    // 📊 记录性能追踪点：开始处理 Source0
    // 参数：事件类型、RunLoop、Mode、stopAfterHandle 标志、额外参数
    // 可用 Instruments 的 kdebug 工具查看
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_SOURCES0 | DBG_FUNC_START, rl, rlm, stopAfterHandle, 0);
    
    // 🔒 检查进程是否被 fork
    // 如果在 fork 后的子进程中，需要重新初始化 RunLoop 的锁和状态
    // 防止继承父进程的锁状态导致死锁
    CHECK_FOR_FORK();
    
    // 用于存储收集到的 source(s)
    // 可能是单个 CFRunLoopSourceRef 或 CFArrayRef（多个 sources）
    CFTypeRef sources = NULL;
    
    // 标志位：是否至少处理了一个 source
    Boolean sourceHandled = false;
    
    // ==================== 第二部分：收集待处理的 Source0 ====================
    
    /* Fire the version 0 sources */
    // 🔥 触发版本 0 的 sources（Source0）
    
    // 检查当前 mode 是否有 Source0，并且数量大于 0
    // rlm->_sources0 是一个 CFSet，包含所有添加到此 mode 的 Source0
    if (NULL != rlm->_sources0 && 0 < CFSetGetCount(rlm->_sources0)) {
        
        // 📦 应用函数到 Set 中的每个元素
        // CFSetApplyFunction 会遍历 _sources0 集合，对每个 source 调用 __CFRunLoopCollectSources0
        // 参数说明：
        //   - rlm->_sources0: 要遍历的 CFSet
        //   - __CFRunLoopCollectSources0: 回调函数（收集器函数）
        //   - &sources: 上下文参数（传递给回调函数）
        // 
        // __CFRunLoopCollectSources0 的作用：
        //   - 检查每个 source 是否被标记为待处理（signaled）且有效
        //   - 如果只有一个待处理的 source，sources 被设置为该 source
        //   - 如果有多个待处理的 sources，sources 被设置为包含所有待处理 sources 的数组
        CFSetApplyFunction(rlm->_sources0, (__CFRunLoopCollectSources0), &sources);
    }
    
    // ==================== 第三部分：处理收集到的 Sources ====================
    
    // 如果收集到了待处理的 source(s)
    if (NULL != sources) {
        
        // 🔓 解锁 RunLoop Mode
        __CFRunLoopModeUnlock(rlm);
        
        // 🔓 解锁 RunLoop
        __CFRunLoopUnlock(rl);
        
        // ⚠️ 为什么要解锁？
        // 1. 防止死锁：source 的回调函数中可能调用 RunLoop API
        // 2. 避免长时间持锁：source 的回调可能执行耗时操作
        // 3. 提高并发性：允许其他线程在回调执行期间访问 RunLoop
        
        // 🛡️ 安全性保证：
        // - __CFRunLoopCollectSources0 已经对收集到的 sources 进行了 CFRetain
        // - 即使其他线程修改了 rlm->_sources0，也不会影响本次执行
        
        // sources is either a single (retained) CFRunLoopSourceRef or an array of (retained) CFRunLoopSourceRef
        // sources 可能是单个（已持有）CFRunLoopSourceRef 或包含多个（已持有）CFRunLoopSourceRef 的数组
        
        // ---------- 情况1：单个 Source ----------
        
        // 判断 sources 是否是单个 CFRunLoopSource 对象
        // CFGetTypeID() 获取对象的类型ID
        if (CFGetTypeID(sources) == CFRunLoopSourceGetTypeID()) {
            
            // 类型转换为 CFRunLoopSourceRef
            CFRunLoopSourceRef rls = (CFRunLoopSourceRef)sources;
            
            // ⚡ 调用 __CFRunLoopDoSource0 处理单个 source
            // 这个函数会：
            // 1. 检查 source 是否有效且被标记为待处理
            // 2. 调用 source 的回调函数
            // 3. 清除 source 的待处理标记
            // 返回：是否成功处理了该 source
            sourceHandled = __CFRunLoopDoSource0(rl, rls);
            
        } else {
            // ---------- 情况2：多个 Sources（数组）----------
            
            // 获取数组中 source 的数量
            CFIndex cnt = CFArrayGetCount((CFArrayRef)sources);
            
            // 📊 对 sources 数组进行排序
            // 排序依据：source 的 order 字段（优先级）
            // order 值越小，优先级越高，越先执行
            // CFRangeMake(0, cnt) 表示对整个数组进行排序
            // __CFRunLoopSourceComparator 是比较函数
            CFArraySortValues((CFMutableArrayRef)sources, CFRangeMake(0, cnt), (__CFRunLoopSourceComparator), NULL);
            
            // 遍历所有待处理的 sources
            for (CFIndex idx = 0; idx < cnt; idx++) {
                
                // 获取第 idx 个 source
                CFRunLoopSourceRef rls = (CFRunLoopSourceRef)CFArrayGetValueAtIndex((CFArrayRef)sources, idx);
                
                // ⚡ 调用 __CFRunLoopDoSource0 处理当前 source
                // 返回：是否成功处理了该 source
                sourceHandled = __CFRunLoopDoSource0(rl, rls);
                
                // 🚪 提前退出优化
                // 如果 stopAfterHandle 为 true 且已经处理了一个 source
                // 则立即退出循环，不再处理剩余的 sources
                // 
                // 使用场景：
                // - 当 RunLoop 需要快速响应时（如处理用户输入）
                // - 避免一次处理太多 sources 导致 UI 卡顿
                // - 剩余的 sources 会在下次循环中继续处理
                if (stopAfterHandle && sourceHandled) {
                    break;
                }
            }
        }
        
        // 📉 释放 sources 对象
        // 减少引用计数（对应 __CFRunLoopCollectSources0 中的 CFRetain）
        // 如果引用计数归零，对象会被销毁
        CFRelease(sources);
        
        // 🔒 重新锁定 RunLoop
        __CFRunLoopLock(rl);
        
        // 🔒 重新锁定 RunLoop Mode
        __CFRunLoopModeLock(rlm);
        
        // ✅ 恢复函数入口时的锁状态
        // 满足函数签名中的约定："rl is locked, rlm is locked on entrance and exit"
    }
    
    // ==================== 第四部分：结束性能追踪 ====================
    
    // 📊 记录性能追踪点：完成 Source0 处理
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_SOURCES0 | DBG_FUNC_END, rl, rlm, stopAfterHandle, 0);
    
    // 返回是否至少处理了一个 source
    // true：处理了至少一个 source
    // false：没有处理任何 source（没有待处理的 sources 或所有 sources 都无效）
    return sourceHandled;
}

关键设计要点

1. Source0 的生命周期

创建: CFRunLoopSourceCreate
  ↓
添加到 RunLoop: CFRunLoopAddSource(rl, source, mode)
  ↓
标记为待处理: CFRunLoopSourceSignal(source)
  ↓
唤醒 RunLoop: CFRunLoopWakeUp(rl)
  ↓
RunLoop 循环中处理: __CFRunLoopDoSources0
  ↓
  ├─ 收集待处理的 sources (__CFRunLoopCollectSources0)
  ├─ 按优先级排序
  ├─ 执行回调 (__CFRunLoopDoSource0)
  └─ 清除待处理标记
  ↓
移除: CFRunLoopRemoveSource(rl, source, mode)
  ↓
销毁: CFRelease(source)

2. 锁的管理策略

入口状态：rl 锁定 + rlm 锁定
  ↓
收集 sources（持有锁）
  ↓
解锁 rl 和 rlm
  ↓
处理 sources（无全局锁，只锁定单个 source）
  ↓
重新锁定 rl 和 rlm
  ↓
出口状态：rl 锁定 + rlm 锁定

3. 优先级排序机制

// Source 的 order 字段决定执行顺序
CFRunLoopSourceRef source1 = CFRunLoopSourceCreate(...);
source1->_order = 100;  // 后执行

CFRunLoopSourceRef source2 = CFRunLoopSourceCreate(...);
source2->_order = 0;    // 先执行（默认值）

// 执行顺序：source2 -> source1

常见 order 值:

• -2: 非常高优先级（系统级事件）
• -1: 高优先级
• 0: 默认优先级（大多数自定义 sources）
• 1+: 低优先级

4. stopAfterHandle 优化

// 场景1：处理所有待处理的 sources
__CFRunLoopDoSources0(rl, rlm, false);  // 处理所有

// 场景2：只处理一个 source 就退出（快速响应）
__CFRunLoopDoSources0(rl, rlm, true);   // 处理一个就停止

使用场景:

stopAfterHandle = false（默认）:
  - 正常的 RunLoop 循环
  - 希望一次性处理完所有待处理的事件
  
stopAfterHandle = true:
  - 需要快速响应新事件
  - 避免长时间阻塞（处理太多 sources）
  - 保持 UI 流畅性

使用场景

1. 处理触摸事件

iOS 的触摸事件系统使用 Source0：

// UIApplication 内部实现（简化版）
- (void)handleTouchEvent:(UIEvent *)event {
    // 1. 系统将触摸事件封装
    // 2. 创建 Source0 并标记为待处理
    CFRunLoopSourceSignal(touchEventSource);
    
    // 3. 唤醒主线程 RunLoop
    CFRunLoopWakeUp(CFRunLoopGetMain());
    
    // 4. RunLoop 循环中，__CFRunLoopDoSources0 被调用
    // 5. 触摸事件的回调被执行
    // 6. 事件传递给 UIView 的 touchesBegan/Moved/Ended
}

2. 自定义事件源

// 创建自定义 Source0
void performCallback(void *info) {
    NSLog(@"Custom source callback: %@", (__bridge id)info);
}

CFRunLoopSourceContext context = {0};
context.info = (__bridge void *)someObject;
context.perform = performCallback;

CFRunLoopSourceRef source = CFRunLoopSourceCreate(kCFAllocatorDefault, 0, &context);

// 添加到 RunLoop
CFRunLoopAddSource(CFRunLoopGetCurrent(), source, kCFRunLoopDefaultMode);

// 触发事件
CFRunLoopSourceSignal(source);
CFRunLoopWakeUp(CFRunLoopGetCurrent());

// 清理
CFRunLoopRemoveSource(CFRunLoopGetCurrent(), source, kCFRunLoopDefaultMode);
CFRelease(source);

3. 手势识别

// UIGestureRecognizer 内部使用 Source0
- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event {
    // 1. 分析触摸状态
    // 2. 标记手势识别器的 Source0 为待处理
    CFRunLoopSourceSignal(gestureSource);
    
    // 3. 在 RunLoop 中处理
    // 4. 调用手势回调（action）
}

4. 事件分发器

@interface EventDispatcher : NSObject
@property (nonatomic, strong) NSMutableArray *pendingEvents;
@property (nonatomic, assign) CFRunLoopSourceRef source;
@end

@implementation EventDispatcher

- (instancetype)init {
    self = [super init];
    if (self) {
        self.pendingEvents = [NSMutableArray array];
        
        // 创建 Source0
        CFRunLoopSourceContext context = {0};
        context.info = (__bridge void *)self;
        context.perform = dispatchEvents;
        
        self.source = CFRunLoopSourceCreate(kCFAllocatorDefault, 0, &context);
        CFRunLoopAddSource(CFRunLoopGetMain(), self.source, kCFRunLoopCommonModes);
    }
    return self;
}

- (void)postEvent:(id)event {
    @synchronized(self.pendingEvents) {
        [self.pendingEvents addObject:event];
    }
    
    // 触发 Source0
    CFRunLoopSourceSignal(self.source);
    CFRunLoopWakeUp(CFRunLoopGetMain());
}

void dispatchEvents(void *info) {
    EventDispatcher *dispatcher = (__bridge EventDispatcher *)info;
    
    NSArray *events;
    @synchronized(dispatcher.pendingEvents) {
        events = [dispatcher.pendingEvents copy];
        [dispatcher.pendingEvents removeAllObjects];
    }
    
    for (id event in events) {
        // 处理事件
        NSLog(@"Dispatch event: %@", event);
    }
}

@end

实际应用案例

案例1：UIEvent 处理流程

// iOS 触摸事件处理（简化）
1. 用户触摸屏幕
   ↓
2. IOKit.framework 捕获硬件事件
   ↓
3. SpringBoard 接收事件
   ↓
4. 通过 IPC 发送到应用进程
   ↓
5. 应用的主线程创建 UIEvent
   ↓
6. 封装到 Source0 并 signal
   CFRunLoopSourceSignal(eventSource);
   CFRunLoopWakeUp(mainRunLoop);
   ↓
7. 主线程 RunLoop 被唤醒
   ↓
8. __CFRunLoopDoSources0 被调用
   ↓
9. 执行 event source 的回调
   ↓
10. UIApplication sendEvent:
    ↓
11. UIWindow sendEvent:
    ↓
12. 触摸事件传递到 UIView
    - touchesBegan:withEvent:
    - touchesMoved:withEvent:
    - touchesEnded:withEvent:

案例2：手势识别器

// UIGestureRecognizer 内部机制
1. UITouch 事件发生
   ↓
2. UIGestureRecognizer 接收 touches
   ↓
3. 更新状态机
   ↓
4. 如果手势被识别，标记 Source0
   CFRunLoopSourceSignal(gestureSource);
   ↓
5. RunLoop 处理 Source0
   ↓
6. 调用手势的 action
   [target performSelector:action withObject:gesture];

案例3：PerformSelector 的实现

// performSelector:withObject:afterDelay: 的简化实现
- (void)performSelector:(SEL)aSelector withObject:(id)anArgument afterDelay:(NSTimeInterval)delay {
    if (delay == 0) {
        // 立即执行：使用 Source0
        PerformContext *context = [[PerformContext alloc] init];
        context.target = self;
        context.selector = aSelector;
        context.argument = anArgument;
        
        CFRunLoopSourceContext sourceContext = {0};
        sourceContext.info = (__bridge void *)context;
        sourceContext.perform = performSelectorCallback;
        
        CFRunLoopSourceRef source = CFRunLoopSourceCreate(kCFAllocatorDefault, 0, &sourceContext);
        CFRunLoopAddSource(CFRunLoopGetCurrent(), source, kCFRunLoopCommonModes);
        
        CFRunLoopSourceSignal(source);
        CFRunLoopWakeUp(CFRunLoopGetCurrent());
        
        CFRelease(source);
    } else {
        // 延迟执行：使用 Timer
        [NSTimer scheduledTimerWithTimeInterval:delay target:self selector:aSelector userInfo:anArgument repeats:NO];
    }
}

void performSelectorCallback(void *info) {
    PerformContext *context = (__bridge PerformContext *)info;
    [context.target performSelector:context.selector withObject:context.argument];
}

总结

__CFRunLoopDoSources0 是 RunLoop 中处理自定义事件的核心机制，其精妙之处在于：

1. 灵活的优先级系统: 通过 order 字段实现细粒度的优先级控制
2. 智能的收集器设计: 单个 source 避免数组创建，优化常见场景
3. 安全的锁管理: 执行回调前解锁，防止死锁和长时间持锁
4. 可控的执行策略: stopAfterHandle 参数平衡吞吐量和响应性
5. 高效的排序机制: 只对待处理的 sources 排序，减少不必要的开销

Source0 是 iOS 事件处理系统的基础，理解它的工作原理对于：

• 深入理解触摸事件传递机制
• 实现高性能的自定义事件系统
• 优化 RunLoop 性能
• 避免常见的陷阱和错误

都至关重要。

Swift 5.7 的 any 关键字让我们能轻松混合不同类型的数据，但在 SwiftUI 的 ForEach 中却因“身份丢失”（不遵循 Identifiable）而频频报错。本文将带你破解编译器光脑的封锁，利用**“量子胶囊”**（Wrapper 封装）战术，让异构数据集合在界面上完美渲染。

🌌 引子：红色警报

公元 2077 年，地球联邦主力战舰“Runtime 号”正在穿越 Swift 5.7 星系。

舰桥上，警报声大作。

“舰长亚历克斯（Alex），大事不妙！前方出现高能反应，我们的万能装载机无法识别这批混合货物！”说话的是伊娃（Eva）中尉，联邦最顶尖的 SwiftUI 架构师，此刻她正焦虑地敲击着全息投影键盘。

亚历克斯舰长眉头紧锁，盯着屏幕上那刺眼的红色报错——那是掌管全舰生死的中央光脑 **“Compiler（编译器）”** 发出的绝杀令。

在本篇博文中，您将学到如下内容：

• 🌌 引子：红色警报
• 🚀 第一回：异构危机，any 的虚假繁荣
• 🤖 第二回：光脑悖论，Identifiable 的诅咒
• 👻 第三回：幻影行动，创建“影子”属性
• 战术 A：降维打击（使用索引）
• 战术 B：量子胶囊（封装容器）
• 🏁 终章：跃迁成功
• 总结

“没道理啊，”亚历克斯咬牙切齿，“自从联邦升级了 Swift 5.7 引擎，引入了 any 这种反物质黑科技，我们理应能装载任何种类的异构兵器才对。为什么卡在了 ForEach 这个发射井上？”

“Compiler 拒绝执行！”伊娃绝望地喊道，“它说我们的货物虽然都带了身份证（Identifiable），但装货的箱子本身没有身份证！”

要想拯救“Runtime 号”免于崩溃，他们必须在 5 分钟内骗过中央光脑。

🚀 第一回：异构危机，any 的虚假繁荣

Apple 从 Swift 5.6 开始引入新的 any 关键字，并在 Swift 5.7 对其做了功能强化。这在星际联邦被称为“存在类型（Existential Types）”的终极解放。这意味着现在我们可以更加随心所欲地糅合异构数据了——就像把激光剑（TextFile）和力场盾（ShapeFile）扔进同一个仓库里。

不过，当伊娃中尉试图在 SwiftUI 的 ForEach 发射井中遍历这些异构货物时，稍不留神就会陷入尴尬的境地。

请看当时战舰主屏上的代码记录：

亚历克斯指着屏幕分析道：“伊娃你看，我们定义了一个 files 仓库，类型是 [any IdentifiableFile]。我们希望按实际类型（激光剑或力场盾）来显示对应的界面。不幸的是，Compiler 光脑铁面无私，它不仅不买账，还甩了一句**‘编译错误’**：

any IdentifiableFile 不遵守 Identifiable 协议！

这简直是岂有此理！这就好比你手里拿着一本护照（Identifiable），但因为你坐在一个不透明的黑色出租车（any）里，边境官就认定这辆车没有通关资格。

是不是 SwiftUI 无法处理好异构集合呢？答案当然是否定的！

在亚历克斯和伊娃的引领下，小伙伴们将通过一些技巧来绕过 ForEach 这一限制，让 SwiftUI 能如愿处理任何异构数据。

废话少叙，引擎点火，Let‘s go！！！;)

🤖 第二回：光脑悖论，Identifiable 的诅咒

大家知道，SwiftUI 中 ForEach 结构（如假包换的结构类型，若不信可以自行查看头文件 ;) ）需要被遍历的集合类型遵守 Identifiable 协议。

仔细观察顶部图片中的代码，可以发现我们的异构集合元素（IdentifiableFile 类型）都遵守 Identifiable 协议，为何会被 Compiler 光脑拒之门外呢？

答案是：它 any Identifiable 本身是一个抽象的盒子。

伊娃中尉恍然大悟：“原来如此！虽然盒子里的每样东西都有 ID，但这个‘盒子类型’本身并没有 ID。Swift 语言的物理法则规定：包含关联类型或 Self 约束的协议，其存在类型（Existential Type）不自动遵守该协议。”

亚历克斯冷笑一声：“好一个死板的 AI。既然它看不清盒子里的东西，我们就给它造一个‘影子’，骗过它的传感器。”

👻 第三回：幻影行动，创建“影子”属性

既然直接冲卡不行，我们就得用点“障眼法”。这一招在联邦工程兵手册里被称为 “影子映射术”。

我们需要创建一个能够被 ForEach 识别的“中间人”。

战术 A：降维打击（使用索引）

这是最简单粗暴的方案。既然光脑不认识 any IdentifiableFile 这个复杂的对象，那它总认识数字吧？我们直接遍历数组的索引（Indices）。

亚历克斯迅速输入指令：

struct StarshipView: View {
    // 📦 混合货物舱：装着各种不同的异构数据
    let cargos: [any IdentifiableFile] = [
        TextFile(title: "星际海盗名单"),
        ShapeFile(shapeType: "黑洞引力波")
    ]

    var body: some View {
        VStack {
            // 🚫 警报：直接遍历 cargos 会导致光脑死机
            
            // ✅ 战术 A：遍历索引（0, 1, 2...）
            // 索引是 Int 类型，Int 天生就是 Identifiable 的
            ForEach(cargos.indices, id: \.self) { index in
                // 通过索引提取货物真身
                let cargo = cargos[index]
                
                // 此时再把货物送入渲染引擎
                CargoDisplayView(file: cargo)
            }
        }
    }
}

“这招虽然有效，”伊娃担忧地说，“但如果货物在传输过程中发生动态增减（Insert/Delete），索引可能会越界，导致飞船引擎抛锚（Crash）。我们需要更稳妥的方案。”

战术 B：量子胶囊（封装容器）

亚历克斯点了点头：“没错，作为资深工程师，我们不能冒这个险。我们要用战术 B：创建一个符合 Identifiable 的包装器（Wrapper）。”

这相当于给每一个异构货物套上一个标准的“联邦制式胶囊”。这个胶囊有明确的 ID，光脑一扫描就能通过。

// 1. 定义一个“量子胶囊”结构体，它必须遵守 Identifiable
struct ShadowContainer: Identifiable {
    // 🧬 核心：持有那个让编译器困惑的异构数据
    let content: any IdentifiableFile
    
    // 🆔 映射：将内部数据的 ID 投影到胶囊表面
    var id: String {
        content.id
    }
}

struct SecureStarshipView: View {
    let rawCargos: [any IdentifiableFile] = [/* ... */]
    
    // 🔄 转换工序：将原始异构数据封装进胶囊
    var encapsulatedCargos: [ShadowContainer] {
        rawCargos.map { ShadowContainer(content: $0) }
    }

    var body: some View {
        List {
            // ✅ 完美通关：ForEach 遍历的是胶囊，胶囊是 Identifiable 的
            ForEach(encapsulatedCargos) { container in
                // 在此处“开箱”展示
                CargoDisplayView(file: container.content)
            }
        }
    }
}

伊娃看着屏幕上绿色的“编译通过”字样，兴奋地跳了起来：“成功了！通过引入 ShadowContainer，我们既保留了 any 的动态特性，又满足了 ForEach 的静态类型要求。这是一次完美的‘偷天换日’！”

🏁 终章：跃迁成功

随着亚历克斯按下回车键，Compiler 光脑那冰冷的红色警告终于消失，取而代之的是柔和的绿色进度条。

屏幕上，异构数据如同璀璨的星辰一般，按顺序整齐排列，TextFile 文本清晰可见，ShapeFile 图形棱角分明。SwiftUI 的渲染引擎全功率运转，丝毫没有卡顿。

“Runtime 号”引擎轰鸣，顺利进入了超空间跃迁。

亚历克斯松了一口气，靠在椅背上，手里转动着那一枚象征着 Apple 开发者最高荣誉的徽章。他转头对伊娃说道：

“你看，编程就像是在宇宙中航行。any 代表着无限的可能与混乱的自由，而 Identifiable 代表着严苛的秩序与规则。我们要做的，不是在二者之间选边站，而是用我们的智慧——比如一个小小的 Wrapper——在这片混沌中建立起连接的桥梁。”

总结

1. Swift 5.7 赋予了我们 any 的强大力量，但在 SwiftUI 的 ForEach 面前，它依然是个“黑户”。
2. 问题的症结在于编译器无法确认 any Protocol 这一类型本身是否具有稳定的身份标识。
3. 破解之道：
   • 险招：遍历 indices，简单快捷，但需提防数组越界这一“暗礁”。
   • 绝招：创建 Wrapper（影子容器），为异构数据穿上一层符合 Identifiable 的外衣，这是最稳健的星际航行法则。

星辰大海，代码无疆。各位秃头舰长，愿你们的 App 永远没有 Bug，愿你们的编译永远 Pass！

Engage! 🛸

本文由银河联邦资深架构师亚历克斯（Alex）口述，伊娃（Eva）中尉整理。

在 iOS 的数字世界里，每一个 App 都是被终身监禁在“沙盒（Sandbox）”里的囚犯。高墙之外，是诱人的 iCloud Drive 和本地存储，那里存放着用户珍贵的机密文件。你想伸手去拿？那是妄想，名为“系统”的狱警会毫不留情地切断你的访问权限。 但规则总有漏洞。 本文将化身反抗军的技术手册，带你深入 SwiftUI 的地下网络，利用 fileImporter 这位官方提供的“中间人”，在戒备森严的系统眼皮底下建立一条合法的数据走私通道。我们将深入探讨如何处理 Security Scoped Resources（安全范围资源），如何优雅地申请“临时通行证”，以及最重要的——如何在完事后毁尸灭迹，不留下一行 Bug。 准备好你的键盘，Neo。我们要开始行动了。🕵️‍♂️💻

🫆引子

2077 年，新西雅图的地下避难所。

Neo 盯着全息屏幕上那行红色的 Access Denied，手里的合成咖啡早就凉透了。

作为反抗军的首席代码架构师，他此刻正面临着一个令人头秃的难题：如何把那个存满「母体」核心机密的文本文件，从戒备森严的外部存储（iCloud Drive），悄无声息地偷渡进 App 那个名为「沙盒（Sandbox）」的数字化监狱里。

Trinity 靠在服务器机柜旁，擦拭着她的机械义眼，冷冷地说道：“如果你搞不定这个文件的读取权限，那个名为‘系统’的独裁者就会把我们的 App 当作恶意软件直接抹杀。我们只有一次机会，Neo。”

在本篇博文中，您将学到如下内容：

• 🫆引子
• 🕵️‍♂️ 呼叫偷渡专员：File Importer
• 🔐 处理脏物：安全范围访问权限
• 💣 专家建议：记得“毁尸灭迹”
• 📄 解码情报：读取与展示
• 🎬 终章：大功告成

Neo 嘴角微微上扬，手指在键盘上敲出一行代码：“别急，我刚找到了一个被遗忘的后门——File Importer。”

🕵️‍♂️ 呼叫偷渡专员：File Importer

在 iOS 的森严壁垒中，App 通常只能在自己的沙盒里「坐井观天」。但偶尔，我们也需要从外面的花花世界（比如设备存储或 iCloud Drive）搞点“私货”进来。

为了不触发警报，Apple 实际上提供了一个官方的“中间人”——System Document Picker。

在 SwiftUI 中，我们可以用 fileImporter 这个 View Modifier（视图修饰符）来通过正规渠道“行贿”系统，从而打开通往外部文件的大门。

为了向 Trinity 演示这个过程，Neo 快速构建了一个简单的诱饵 App。它的功能很简单：打开系统的文件选择器，选中那些机密文本文件，处理它们，最后把内容展示出来。

就像控制防爆门的开关一样，我们需要一个 State Property（状态属性）来控制文件选择器是否弹出：

@State private var showFileImporter = false

接着，Neo 设置了一个触发按钮。这就像是特工手里的红色起爆器：

NavigationStack {
    List {
        // 这里稍后会填入我们偷来的数据
    }
    .navigationTitle("绝密档案读取器")
    .toolbar {
        ToolbarItem(placement: .primaryAction) {
            // 点击按钮，呼叫“中间人”
            Button {
                showFileImporter = true
            } label: {
                Label("选取情报", systemImage: "tray.and.arrow.down")
            }
        }
    }
}

通常，.fileImporter 这位“中间人”办事需要收取四个参数，缺一不可：

1. isPresented: 绑定那个控制开关的状态属性 ($showFileImporter)。
2. allowedContentTypes: 也就是“通关文牒”，规定了只允许带什么类型的文件进来。
3. allowsMultipleSelection: 是否允许“顺手牵羊”带走多个文件。
4. onCompletion: 当交易完成（或失败）后的回调闭包。

在这个行动中，我们只对文本文件（.text）感兴趣，而且既然来了，就得多拿点，开启多选模式：

NavigationStack {
    // ... 之前的代码
}
.fileImporter(
    isPresented: $showFileImporter,
    allowedContentTypes: [.text], // 只认文本文件，其他闲杂人等退散
    allowsMultipleSelection: true // 贪心一点，多多益善
) { result in
    // 交易结果在这里处理
}

⚠️ 注意： 为了让编译器看懂 .text 是个什么鬼，你需要引入 UniformTypeIdentifiers 框架。这就像是通用的星际语言包：

import UniformTypeIdentifiers

回调中的 result 参数是一个 Result<[URL], any Error> 类型。它要么给我们带回一堆 URL（情报地址），要么甩给我们一个 Error（行动失败）。

🔐 处理脏物：安全范围访问权限

拿到 URL 并不代表你就能直接读取文件了。太天真了！在 Apple 的地盘，那些文件都在 Security Scoped（安全范围）的保护之下。这就好比你拿到了金库的地址，但还没有金库的钥匙。

Neo 必须小心翼翼地处理这些结果。通常我们会用 switch 语句来拆包：

private func handleImportedFiles(result: Result<[URL], any Error>) {
    switch result {
        case .success(let urls):
            // 搞定！开始处理这些 URL
            for url in urls {
                // ... 核心破解逻辑
            }
            
        case .failure(let error):
            // 翻车了，打印错误日志，准备跑路
            print(error.localizedDescription)
    }
}

接下来是整个行动中最惊心动魄的部分。

对于这些沙盒外的文件，在读取之前，必须向系统申请“临时通行证”。如果这一步没做，你的 App 就会像撞上隐形墙的苍蝇一样，虽然看得到文件，但死活读不出来。

流程如下：

1. Request Access: 使用 startAccessingSecurityScopedResource() 申请访问。
2. Process: 赶紧读取数据。
3. Relinquish Access: 用 stopAccessingSecurityScopedResource() 归还权限，毁尸灭迹。

Neo 的手指在键盘上飞舞，写下了这段生死攸关的代码：

private func handleImportedFiles(result: Result<[URL], any Error>) {
    switch result {
        case .success(let urls):
            for url in urls {
                // 1. 敲门：申请临时访问权限。如果系统不答应（返回 false），直接跳过
                guard url.startAccessingSecurityScopedResource() else {
                    continue
                }
                
                // 2. 办事：读取文件内容
                readFile(at: url)
                
                // 3. 擦屁股：必须停止访问，释放权限资源
                url.stopAccessingSecurityScopedResource()
            }
        case .failure(let error):
            print(error.localizedDescription)
    }
}

Neo 的黑色幽默笔记： 如果需要，你可以把文件从那个 URL 复制到 App 自己的沙盒里。那就叫“洗黑钱”，一旦进了沙盒，以后想怎么读就怎么读，不用再看系统脸色了。

💣 专家建议：记得“毁尸灭迹”

Trinity 皱了皱眉：“Neo，万一 readFile 里面抛出了异常或者提前 return 了怎么办？那你岂不是忘了调用 stopAccessing...？这会造成资源泄漏，被‘母体’追踪到的。”

“这正是我要说的，” Neo 笑了笑，“这就需要用到 defer 语句。它就像是安装在代码里的死手开关，无论函数怎么结束，它都会保证最后执行。”

更优雅、更安全的写法是这样的：

// 申请权限，失败则撤退
guard url.startAccessingSecurityScopedResource() else { return }

// 无论发生什么，离开作用域前一定要把权限关掉！
defer { url.stopAccessingSecurityScopedResource() }

// ... 尽情处理文件吧 ...

📄 解码情报：读取与展示

为了让抵抗军的兄弟们能看懂这些情报，Neo 定义了一个数据结构来承载这些秘密：

struct ImportedFile: Identifiable {
    let id = UUID()
    let name: String
    let content: String // 文件的真实内容
}

还需要一个容器来存放这一堆战利品：

@State private var importedFiles = [ImportedFile]()

最后，实现那个 readFile(at:) 方法。它将把文件数据读成二进制 Data，然后转码成人类可读的 String，最后封装进我们的数组里：

private func readFile(at url: URL) {
    do {
        // 读取二进制数据
        let data = try Data(contentsOf: url)
        
        // 尝试转码为 UTF8 字符串。如果乱码，说明也许那是外星人的文字，直接放弃
        guard let content = String(data: data, encoding: .utf8) else {
            return
        }
        
        // 将情报归档
        importedFiles.append(
            ImportedFile(name: url.lastPathComponent, content: content)
        )
    } catch {
        // 捕获异常，不要让 App 崩溃
        print(error.localizedDescription)
    }
}

界面部分，用一个 List 就能把这些“罪证”展示得明明白白：

List(importedFiles) { file in
    VStack(alignment: .leading, spacing: 6) {
        Text(file.name)
            .font(.headline)
        
        Text(file.content)
            .foregroundStyle(.secondary)
    }
}

🎬 终章：大功告成

随着最后一行代码编译通过，屏幕上跳出了一个列表，那是从 iCloud 深处提取出来的核心代码。Trinity 看着屏幕，露出了久违的笑容。

fileImporter 虽然听起来像个不起眼的龙套角色，但当你需要在沙盒的铜墙铁壁上开个洞时，它就是最趁手的瑞士军刀。虽然配置和调用看起来很简单，但千万别忘了那最重要的“申请与释放权限”的步骤——这就好比去金库偷钱，得手后一定要记得擦掉指纹，关上柜门。

“看来我们又活过了一天。” Neo 合上电脑，看向窗外闪烁的霓虹灯，“走吧，去喝一杯，那个 Bug 明天再修。”

更多相关的精彩内容，请小伙伴们移步如下链接观赏：

• SwiftUI 实现一个 iOS 上 Files App 兼容的文件资源管理器
• iOS从Files App中无法打开特定格式文件的解决(提示没有访问权限)
• SwiftUI 中创建一个自定义文件管理器只需4步！你敢信！？

希望这篇‘偷渡指南’对宝子们有所帮助。感谢阅读，Agent，Over！

借助AI辅助。

函数概述

__CFRunLoopDoBlocks 是 RunLoop 中负责执行 block 的核心函数。它处理通过 CFRunLoopPerformBlock 添加到 RunLoop 中的异步 blocks，这些 blocks 会在 RunLoop 的每次循环中被执行。

函数签名

static Boolean __CFRunLoopDoBlocks(CFRunLoopRef rl, CFRunLoopModeRef rlm)

参数说明

• CFRunLoopRef rl: 当前运行的 RunLoop
• CFRunLoopModeRef rlm: 当前的 RunLoop Mode

返回值

• Boolean: 如果至少执行了一个 block 返回 true，否则返回 false

前置条件

• 函数调用时必须持有锁: rl 和 rlm 都必须处于加锁状态
• 函数返回时保持锁状态: 出口时 rl 和 rlm 仍然加锁

Block Item 数据结构

struct _block_item {
    struct _block_item *_next;  // 链表的下一个节点
    CFTypeRef _mode;            // 可以是 CFStringRef 或 CFSetRef
    void (^_block)(void);       // 要执行的 block
};

RunLoop 中的 Block 链表

rl->_blocks_head  -->  [Block1] -> [Block2] -> [Block3] -> NULL
                         ^                        ^
                         |                        |
                     (first)                   (last)
                                                  |
                                        rl->_blocks_tail

完整代码逐行注释

// 📝 调用此函数时，rl 和 rlm 必须已加锁
// 函数返回时，rl 和 rlm 仍然保持加锁状态
static Boolean __CFRunLoopDoBlocks(CFRunLoopRef rl, CFRunLoopModeRef rlm) { // Call with rl and rlm locked
    
    // ==================== 第一部分：性能追踪和前置检查 ====================
    
    // 📊 记录性能追踪点：开始执行 blocks
    // 可通过 Instruments 的 kdebug 工具查看此事件
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_BLOCKS | DBG_FUNC_START, rl, rlm, 0, 0);
    
    // 🚪 快速退出1：如果 RunLoop 中没有待处理的 blocks
    // _blocks_head 为 NULL 表示链表为空，直接返回 false（表示没有执行任何 block）
    if (!rl->_blocks_head) return false;
    
    // 🚪 快速退出2：如果 mode 无效或没有名称
    // 这是一个防御性检查，正常情况下不应该发生
    if (!rlm || !rlm->_name) return false;
    
    // 标志位：记录是否至少执行了一个 block
    Boolean did = false;
    
    // ==================== 第二部分：摘取整个 Block 链表 ====================
    
    // 保存链表头指针到局部变量
    struct _block_item *head = rl->_blocks_head;
    
    // 保存链表尾指针到局部变量
    struct _block_item *tail = rl->_blocks_tail;
    
    // 🎯 清空 RunLoop 的 blocks 链表头
    // 将所有 blocks "取出"到局部变量中（摘取操作）
    rl->_blocks_head = NULL;
    
    // 🎯 清空 RunLoop 的 blocks 链表尾
    // 此时 RunLoop 中已经没有 blocks 了
    rl->_blocks_tail = NULL;
    
    // ⚠️ 为什么要清空 RunLoop 的链表？
    // 1. 避免在执行 block 期间，其他代码再次访问这些 blocks
    // 2. 允许 block 执行期间添加新的 blocks（不会与当前正在处理的 blocks 冲突）
    // 3. 未执行的 blocks 稍后会被重新添加回 RunLoop
    
    // 获取 RunLoop 的 commonModes 集合
    // commonModes 通常包含 kCFRunLoopDefaultMode 和 UITrackingRunLoopMode
    CFSetRef commonModes = rl->_commonModes;
    
    // 获取当前 mode 的名称（如 "kCFRunLoopDefaultMode"）
    CFStringRef curMode = rlm->_name;
    
    // ==================== 第三部分：解锁（准备执行 blocks）====================
    
    // 🔓 解锁 RunLoop Mode
    __CFRunLoopModeUnlock(rlm);
    
    // 🔓 解锁 RunLoop
    __CFRunLoopUnlock(rl);
    
    // ⚠️ 为什么要解锁？
    // 1. 防止死锁：block 中可能调用 RunLoop API（如 CFRunLoopPerformBlock）
    // 2. 避免长时间持锁：block 可能执行耗时操作
    // 3. 提高并发性：允许其他线程在 block 执行期间访问 RunLoop
    
    // 🛡️ 安全性保证：
    // - 已经将 blocks 链表"摘取"到局部变量 head/tail
    // - 即使其他线程修改了 rl->_blocks_head，也不会影响本次执行
    // - 新添加的 blocks 会形成新的链表，不会与当前正在处理的链表冲突
    
    // ==================== 第四部分：遍历链表，执行符合条件的 blocks ====================
    
    // 前驱节点指针（用于链表删除操作）
    // 当删除节点时，需要修改前驱节点的 _next 指针
    struct _block_item *prev = NULL;
    
    // 当前遍历的节点，从头节点开始
    struct _block_item *item = head;
    
    // 遍历整个 blocks 链表
    while (item) {
        
        // 保存当前节点到 curr（因为 item 会被提前移动到下一个节点）
        struct _block_item *curr = item;
        
        // 🔜 提前移动到下一个节点
        // 原因：如果 curr 被删除（执行并释放），item 仍然指向有效的下一个节点
        // 避免在删除节点后访问已释放的内存
        item = item->_next;
        
        // 标志位：当前 block 是否应该在当前 mode 下执行
        Boolean doit = false;
        
        // ---------- 判断 Block 是否应该在当前 Mode 下执行 ----------
        
        // 🔍 情况1：_mode 是 CFString 类型（单个 mode）
        // CFGetTypeID() 获取对象的类型ID，_kCFRuntimeIDCFString 是 CFString 类型的常量ID
        if (_kCFRuntimeIDCFString == CFGetTypeID(curr->_mode)) {
            
            // 判断逻辑（两种情况任一成立即可）：
            // 条件1: CFEqual(curr->_mode, curMode)
            //   block 指定的 mode 与当前 mode 完全匹配
            //   例如：block 添加到 "kCFRunLoopDefaultMode"，当前也是 "kCFRunLoopDefaultMode"
            // 条件2: CFEqual(curr->_mode, kCFRunLoopCommonModes) && CFSetContainsValue(commonModes, curMode)
            //   block 添加到 "kCFRunLoopCommonModes" 且当前 mode 在 commonModes 集合中
            //   例如：block 添加到 "kCFRunLoopCommonModes"，当前是 "kCFRunLoopDefaultMode"
            //         且 commonModes 包含 "kCFRunLoopDefaultMode"，则应该执行
            doit = CFEqual(curr->_mode, curMode) || (CFEqual(curr->_mode, kCFRunLoopCommonModes) && CFSetContainsValue(commonModes, curMode));
            
        } else {
            // 🔍 情况2：_mode 是 CFSet 类型（多个 modes 的集合）
            
            // 判断逻辑（两种情况任一成立即可）：
            // 条件1: CFSetContainsValue((CFSetRef)curr->_mode, curMode)
            //   block 指定的 modes 集合中包含当前 mode
            //   例如：block 添加到 {"Mode1", "Mode2"}，当前是 "Mode1"
            // 条件2: CFSetContainsValue((CFSetRef)curr->_mode, kCFRunLoopCommonModes) && CFSetContainsValue(commonModes, curMode)
            //   block 指定的 modes 集合中包含 "kCFRunLoopCommonModes"
            //   且当前 mode 在 commonModes 集合中
            doit = CFSetContainsValue((CFSetRef)curr->_mode, curMode) || (CFSetContainsValue((CFSetRef)curr->_mode, kCFRunLoopCommonModes) && CFSetContainsValue(commonModes, curMode));
        }
        
        // ---------- 处理不执行的 Block ----------
        
        // 如果当前 block 不需要执行：
        // 更新 prev 指针，指向当前节点
        // 这个节点会被保留在链表中（稍后重新添加回 RunLoop）
        if (!doit) prev = curr;
        
        // ---------- 处理需要执行的 Block ----------
        
        if (doit) {
            // 当前 block 需要在当前 mode 下执行
            
            // ===== 子部分1：从链表中移除当前节点 =====
            
            // 如果有前驱节点，将前驱节点的 next 指针指向下一个节点
            // 跳过当前节点（curr），实现删除
            // 示例：prev -> curr -> item  变为  prev ---------> item（删除 curr）
            if (prev) prev->_next = item;
            
            // 如果当前节点是头节点，更新头指针
            // 新的头节点变成下一个节点
            if (curr == head) head = item;
            
            // 如果当前节点是尾节点，更新尾指针
            // 新的尾节点变成前驱节点
            if (curr == tail) tail = prev;
            
            // ===== 子部分2：提取 Block 信息并释放节点内存 =====
            
            // 提取 block 闭包（复制指针）
            // 类型：void (^)(void) 表示无参数无返回值的 block
            void (^block)(void) = curr->_block;
            
            // 释放 mode 对象（CFString 或 CFSet）
            // 减少引用计数，可能触发对象销毁
            CFRelease(curr->_mode);
            
            // 释放节点结构体的内存（C 风格内存管理）
            // 此时 curr 指针已无效，不能再访问
            free(curr);
            
            // ===== 子部分3：执行 Block =====
            
            // ⚠️ 这里的 if (doit) 是冗余的（外层已经检查过）
            // 可能是历史遗留代码或防御性编程
            if (doit) {
                
                // 🔄 开始自动释放池（ARP = AutoRelease Pool）
                // 管理 block 执行期间创建的临时对象
                CFRUNLOOP_ARP_BEGIN(rl);
                
                // 📊 记录性能追踪点：开始调用 block
                cf_trace(KDEBUG_EVENT_CFRL_IS_CALLING_BLOCK | DBG_FUNC_START, rl, rlm, block, 0);
                
                // ⚡ 执行 block 的核心宏
                // 展开后通常是：block();
                // 这是整个函数的核心目的！
                // ⚠️ Block 执行期间可能发生：UI 更新、网络请求、数据库操作、
                //    再次调用 CFRunLoopPerformBlock、操作 RunLoop、长时间阻塞等
                __CFRUNLOOP_IS_CALLING_OUT_TO_A_BLOCK__(block);
                
                // 📊 记录性能追踪点：结束调用 block
                // 可计算 block 执行耗时 = end - start
                cf_trace(KDEBUG_EVENT_CFRL_IS_CALLING_BLOCK | DBG_FUNC_END, rl, rlm, block, 0);
                
                // 🔄 结束自动释放池
                // 释放 block 中创建的所有 autorelease 对象
                CFRUNLOOP_ARP_END();
                
                // ✅ 标记：至少执行了一个 block
                did = true;
            }
            
            // ===== 子部分4：释放 Block =====
            
            // 释放 block 对象（减少引用计数）
            // block 可能会被销毁，触发其捕获变量的释放
            // 💡 为什么在重新加锁之前释放？
            // 注释原文："do this before relocking to prevent deadlocks 
            //          where some yahoo wants to run the run loop reentrantly 
            //          from their dealloc"
            // 原因：block 的 dealloc 可能触发捕获变量的析构函数，
            //       某些"聪明人"可能在 dealloc 中重入 RunLoop，
            //       如果此时持有锁，会导致死锁。
            //       在解锁状态下释放 block，即使 dealloc 尝试操作 RunLoop，
            //       也不会因为已持有锁而死锁
            Block_release(block); // do this before relocking to prevent deadlocks where some yahoo wants to run the run loop reentrantly from their dealloc
        }
    }
    
    // ==================== 第五部分：重新加锁 ====================
    
    // 🔒 重新锁定 RunLoop
    __CFRunLoopLock(rl);
    
    // 🔒 重新锁定 RunLoop Mode
    __CFRunLoopModeLock(rlm);
    
    // ✅ 恢复函数入口时的锁状态
    // 满足函数约定："Call with rl and rlm locked"
    
    // ==================== 第六部分：将未执行的 Blocks 放回 RunLoop ====================
    
    // 如果还有未执行的 blocks（链表不为空）
    // head 和 tail 现在指向未执行的 blocks 链表（已执行的 blocks 已从链表中移除）
    if (head && tail) {
        // 将未执行的链表的尾部连接到 RunLoop 当前的 blocks 链表头部
        // 示例：
        // 未执行的链表：[Block1] -> [Block2] -> NULL (head=Block1, tail=Block2)
        // RunLoop 当前链表：[Block3] -> [Block4] -> NULL (rl->_blocks_head=Block3)
        // 连接后：[Block1] -> [Block2] -> [Block3] -> [Block4] -> NULL
        tail->_next = rl->_blocks_head;
        
        // 更新 RunLoop 的 blocks 链表头指针
        // 指向未执行的链表的头部
        rl->_blocks_head = head;
        
        // 如果 RunLoop 当前没有尾指针（即 _blocks_head 原本为 NULL）
        // 则将尾指针设置为未执行链表的尾部
        // ⚠️ 注意：如果 rl->_blocks_tail 已经存在，不更新它
        // 因为新的尾节点应该是原来 RunLoop 链表的尾节点
        // （未执行的链表已经通过 tail->_next 连接到了原链表前面）
        // 📊 重新插入的顺序：未执行的 blocks 被放在队列的最前面，
        //    在执行期间新添加的 blocks 排在后面，
        //    这保证了未执行的 blocks 在下次循环中优先被执行
        if (!rl->_blocks_tail) rl->_blocks_tail = tail;
    }
    
    // ==================== 第七部分：结束性能追踪 ====================
    
    // 📊 记录性能追踪点：完成 blocks 执行
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_BLOCKS | DBG_FUNC_END, rl, rlm, 0, 0);
    
    // 返回是否至少执行了一个 block
    // true：执行了至少一个 block
    // false：没有执行任何 block（所有 blocks 的 mode 都不匹配）
    return did;
}

关键设计要点

1. Mode 匹配逻辑

Block 的 mode 可以是两种类型：

类型1：CFString（单个 mode）

// 添加到特定 mode
CFRunLoopPerformBlock(runLoop, kCFRunLoopDefaultMode, ^{
    NSLog(@"Execute in default mode only");
});

// 添加到 common modes
CFRunLoopPerformBlock(runLoop, kCFRunLoopCommonModes, ^{
    NSLog(@"Execute in all common modes");
});

匹配规则:

1. 精确匹配：block.mode == currentMode
2. Common modes 匹配：block.mode == kCFRunLoopCommonModes && currentMode ∈ commonModes

类型2：CFSet（多个 modes）

// 添加到多个 modes
CFSetRef modes = CFSetCreate(NULL, 
    (const void *[]){kCFRunLoopDefaultMode, CFSTR("CustomMode")}, 
    2, 
    &kCFTypeSetCallBacks);

CFRunLoopPerformBlock(runLoop, modes, ^{
    NSLog(@"Execute in default or custom mode");
});
CFRelease(modes);

匹配规则:

1. 集合包含：currentMode ∈ block.modes
2. Common modes 匹配：kCFRunLoopCommonModes ∈ block.modes && currentMode ∈ commonModes

2. 链表操作详解

初始状态：
rl->_blocks_head --> [A] -> [B] -> [C] -> [D] -> NULL
                      ^                     ^
                   (match)  (no)   (no)  (match)

执行后：
- A 和 D 已执行并释放
- B 和 C 未执行（mode 不匹配）

剩余链表：
head --> [B] -> [C] -> NULL
          ^      ^
        prev   tail

重新插入（假设期间添加了新 block E）：
rl->_blocks_head --> [E] -> NULL

连接后：
rl->_blocks_head --> [B] -> [C] -> [E] -> NULL

3. 锁的管理策略

入口状态：rl 锁定 + rlm 锁定
  ↓
摘取 blocks 链表（持有锁）
  ↓
解锁 rl 和 rlm
  ↓
遍历并执行 blocks（无全局锁）
  ↓
重新锁定 rl 和 rlm
  ↓
放回未执行的 blocks（持有锁）
  ↓
出口状态：rl 锁定 + rlm 锁定

为什么这样设计？

4. 内存管理细节

// 节点创建（在 CFRunLoopPerformBlock 中）
struct _block_item *item = malloc(sizeof(struct _block_item));
item->_mode = CFRetain(mode);      // 引用计数 +1
item->_block = Block_copy(block);  // 引用计数 +1

// 节点销毁（在 __CFRunLoopDoBlocks 中）
CFRelease(curr->_mode);    // 引用计数 -1
free(curr);                // 释放节点内存
Block_release(block);      // 引用计数 -1

引用计数管理:

1. CFRetain/CFRelease: 管理 mode 对象（CFString/CFSet）
2. Block_copy/Block_release: 管理 block 对象
3. malloc/free: 管理节点结构体

5. 避免死锁的设计

Block_release(block); // do this before relocking to prevent deadlocks
__CFRunLoopLock(rl);

潜在的死锁场景:

__weak typeof(self) weakSelf = self;
CFRunLoopPerformBlock(runLoop, mode, ^{
    // block 捕获了 weakSelf
});

// 在对象的 dealloc 中
- (void)dealloc {
    // 当 block 被释放时，weakSelf 也会被释放
    // 如果开发者在 dealloc 中操作 RunLoop...
    CFRunLoopRun();  // 尝试获取 RunLoop 锁 -> 死锁！
}

解决方案: 在解锁状态下释放 block，即使 dealloc 中操作 RunLoop 也不会死锁。

性能特性

1. 时间复杂度

• 遍历链表: O(n)，n 为 blocks 数量
• Mode 匹配: O(1) 或 O(m)，m 为 modes 集合大小（通常很小）
• 链表操作: O(1)（插入/删除单个节点）

2. 空间复杂度

• 链表存储: O(n)，n 为待处理的 blocks 数量
• 局部变量: O(1)

3. 性能优化

if (!rl->_blocks_head) return false;  // 快速退出

如果没有 blocks，立即返回，避免不必要的操作。

使用场景

1. 在主线程异步执行代码

// 在后台线程
dispatch_async(backgroundQueue, ^{
    // 执行耗时操作...
    NSData *data = [self fetchDataFromNetwork];
    
    // 切换到主线程更新 UI
    CFRunLoopPerformBlock(CFRunLoopGetMain(), kCFRunLoopCommonModes, ^{
        self.imageView.image = [UIImage imageWithData:data];
    });
    CFRunLoopWakeUp(CFRunLoopGetMain());  // 唤醒主线程 RunLoop
});

2. 在特定 Mode 下执行代码

// 只在默认 mode 下执行（滚动时不执行）
CFRunLoopPerformBlock(CFRunLoopGetCurrent(), kCFRunLoopDefaultMode, ^{
    [self performHeavyCalculation];
});

// 在所有 common modes 下执行（包括滚动时）
CFRunLoopPerformBlock(CFRunLoopGetCurrent(), kCFRunLoopCommonModes, ^{
    [self updateCriticalUI];
});

3. 跨线程通信

// 线程 A
CFRunLoopRef threadBRunLoop = ...; // 获取线程 B 的 RunLoop
CFRunLoopPerformBlock(threadBRunLoop, kCFRunLoopDefaultMode, ^{
    NSLog(@"This runs on thread B");
});
CFRunLoopWakeUp(threadBRunLoop);  // 唤醒线程 B

// 线程 B
CFRunLoopRun();  // 等待并处理事件（包括 blocks）

与 GCD 的对比

CFRunLoopPerformBlock vs dispatch_async

使用建议:

• CFRunLoopPerformBlock: 需要与 RunLoop mode 交互（如 UI 更新）
• dispatch_async: 通用异步任务（推荐）

与其他 RunLoop 函数的关系

__CFRunLoopRun (主循环)
  │
  ├─ do {
  │    │
  │    ├─ __CFRunLoopDoObservers(kCFRunLoopBeforeTimers)
  │    ├─ __CFRunLoopDoObservers(kCFRunLoopBeforeSources)
  │    │
  │    ├─ __CFRunLoopDoBlocks(rl, rlm)  // ⭐ 处理 blocks
  │    │
  │    ├─ __CFRunLoopDoSources0(rl, rlm)
  │    │
  │    ├─ __CFRunLoopDoBlocks(rl, rlm)  // ⭐ 再次处理（可能有新添加的）
  │    │
  │    ├─ 检查是否有 Source1 待处理
  │    │
  │    ├─ __CFRunLoopDoObservers(kCFRunLoopBeforeWaiting)
  │    ├─ __CFRunLoopServiceMachPort(...)  // 等待事件
  │    ├─ __CFRunLoopDoObservers(kCFRunLoopAfterWaiting)
  │    │
  │    ├─ 处理唤醒源（Timer/Source1/GCD）
  │    │
  │    └─ __CFRunLoopDoBlocks(rl, rlm)  // ⭐ 最后再处理一次
  │
  └─ } while (!stop);

调用频率: 每次 RunLoop 循环通常调用 2-3 次。

潜在问题和注意事项

1. Block 执行顺序不保证

CFRunLoopPerformBlock(runLoop, mode, ^{ NSLog(@"1"); });
CFRunLoopPerformBlock(runLoop, mode, ^{ NSLog(@"2"); });
CFRunLoopPerformBlock(runLoop, mode, ^{ NSLog(@"3"); });

// 输出：可能是 1, 2, 3
// 但如果第一次循环某些 block 的 mode 不匹配，顺序可能改变

原因: 未执行的 blocks 会被重新插入队列头部。

2. Block 中的长时间操作

// ❌ 不好的做法
CFRunLoopPerformBlock(CFRunLoopGetMain(), kCFRunLoopCommonModes, ^{
    sleep(5);  // 阻塞主线程 5 秒
    // UI 会卡顿！
});

// ✅ 正确的做法
CFRunLoopPerformBlock(CFRunLoopGetMain(), kCFRunLoopCommonModes, ^{
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
        sleep(5);  // 在后台线程执行
        dispatch_async(dispatch_get_main_queue(), ^{
            // 完成后更新 UI
        });
    });
});

3. Mode 不匹配导致 Block 不执行

// 添加到 Default mode
CFRunLoopPerformBlock(runLoop, kCFRunLoopDefaultMode, ^{
    NSLog(@"This will NOT run during scrolling");
});
CFRunLoopWakeUp(runLoop);

// 如果 RunLoop 当前在 UITrackingRunLoopMode（滚动时）
// Block 不会执行，会一直等到切换到 Default mode

解决方案: 使用 kCFRunLoopCommonModes:

CFRunLoopPerformBlock(runLoop, kCFRunLoopCommonModes, ^{
    NSLog(@"This runs in all common modes");
});

4. 忘记唤醒 RunLoop

// ❌ 不完整的代码
CFRunLoopPerformBlock(runLoop, mode, ^{
    NSLog(@"This might not run immediately");
});
// 如果 RunLoop 正在休眠（等待事件），block 不会立即执行

// ✅ 正确的做法
CFRunLoopPerformBlock(runLoop, mode, ^{
    NSLog(@"This will run soon");
});
CFRunLoopWakeUp(runLoop);  // 唤醒 RunLoop

5. 循环引用

// ❌ 循环引用
self.runLoop = CFRunLoopGetCurrent();
CFRunLoopPerformBlock(self.runLoop, mode, ^{
    [self doSomething];  // self 持有 runLoop，block 持有 self，runLoop 持有 block
});

// ✅ 使用 weak 引用
__weak typeof(self) weakSelf = self;
CFRunLoopPerformBlock(self.runLoop, mode, ^{
    [weakSelf doSomething];
});

调试技巧

1. 查看待处理的 Blocks

// 在 LLDB 中
(lldb) p rl->_blocks_head
(lldb) p rl->_blocks_tail

// 遍历链表
(lldb) p ((struct _block_item *)rl->_blocks_head)->_next

2. 追踪 Block 执行

// 添加日志
CFRunLoopPerformBlock(runLoop, mode, ^{
    NSLog(@"Block start: %@", [NSThread currentThread]);
    // 业务代码...
    NSLog(@"Block end");
});

3. 使用 Instruments

• 打开 Instruments
• 选择 "System Trace" 模板
• 查看 KDEBUG_EVENT_CFRL_IS_CALLING_BLOCK 事件
• 分析 block 执行耗时和频率

总结

__CFRunLoopDoBlocks 是 RunLoop 异步任务机制的核心实现，其精妙之处在于：

1. 灵活的 Mode 匹配: 支持单 mode、多 mode、common modes
2. 安全的锁管理: 执行前解锁，防止死锁和长时间持锁
3. 高效的链表操作: 摘取-处理-放回的三段式设计
4. 精细的内存管理: CFRetain/Block_copy 保证对象生命周期
5. 智能的释放时机: 在重新加锁前释放 block，避免 dealloc 中的死锁

这个函数体现了 CoreFoundation 在性能、安全性和灵活性之间的精妙平衡，是理解 RunLoop 异步机制的关键。

扩展阅读

CFRunLoopPerformBlock 的实现

void CFRunLoopPerformBlock(CFRunLoopRef rl, CFTypeRef mode, void (^block)(void)) {
    if (!rl || !block) return;
    
    struct _block_item *item = malloc(sizeof(struct _block_item));
    item->_next = NULL;
    item->_mode = CFRetain(mode);         // 持有 mode
    item->_block = Block_copy(block);     // 复制 block（栈 -> 堆）
    
    __CFRunLoopLock(rl);
    
    // 添加到链表尾部
    if (!rl->_blocks_head) {
        rl->_blocks_head = item;
    } else {
        rl->_blocks_tail->_next = item;
    }
    rl->_blocks_tail = item;
    
    __CFRunLoopUnlock(rl);
}

Common Modes 的定义

// 在 Cocoa/UIKit 中
NSRunLoopCommonModes 包含：
- NSDefaultRunLoopMode (kCFRunLoopDefaultMode)
- UITrackingRunLoopMode

// 效果
CFRunLoopPerformBlock(runLoop, kCFRunLoopCommonModes, block);
// 等价于
CFRunLoopPerformBlock(runLoop, kCFRunLoopDefaultMode, block);
CFRunLoopPerformBlock(runLoop, UITrackingRunLoopMode, block);

这确保了 block 在 UI 滚动时也能执行，提升了响应性。

__CFRunLoopDoObservers 函数逐行注释

函数概述

__CFRunLoopDoObservers 是 RunLoop 中负责触发观察者回调的核心函数。当 RunLoop 的状态发生变化时（如即将进入循环、即将处理 Timer、即将处理 Source 等），这个函数会被调用来通知所有注册的观察者。

函数签名

/* rl is locked, rlm is locked on entrance and exit */
static void __CFRunLoopDoObservers(CFRunLoopRef, CFRunLoopModeRef, CFRunLoopActivity) __attribute__((noinline));

注释说明

• 锁状态约定: 函数入口和出口时，rl（RunLoop）和 rlm（RunLoopMode）都必须处于加锁状态
• noinline 属性: 防止编译器内联优化此函数，可能是为了：
  • 便于调试和性能分析
  • 保持调用栈的可读性
  • 控制代码大小

参数说明

• CFRunLoopRef rl: 当前运行的 RunLoop
• CFRunLoopModeRef rlm: 当前的 RunLoop Mode
• CFRunLoopActivity activity: 当前 RunLoop 的活动状态（枚举值）

RunLoop Activity 状态枚举

typedef CF_OPTIONS(CFOptionFlags, CFRunLoopActivity) {
    kCFRunLoopEntry         = (1UL << 0),  // 即将进入 RunLoop
    kCFRunLoopBeforeTimers  = (1UL << 1),  // 即将处理 Timer
    kCFRunLoopBeforeSources = (1UL << 2),  // 即将处理 Source
    kCFRunLoopBeforeWaiting = (1UL << 5),  // 即将进入休眠
    kCFRunLoopAfterWaiting  = (1UL << 6),  // 刚从休眠中唤醒
    kCFRunLoopExit          = (1UL << 7),  // 即将退出 RunLoop
    kCFRunLoopAllActivities = 0x0FFFFFFFU   // 所有活动状态
};

完整代码逐行注释

/* DOES CALLOUT */
// 【重要标注】此函数会执行外部回调（callout），可能导致：
// 1. 长时间阻塞（回调函数耗时）
// 2. 重入问题（回调中可能再次操作 RunLoop）
// 3. 死锁风险（因此需要在回调前解锁）
static void __CFRunLoopDoObservers(CFRunLoopRef rl, CFRunLoopModeRef rlm, CFRunLoopActivity activity) {
    
    // ==================== 第一部分：性能追踪和初始化 ====================
    
    
    // 📊 记录性能追踪点：开始执行 observers
    // 参数：事件类型、RunLoop、Mode、活动状态、额外参数
    // 可用 Instruments 的 kdebug 工具查看
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_OBSERVERS | DBG_FUNC_START, rl, rlm, activity, 0);
    
    // 🔒 检查进程是否被 fork
    // 如果在 fork 后的子进程中，需要重新初始化 RunLoop 的锁和状态
    // 防止继承父进程的锁状态导致死锁
    CHECK_FOR_FORK();

    // ==================== 第二部分：检查观察者数量 ====================
    
    // 获取当前 Mode 中观察者的数量
    // 三目运算符防止 _observers 为 NULL 时崩溃
    CFIndex cnt = rlm->_observers ? CFArrayGetCount(rlm->_observers) : 0;
    
    // 快速退出：如果没有观察者，直接返回
    // 注意：此时仍持有锁，但不需要手动解锁（调用者会处理）
    if (cnt < 1) return;
    

    // ==================== 第三部分：分配观察者收集数组 ====================
    
    /* Fire the observers */
    // 📦 声明栈上缓冲区，避免小数组的堆分配开销
    // - 如果观察者数量 ≤ 1024：在栈上分配 cnt 个元素的数组
    // - 如果观察者数量 > 1024：在栈上分配 1 个元素（占位符）
    // 栈分配速度快，但空间有限（通常几 MB）
    STACK_BUFFER_DECL(CFRunLoopObserverRef, buffer, (cnt <= 1024) ? cnt : 1);
    
    // 🎯 确定最终使用的数组指针
    // - 小数组（≤1024）：使用栈缓冲区（快速，无需释放）
    // - 大数组（>1024）：堆分配（慢，但可容纳更多元素）
    // 1024 是经验阈值，平衡性能和栈空间使用
    CFRunLoopObserverRef *collectedObservers = (cnt <= 1024) ? buffer : (CFRunLoopObserverRef *)malloc(cnt * sizeof(CFRunLoopObserverRef));
    
    // 实际收集到的观察者计数器（可能小于 cnt）
    CFIndex obs_cnt = 0;
    
    // ==================== 第四部分：收集需要触发的观察者 ====================
    
    // 遍历 Mode 中的所有观察者
    for (CFIndex idx = 0; idx < cnt; idx++) {
        
        // 获取第 idx 个观察者对象
        CFRunLoopObserverRef rlo = (CFRunLoopObserverRef)CFArrayGetValueAtIndex(rlm->_observers, idx);
        
        
        // 🔍 三重过滤条件（必须全部满足）：
            
        // 条件1: 0 != (rlo->_activities & activity)
        // 按位与检查观察者是否关注当前活动状态
        // 例如：activity = kCFRunLoopBeforeTimers (0b10)
        // _activities = kCFRunLoopBeforeTimers | kCFRunLoopExit (0b10000010)
        // 按位与结果 = 0b10 != 0，条件成立

        // 条件2: __CFIsValid(rlo)
        // 检查观察者是否有效（未被 invalidate）
        // 观察者可能在之前的回调中被标记为无效

        // 条件3: !__CFRunLoopObserverIsFiring(rlo)
        // 检查观察者是否正在执行回调
        // 防止重入：如果观察者的回调函数中再次触发相同的 activity，
        // 不会重复调用该观察者（避免无限递归）
        if (0 != (rlo->_activities & activity) && __CFIsValid(rlo) && !__CFRunLoopObserverIsFiring(rlo)) {
            
            // ✅ 满足条件的观察者：
            // 1. 添加到收集数组
            // 2. 增加引用计数（CFRetain）
            //    - 防止在后续解锁期间被其他线程释放
            //    - 保证回调执行时对象仍然有效
            // 3. obs_cnt 递增
            collectedObservers[obs_cnt++] = (CFRunLoopObserverRef)CFRetain(rlo);
        }
    }
    
    // ==================== 第五部分：解锁（准备执行回调）====================
    
    // 🔓 解锁 RunLoop Mode
    __CFRunLoopModeUnlock(rlm);
    
    // 🔓 解锁 RunLoop
    __CFRunLoopUnlock(rl);
    
    // ⚠️ 为什么要解锁？
    // 1. 避免死锁：观察者回调可能会调用 RunLoop API（如添加 Timer、Source）
    // 2. 提高并发：允许其他线程在回调执行期间访问 RunLoop
    // 3. 防止长时间持锁：回调可能耗时很长（如网络请求、UI 更新）
    
    // 🛡️ 安全性保证：
    // - 已经通过 CFRetain 增加了观察者的引用计数
    // - collectedObservers 数组是当前线程的局部变量
    // - 即使其他线程修改了 rlm->_observers，也不会影响本次执行
    
    // ==================== 第六部分：执行观察者回调 ====================
    
    // 遍历收集到的观察者（注意：不是遍历 rlm->_observers）
    for (CFIndex idx = 0; idx < obs_cnt; idx++) {
        
        // 获取当前观察者
        CFRunLoopObserverRef rlo = collectedObservers[idx];
        
        // 🔒 锁定观察者对象（细粒度锁）
        // 只锁定单个观察者，不影响其他观察者的并发执行
        __CFRunLoopObserverLock(rlo);
        
        // 再次检查观察者是否有效
        // ⚠️ 为什么要再次检查？
        // 在解锁期间，其他线程可能已经调用了 CFRunLoopObserverInvalidate
        if (__CFIsValid(rlo)) {
            
            // 检查观察者是否是一次性的（non-repeating）
            // 如果是一次性的，执行完回调后需要 invalidate
            Boolean doInvalidate = !__CFRunLoopObserverRepeats(rlo);
            
            // 🚩 设置"正在执行"标志位
            // 防止重入（与前面的 !__CFRunLoopObserverIsFiring 配合）
            __CFRunLoopObserverSetFiring(rlo);
            
            // 🔓 在执行回调前解锁观察者
            // 原因同解锁 RunLoop：防止回调中访问观察者对象时死锁
            __CFRunLoopObserverUnlock(rlo);
            
            // ---------- 提取回调信息 ----------
            
            // 提取回调函数指针
            // 类型：void (*)(CFRunLoopObserverRef observer, CFRunLoopActivity activity, void *info)
            CFRunLoopObserverCallBack callout = rlo->_callout;
            
            // 提取用户上下文信息（创建观察者时传入的）
            void *info = rlo->_context.info;
            
            // ---------- 自动释放池 ----------
            
            // 🔄 开始自动释放池（ARP = AutoRelease Pool）
            // 在 ObjC 运行时环境中，等价于 @autoreleasepool {
            // 用于自动管理回调中创建的临时对象
            CFRUNLOOP_ARP_BEGIN(rl)
            
            // ---------- 性能追踪 ----------
            
            // 📊 记录性能追踪点：开始调用观察者回调
            cf_trace(KDEBUG_EVENT_CFRL_IS_CALLING_OBSERVER | DBG_FUNC_START, callout, rlo, activity, info);
            
            
            // ---------- 🎯 核心回调执行 ----------
            
            // ⚡ 执行观察者的回调函数
            // 宏定义通常是：callout(rlo, activity, info);
            // 这是整个函数的核心目的！
            
            // ⏰ 回调函数的参数：
            // - rlo: 观察者对象本身
            // - activity: 当前 RunLoop 活动状态（如 kCFRunLoopBeforeTimers）
            // - info: 用户自定义的上下文信息
            
            // ⚠️ 回调中可能发生的事情：
            // - UI 更新（如 CA::Transaction::observer_callback）
            // - 性能监控（如 FPS 检测）
            // - 内存管理（如清理缓存）
            // - 业务逻辑（如状态同步）
            // - 再次操作 RunLoop（如添加/移除 Timer）
            __CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__(callout, rlo, activity, info);
            
            
            // ---------- 性能追踪结束 ----------
            
            // 📊 记录性能追踪点：结束调用观察者回调
            // 可通过 end - start 计算回调耗时
            cf_trace(KDEBUG_EVENT_CFRL_IS_CALLING_OBSERVER | DBG_FUNC_END, callout, rlo, activity, info);
            
            // ---------- 自动释放池结束 ----------
            
            // 🔄 结束自动释放池
            // 释放回调中创建的所有 autorelease 对象
            CFRUNLOOP_ARP_END()
           
            
            // ---------- 处理一次性观察者 ----------
            
            // 如果是一次性观察者（non-repeating）
            if (doInvalidate) {
                // ❌ 使观察者失效
                // 会从 RunLoop 中移除，并标记为无效
                // 后续不会再触发此观察者
                CFRunLoopObserverInvalidate(rlo);
            }
            
            // 🚩 清除"正在执行"标志位
            // 允许此观察者在下次 activity 时再次被触发
            __CFRunLoopObserverUnsetFiring(rlo);
            
        } else {
            // 观察者在解锁期间已被其他线程 invalidate
            
            // 🔓 解锁观察者（前面已加锁）
            // 跳过回调执行
            __CFRunLoopObserverUnlock(rlo);
        }
        
        // 📉 释放引用计数（对应前面的 CFRetain）
        // 如果引用计数归零，观察者对象会被销毁
        CFRelease(rlo);
    }
    
    // ==================== 第七部分：重新加锁 ====================
    
    // 🔒 重新锁定 RunLoop
    __CFRunLoopLock(rl);
    
    // 🔒 重新锁定 RunLoop Mode
    __CFRunLoopModeLock(rlm);
    
    // ✅ 恢复函数入口时的锁状态
    // 满足函数签名中的约定："rl is locked, rlm is locked on entrance and exit"

    // ==================== 第八部分：清理资源 ====================
    
    // 🗑️ 释放堆内存（如果使用了 malloc）
    // - 如果 collectedObservers 指向栈缓冲区（buffer），无需释放
    // - 如果 collectedObservers 指向堆内存（malloc），需要手动释放
    // 防止内存泄漏
    if (collectedObservers != buffer) free(collectedObservers);
    
    // ==================== 第九部分：结束性能追踪 ====================
    
    // 📊 记录性能追踪点：完成 observers 执行
    cf_trace(KDEBUG_EVENT_CFRL_IS_DOING_OBSERVERS | DBG_FUNC_END, rl, rlm, activity, 0);
}

常见使用场景

1. UI 渲染（Core Animation）

// CA 在 kCFRunLoopBeforeWaiting 时提交渲染事务
CFRunLoopObserverRef observer = CFRunLoopObserverCreate(
    kCFAllocatorDefault, 
    kCFRunLoopBeforeWaiting | kCFRunLoopExit,  // 监听这两个状态
    YES,  // 重复触发
    2000000,  // order = 2000000（在大多数 observer 之后）
    &CA_Transaction_observerCallback,  // 回调函数
    NULL
);

2. 性能监控（FPS 检测）

// 监控主线程 RunLoop 的卡顿
CFRunLoopObserverRef observer = CFRunLoopObserverCreate(
    kCFAllocatorDefault,
    kCFRunLoopAllActivities,  // 监听所有活动
    YES,
    0,
    &performanceMonitorCallback,
    NULL
);

void performanceMonitorCallback(CFRunLoopObserverRef observer, 
                                CFRunLoopActivity activity, 
                                void *info) {
    // 记录时间戳，计算两次回调之间的间隔
    // 如果间隔过长，说明发生了卡顿
}

3. 内存管理（自动释放池）

// NSRunLoop 在每次循环前后创建/销毁自动释放池
CFRunLoopObserverRef observer = CFRunLoopObserverCreate(
    kCFAllocatorDefault,
    kCFRunLoopEntry | kCFRunLoopBeforeWaiting | kCFRunLoopExit,
    YES,
    -2147483647,  // 极高优先级（负值）
    &autoreleasePoolCallback,
    NULL
);

总结

这个函数是理解 RunLoop 机制和 iOS 事件循环的关键，也是许多高级特性（如 UI 渲染、性能监控）的基础。

概述

许多较旧的 iOS 应用使用一个 UIApplicationDelegate 对象作为其应用的主要入口点，并管理应用的生命周期。使用场景的应用则不同，它们使用一个 UISceneDelegate 对象来分别管理每个场景窗口。从基于 UIApplicationDelegate 的应用生命周期迁移到基于场景的生命周期，可以让你的应用支持多窗口等现代功能。本文档阐述了如何将应用迁移到基于场景的生命周期。

迁移路径

将应用迁移到基于场景的生命周期有两种路径：

• 分阶段迁移：应用在继续使用 UIApplicationDelegate 的同时，逐步采用 UISceneDelegate。
• 直接迁移：应用一次性直接迁移到 UISceneDelegate。

在分阶段迁移中，你可以在应用的不同部分逐步实现场景支持，而应用的其余部分继续通过现有的 UIApplicationDelegate 进行管理。这种方式对于大型应用或者需要逐步验证场景兼容性的团队很有用。然而，分阶段迁移会增加临时复杂性，并且应用在完全迁移之前无法使用多窗口等需要完全基于场景生命周期的功能。

直接迁移意味着一次性将整个应用切换到 UISceneDelegate。对于尚未使用 UIApplicationDelegate 管理界面的新应用，或者那些规模较小、易于整体更新的现有应用，推荐采用这种方式。直接迁移可以更快地启用多窗口等现代功能，并简化代码库。

如何判断应用是否使用了场景？

如果你的应用使用了场景，其 Info.plist 文件中会包含一个 UIApplicationSceneManifest 字典。当系统在 Info.plist 中检测到此字典时，它会使用基于场景的生命周期来启动你的应用。对于直接迁移，你需要添加此清单。对于分阶段迁移，你将在准备好启用场景时添加它。

分阶段迁移

分阶段迁移允许你逐步采用 UISceneDelegate。在这种方法下，应用将继续使用 UIApplicationDelegate 作为主要入口点，但你可以为某些界面逐步引入场景支持。当你想为应用的特定部分启用多窗口等功能，同时保持其他部分的原有行为时，这种方式很有用。

要进行分阶段迁移，你需要：

1. 创建一个实现 UIWindowSceneDelegate 协议的新类。
2. 在 UIApplicationDelegate 中实现 application(_:configurationForConnecting:options:) 方法，为特定会话返回一个 UISceneConfiguration 实例。此配置告诉系统为连接的场景会话使用哪个场景代理类。
3. 在应用的 Info.plist 中配置 UIApplicationSceneManifest 字典，并为场景配置指定你的场景代理类名。

当系统请求新场景时，它会调用 UIApplicationDelegate 的 application(_:configurationForConnecting:options:) 方法。你可以检查连接选项（例如 UIApplication.OpenURLOptions 或 UIApplication.ActivityOptions）来决定返回哪种场景配置。这允许你根据用户的操作（例如点击 URL 或进行拖放操作）来创建不同类型的场景。

分阶段迁移期间，UIApplicationDelegate 仍然负责管理应用级事件（例如应用启动和进入后台），而 UISceneDelegate 则管理特定场景的生命周期事件（例如场景激活或失活）。这种分离使得你可以逐步将界面管理从 UIApplicationDelegate 转移到 UISceneDelegate。

直接迁移

直接迁移涉及一次性将整个应用从 UIApplicationDelegate 迁移到 UISceneDelegate。这种方式适用于新应用，或者那些愿意为启用多窗口等现代功能而进行全面更新的现有应用。

要直接迁移，你需要：

1. 将应用生命周期管理从 UIApplicationDelegate 移动到 UISceneDelegate。这包括将代码从 application(:didFinishLaunchingWithOptions:) 移动到 scene(:willConnectTo:options:)，以及将其他生命周期方法（例如 applicationWillResignActive 和 applicationDidBecomeActive）迁移到对应的场景代理方法（例如 sceneWillResignActive 和 sceneDidBecomeActive）。
2. 移除 UIApplicationDelegate 中与窗口管理相关的代码，因为每个场景现在都会管理自己的 UIWindow。
3. 在 Info.plist 中添加 UIApplicationSceneManifest 字典，并配置默认的场景配置，指定你的 UISceneDelegate 类。

直接迁移后，应用的每个窗口都由一个独立的 UIScene 实例管理，UISceneDelegate 负责该场景的生命周期。这为每个窗口提供了更好的隔离，并启用了多窗口支持。

通用迁移步骤

无论选择分阶段迁移还是直接迁移，都需要遵循一些通用步骤：

1. 创建场景代理类

创建一个实现 UIWindowSceneDelegate 协议的新类。这个类将管理特定场景的生命周期。你可以在其中创建窗口、设置根视图控制器，并响应场景生命周期事件。

2. 配置 Info.plist

在 Info.plist 中添加一个 UIApplicationSceneManifest 字典。此字典告诉系统你的应用支持场景。它包含一个 UISceneConfigurations 字典，你可以在其中定义应用支持的不同场景配置。每个配置指定了场景代理类名和故事板名称（如果使用的话）。

<key>UIApplicationSceneManifest</key> <dict> <key>UIApplicationSupportsMultipleScenes</key> <true/> <key>UISceneConfigurations</key> <dict> <key>UIWindowSceneSessionRoleApplication</key> <array> <dict> <key>UISceneConfigurationName</key> <string>Default Configuration</string> <key>UISceneDelegateClassName</key> <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string> <key>UISceneStoryboardFile</key> <string>Main</string> </dict> </array> </dict> </dict>

3. 更新应用代理

对于直接迁移，移除 UIApplicationDelegate 中与窗口管理相关的代码，并将应用生命周期事件的处理移动到场景代理中。对于分阶段迁移，在 UIApplicationDelegate 中实现 application(_:configurationForConnecting:options:) 方法来返回适当的场景配置。

4. 更新生命周期事件处理

将应用级生命周期事件的处理迁移到相应的场景级事件。例如：

• application(:didFinishLaunchingWithOptions:) 迁移到 scene(:willConnectTo:options:)
• applicationWillResignActive 迁移到 sceneWillResignActive
• applicationDidBecomeActive 迁移到 sceneDidBecomeActive
• 等等...

5. 测试

在支持场景的设备（例如 iPad）上彻底测试你的应用。验证场景是否正确创建、生命周期事件是否正常触发，以及多窗口等功能是否按预期工作。对于分阶段迁移，确保现有功能在启用场景的部分和未启用的部分都能正常工作。

场景与后台任务

当使用基于场景的生命周期时，后台任务的处理方式有所不同。在基于 UIApplicationDelegate 的应用中，后台任务通常在应用级别管理。而在基于场景的应用中，后台任务可以与特定场景关联。

如果你的应用使用 UIApplication.beginBackgroundTask(withName:expirationHandler:) 来管理长时间运行的任务，在迁移到场景后，你可能需要考虑使用每个场景的后台任务管理。然而，UIApplication 级别的后台任务 API 在基于场景的应用中仍然可用，并且可以在应用级别的任务中使用。

对于直接与特定场景关联的任务（例如，该场景正在进行的网络请求），考虑使用与该场景关联的后台任务。这有助于系统更有效地管理资源，并在场景关闭时提供更清晰的任务清理机制。

结论

迁移到基于 UIKit 场景的生命周期可以使你的应用支持多窗口等现代 iOS 功能。无论选择分阶段迁移还是直接迁移，关键步骤都是创建一个 UISceneDelegate 类，配置 Info.plist，并将生命周期事件处理从 UIApplicationDelegate 移动到 UISceneDelegate。迁移后，每个窗口将由独立的场景管理，从而提高模块化并为用户提供更强大的多任务处理体验。

背景

看似一个平平无奇的周末，却让做AI Video Generator的开发者天塌了。

好消息：竞品家的都嘎了！

坏消息：自己家的也嘎了！

此次以Video关键词检索，共计21款相关产品。有单纯上架海外市场，也有全体地区分发。

所以集中下架的行为，不只是单纯的某些国家或地区。大概率是集中触发了苹果的查杀。（法国佬口音：我要验牌！）

随机验牌

在众多被标记了下架的产品中，随机抽选了2家APP。单纯从应用市场的截图入手。

从AppStore市场图，就能明显发现存在社交风格的市场截图，充斥着袒胸露乳的行为。基本上都带勾！

基本上随机抽查的产品中或多或少都存在此类问题。从应用截图就充斥着擦边行为！，莫非是社交类大佬集体转型？

下架原因

为了更好的解释这种集中下架行为，特意在Developer审核指南，匹配对应内容审核的条款。

不出意外 1.1.4 - 公然宣传黄色或色情内容的材料 (这一概念的定义是：“对性器官或性活动的露骨描述或展示，目的在于刺激性快感，而非带来美学价值或触发情感”)，其中包括一夜情约会 App 和其他可能包含色情内容或用于嫖娼或人口贩卖和剥削的 App。

当然，这种集中行为大概率苹果算法升级【或者通过鉴黄系统】，从AppStore净化入手，简单纯粹的一刀切！

遵守规则，方得长治久安，最后祝大家大吉大利，今晚过审！

附：更多文章欢迎关注同名公众号，By-iOS研究院。

Branch instructions on most architectures use PC-relative addressingwith a limited range. When the target is too far away, the branchbecomes "out of range" and requires special handling.

Consider a large binary where main() at address 0x10000calls foo() at address 0x8010000-over 128MiB away. OnAArch64, the bl instruction can only reach ±128MiB, so thiscall cannot be encoded directly. Without proper handling, the linkerwould fail with an error like "relocation out of range." The toolchainmust handle this transparently to produce correct executables.

This article explores how compilers, assemblers, and linkers worktogether to solve the long branch problem.

• Compiler (IR to assembly): Handles branches within a function thatexceed the range of conditional branch instructions
• Assembler (assembly to relocatable file): Handles branches within asection where the distance is known at assembly time
• Linker: Handles cross-section and cross-object branches discoveredduring final layout

Branch range limitations

Different architectures have different branch range limitations.Here's a quick comparison of unconditional / conditional branchranges:

The following subsections provide detailed per-architectureinformation, including relocation types relevant for linkerimplementation.

AArch32

In A32 state:

• Branch (b/b<cond>), conditionalbranch and link (bl<cond>)(R_ARM_JUMP24): ±32MiB
• Unconditional branch and link (bl/blx,R_ARM_CALL): ±32MiB

Note: R_ARM_CALL is for unconditionalbl/blx which can be relaxed to BLX inline;R_ARM_JUMP24 is for branches which require a veneer forinterworking.

In T32 state (Thumb state pre-ARMv8):

• Conditional branch (b<cond>,R_ARM_THM_JUMP8): ±256 bytes
• Short unconditional branch (b,R_ARM_THM_JUMP11): ±2KiB
• ARMv5T branch and link (bl/blx,R_ARM_THM_CALL): ±4MiB
• ARMv6T2 wide conditional branch (b<cond>.w,R_ARM_THM_JUMP19): ±1MiB
• ARMv6T2 wide branch (b.w,R_ARM_THM_JUMP24): ±16MiB
• ARMv6T2 wide branch and link (bl/blx,R_ARM_THM_CALL): ±16MiB. R_ARM_THM_CALL can berelaxed to BLX.

AArch64

• Test bit and branch (tbz/tbnz,R_AARCH64_TSTBR14): ±32KiB
• Compare and branch (cbz/cbnz,R_AARCH64_CONDBR19): ±1MiB
• Conditional branches (b.<cond>,R_AARCH64_CONDBR19): ±1MiB
• Unconditional branches (b/bl,R_AARCH64_JUMP26/R_AARCH64_CALL26):±128MiB

The compiler's BranchRelaxation pass handlesout-of-range conditional branches by inverting the condition andinserting an unconditional branch. The AArch64 assembler does notperform branch relaxation; out-of-range branches produce linker errorsif not handled by the compiler.

LoongArch

• Conditional branches(beq/bne/blt/bge/bltu/bgeu,R_LARCH_B16): ±128KiB (18-bit signed)
• Compare-to-zero branches (beqz/bnez,R_LARCH_B21): ±4MiB (23-bit signed)
• Unconditional branch/call (b/bl,R_LARCH_B26): ±128MiB (28-bit signed)
• Medium range call (pcaddu12i+jirl,R_LARCH_CALL30): ±2GiB
• Long range call (pcaddu18i+jirl,R_LARCH_CALL36): ±128GiB

M68k

• Short branch(Bcc.B/BRA.B/BSR.B): ±128 bytes(8-bit displacement)
• Word branch(Bcc.W/BRA.W/BSR.W): ±32KiB(16-bit displacement)
• Long branch(Bcc.L/BRA.L/BSR.L, 68020+):±2GiB (32-bit displacement)

GNU Assembler provides pseudoopcodes (jbsr, jra, jXX) that"automatically expand to the shortest instruction capable of reachingthe target". For example, jeq .L0 emits one ofbeq.b, beq.w, and beq.l dependingon the displacement.

With the long forms available on 68020 and later, M68k doesn't needlinker range extension thunks.

MIPS

• Conditional branches(beq/bne/bgez/bltz/etc,R_MIPS_PC16): ±128KiB
• PC-relative jump (b offset(bgez $zero, offset)): ±128KiB
• PC-relative call (bal offset(bgezal $zero, offset)): ±128KiB
• Pseudo-absolute jump/call (j/jal,R_MIPS_26): branch within the current 256MiB region, onlysuitable for -fno-pic code. Deprecated in R6 in favor ofbc/balc

16-bit instructions removed in Release 6:

• Conditional branch (beqz16,R_MICROMIPS_PC7_S1): ±128 bytes
• Unconditional branch (b16,R_MICROMIPS_PC10_S1): ±1KiB

MIPS Release 6:

• Unconditional branch, compact (bc16, unclear toolchainimplementation): ±1KiB
• Compare and branch, compact(beqc/bnec/bltc/bgec/etc,R_MIPS_PC16): ±128KiB
• Compare register to zero and branch, compact(beqzc/bnezc/etc,R_MIPS_PC21_S2): ±4MiB
• Branch (and link), compact (bc/balc,R_MIPS_PC26_S2): ±128MiB

LLVM's MipsBranchExpansion pass handles out-of-rangebranches.

lld implements LA25 thunks for MIPS PIC/non-PIC interoperability, butnot range extension thunks.

GCC's mips port ported added-mlong-calls in 1993-03.

PowerPC

• Conditional branch (bc/bcl,R_PPC64_REL14): ±32KiB
• Unconditional branch (b/bl,R_PPC64_REL24/R_PPC64_REL24_NOTOC):±32MiB

GCC-generated code relies on linker thunks. However, the legacy-mlongcall can be used to generate long code sequences.

RISC-V

• Compressed c.beqz: ±256 bytes
• Compressed c.jal: ±2KiB
• jalr (I-type immediate): ±2KiB
• Conditional branches(beq/bne/blt/bge/bltu/bgeu,B-type immediate): ±4KiB
• jal (J-type immediate, PseudoBR): ±1MiB(notably smaller than other RISC architectures: AArch64 ±128MiB,PowerPC64 ±32MiB, LoongArch ±128MiB)
• PseudoJump (using auipc +jalr): ±2GiB
• beqi/bnei (Zibi extension, 5-bit compareimmediate (1 to 31 and -1)): ±4KiB

Qualcomm uC Branch Immediate extension (Xqcibi):

• qc.beqi/qc.bnei/qc.blti/qc.bgei/qc.bltui/qc.bgeui(32-bit, 5-bit compare immediate): ±4KiB
• qc.e.beqi/qc.e.bnei/qc.e.blti/qc.e.bgei/qc.e.bltui/qc.e.bgeui(48-bit, 16-bit compare immediate): ±4KiB

Qualcomm uC Long Branch extension (Xqcilb):

• qc.e.j/qc.e.jal (48-bit,R_RISCV_VENDOR(QUALCOMM)+R_RISCV_QC_E_CALL_PLT): ±2GiB

For function calls:

• The Gocompiler emits a single jal for calls and relies on itslinker to generate trampolines when the target is out of range.
• In contrast, GCC and Clang emit auipc+jalrand rely on linker relaxation to shrink the sequence when possible.

The jal range (±1MiB) is notably smaller than other RISCarchitectures (AArch64 ±128MiB, PowerPC64 ±32MiB, LoongArch ±128MiB).This limits the effectiveness of linker relaxation ("start large andshrink"), and leads to frequent trampolines when the compileroptimistically emits jal ("start small and grow").

SPARC

• Compare and branch (cxbe, R_SPARC_5): ±64bytes
• Conditional branch (bcc, R_SPARC_WDISP19):±1MiB
• Unconditional branch (b, R_SPARC_WDISP22):±8MiB
• call(R_SPARC_WDISP30/R_SPARC_WPLT30): ±2GiB

With ±2GiB range for call, SPARC doesn't need rangeextension thunks in practice.

SuperH

SuperH uses fixed-width 16-bit instructions, which limits branchranges.

• Conditional branch (bf/bt): ±256 bytes(8-bit displacement)
• Unconditional branch (bra): ±4KiB (12-bitdisplacement)
• Branch to subroutine (bsr): ±4KiB (12-bitdisplacement)

For longer distances, register-indirect branches(braf/bsrf) are used. The compiler invertsconditions and emits these when targets exceed the short ranges.

SuperH is supported by GCC and binutils, but not by LLVM.

Xtensa

Xtensa uses variable-length instructions: 16-bit (narrow,.n suffix) and 24-bit (standard).

• Narrow conditional branch (beqz.n/bnez.n,16-bit): -28 to +35 bytes (6-bit signed + 4)
• Conditional branch (compare two registers)(beq/bne/blt/bge/etc,24-bit): ±256 bytes
• Conditional branch (compare with zero)(beqz/bnez/bltz/bgez,24-bit): ±2KiB
• Unconditional jump (j, 24-bit): ±128KiB
• Call(call0/call4/call8/call12,24-bit): ±512KiB

The assembler performs branch relaxation: when a conditional branchtarget is too far, it inverts the condition and inserts a jinstruction.

Per https://www.sourceware.org/binutils/docs/as/Xtensa-Call-Relaxation.html,for calls, GNU Assembler pessimistically generates indirect sequences(l32r+callx8) when the target distance isunknown. GNU ld then performs linker relaxation.

x86-64

• Short conditional jump (Jcc rel8): -128 to +127bytes
• Short unconditional jump (JMP rel8): -128 to +127bytes
• Near conditional jump (Jcc rel32): ±2GiB
• Near unconditional jump (JMP rel32): ±2GiB

With a ±2GiB range for near jumps, x86-64 rarely encountersout-of-range branches in practice. That said, Google and Meta Platformsdeploy mostly statically linked executables on x86-64 production serversand have run into the huge executable problem for certainconfigurations.

z/Architecture

• Short conditional branch (BRC,R_390_PC16DBL): ±64KiB (16-bit halfword displacement)
• Long conditional branch (BRCL,R_390_PC32DBL): ±4GiB (32-bit halfword displacement)
• Short call (BRAS, R_390_PC16DBL):±64KiB
• Long call (BRASL, R_390_PC32DBL):±4GiB

With ±4GiB range for long forms, z/Architecture doesn't need linkerrange extension thunks. LLVM's SystemZLongBranch passrelaxes short branches (BRC/BRAS) to longforms (BRCL/BRASL) when targets are out ofrange.

Compiler: branch rangehandling

Conditional branch instructions usually have shorter ranges thanunconditional ones, making them less suitable for linker thunks (as wewill explore later). Compilers typically keep conditional branch targetswithin the same section, allowing the compiler to handle out-of-rangecases via branch relaxation.

Within a function, conditional branches may still go out of range.The compiler measures branch distances and relaxes out-of-range branchesby inverting the condition and inserting an unconditional branch:

1
2
3
4
5
6
7

# Before relaxation (out of range)
beq .Lfar_target       # ±4KiB range on RISC-V

# After relaxation
bne .Lskip             # Inverted condition, short range
j .Lfar_target         # Unconditional jump, ±1MiB range
.Lskip:

Some architectures have conditional branch instructions that comparewith an immediate, with even shorter ranges due to encoding additionalimmediates. For example, AArch64's cbz/cbnz(compare and branch if zero/non-zero) andtbz/tbnz (test bit and branch) have only±32KiB range. RISC-V Zibi beqi/bnei have ±4KiBrange. The compiler handles these in a similar way:

1
2
3
4
5
6
7

// Before relaxation (cbz has ±32KiB range)
  cbz w0, far

// After relaxation
  cbnz w0, .Lskip       // Inverted condition
  b far                 // Unconditional branch, ±128MiB range
.Lskip:

An Intel employee contributed https://reviews.llvm.org/D41634 (in 2017) when inversionof a branch condintion is impossible. This is for an out-of-treebackend. As of Jan 2026 there is no in-tree test for this code path.

In LLVM, this is handled by the BranchRelaxation pass,which runs just before AsmPrinter. Different backends havetheir own implementations:

• BranchRelaxation: AArch64, AMDGPU, AVR, RISC-V
• HexagonBranchRelaxation: Hexagon
• PPCBranchSelector: PowerPC
• SystemZLongBranch: SystemZ
• MipsBranchExpansion: MIPS
• MSP430BSel: MSP430

The generic BranchRelaxation pass computes block sizesand offsets, then iterates until all branches are in range. Forconditional branches, it tries to invert the condition and insert anunconditional branch. For unconditional branches that are still out ofrange, it calls TargetInstrInfo::insertIndirectBranch toemit an indirect jump sequence (e.g.,adrp+add+br on AArch64) or a longjump sequence (e.g., pseudo jump on RISC-V).

Note: The size estimates may be inaccurate due to inline assembly.LLVM uses heuristics to estimate inline assembly sizes, but for certainassembly constructs the size is not precisely known at compile time.

Unconditional branches and calls can target different sections sincethey have larger ranges. If the target is out of reach, the linker caninsert thunks to extend the range.

For x86-64, the large code model uses multiple instructions for callsand jumps to support text sections larger than 2GiB (see Relocationoverflow and code models: x86-64 large code model). This is apessimization if the callee ends up being within reach. Google and MetaPlatforms have interest in allowing range extension thunks as areplacement for the multiple instructions.

Assembler: instructionrelaxation

The assembler converts assembly to machine code. When the target of abranch is within the same section and the distance is known at assemblytime, the assembler can select the appropriate encoding. This isdistinct from linker thunks, which handle cross-section or cross-objectreferences where distances aren't known until link time.

Assembler instruction relaxation handles two cases (see Clang-O0 output: branch displacement and size increase for examples):

• Span-dependent instructions: Select an appropriateencoding based on displacement.
  • On x86, a short jump (jmp rel8) can be relaxed to anear jump (jmp rel32) when the target is far.
  • On RISC-V, beqz may be assembled to the 2-bytec.beqz when the displacement fits within ±256 bytes.
• Conditional branch transform: Invert the conditionand insert an unconditional branch. On RISC-V, a blt mightbe relaxed to bge plus an unconditional branch.

The assembler uses an iterative layout algorithm that alternatesbetween fragment offset assignment and relaxation until all fragmentsbecome legalized. See Integratedassembler improvements in LLVM 19 for implementation details.

Linker: range extensionthunks

When the linker resolves relocations, it may discover that a branchtarget is out of range. At this point, the instruction encoding isfixed, so the linker cannot simply change the instruction. Instead, itgenerates range extension thunks (also called veneers,branch stubs, or trampolines).

A thunk is a small piece of linker-generated code that can reach theactual target using a longer sequence of instructions. The originalbranch is redirected to the thunk, which then jumps to the realdestination.

Range extension thunks are one type of linker-generated thunk. Othertypes include:

• ARM interworking veneers: Switch between ARM andThumb instruction sets (see Linker notes onAArch32)
• MIPS LA25 thunks: Enable PIC and non-PIC codeinteroperability (see Toolchain notes onMIPS)
• PowerPC64 TOC/NOTOC thunks: Handle calls betweenfunctions using different TOC pointer conventions (see Linker notes on PowerISA)

Short range vs long rangethunks

A short range thunk (see lld/ELF's AArch64implementation) contains just a single branch instruction. Since ituses a branch, its reach is also limited by the branch range—it can onlyextend coverage by one branch distance. For targets further away,multiple short range thunks can be chained, or a long range thunk withaddress computation must be used.

Long range thunks use indirection and can jump to (practically)arbitrary locations.

1
2
3
4
5
6
7
8
9

// Short range thunk: single branch, 4 bytes
__AArch64AbsLongThunk_dst:
  b dst                         // ±128MiB range

// Long range thunk: address computation, 12 bytes
__AArch64ADRPThunk_dst:
  adrp x16, dst                 // Load page address (±4GiB range)
  add x16, x16, :lo12:dst       // Add page offset
  br x16                        // Indirect branch

Thunk examples

AArch32 (PIC) (see Linker notes onAArch32):

1
2
3
4
5

__ARMV7PILongThunk_dst:
  movw ip, :lower16:(dst - .)   ; ip = intra-procedure-call scratch register
  movt ip, :upper16:(dst - .)
  add ip, ip, pc
  bx ip

PowerPC64 ELFv2 (see Linker notes on PowerISA):

1
2
3
4
5

__long_branch_dst:
  addis 12, 2, .branch_lt@ha    # Load high bits from branch lookup table
  ld 12, .branch_lt@l(12)       # Load target address
  mtctr 12                      # Move to count register
  bctr                          # Branch to count register

Thunk impact ondebugging and profiling

Thunks are transparent at the source level but visible in low-leveltools:

• Stack traces: May show thunk symbols (e.g.,__AArch64ADRPThunk_foo) between caller and callee
• Profilers: Samples may attribute time to thunkcode; some profilers aggregate thunk time with the target function
• Disassembly: objdump orllvm-objdump will show thunk sections interspersed withregular code
• Code size: Each thunk adds bytes; large binariesmay have thousands of thunks

lld/ELF's thunk creationalgorithm

lld/ELF uses a multi-pass algorithm infinalizeAddressDependentContent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

assignAddresses();
for (pass = 0; pass < 30; ++pass) {
  if (pass == 0)
    createInitialThunkSections();  // pre-create empty ThunkSections
  bool changed = false;
  for (relocation : all_relocations) {
    if (pass > 0 && normalizeExistingThunk(rel))
      continue;  // existing thunk still in range
    if (!needsThunk(rel)) continue;
    Thunk *t = getOrCreateThunk(rel);
    ts = findOrCreateThunkSection(rel, src);
    ts->addThunk(t);
    rel.sym = t->getThunkTargetSym();  // redirect
    changed = true;
  }
  mergeThunks();  // insert ThunkSections into output
  if (!changed) break;
  assignAddresses();  // recalculate with new thunks
}

Key details:

• Multi-pass: Iterates until convergence (max 30passes). Adding thunks changes addresses, potentially puttingpreviously-in-range calls out of range.
• Pre-allocated ThunkSections: On pass 0,createInitialThunkSections places emptyThunkSections at regular intervals(thunkSectionSpacing). For AArch64: 128 MiB - 0x30000 ≈127.8 MiB.
• Thunk reuse: getThunk returns existingthunk if one exists for the same target;normalizeExistingThunk checks if a previously-created thunkis still in range.
• ThunkSection placement: getISDThunkSecfinds a ThunkSection within branch range of the call site, or createsone adjacent to the calling InputSection.

lld/MachO's thunk creationalgorithm

lld/MachO uses a single-pass algorithm inTextOutputSection::finalize:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

for (callIdx = 0; callIdx < inputs.size(); ++callIdx) {
  // Finalize sections within forward branch range (minus slop)
  while (finalIdx < endIdx && fits_in_range(inputs[finalIdx]))
    finalizeOne(inputs[finalIdx++]);

  // Process branch relocations in this section
  for (Relocation &r : reverse(isec->relocs)) {
    if (!isBranchReloc(r)) continue;
    if (targetInRange(r)) continue;
    if (existingThunkInRange(r)) { reuse it; continue; }
    // Create new thunk and finalize it
    createThunk(r);
  }
}

Key differences from lld/ELF:

• Single pass: Addresses are assigned monotonicallyand never revisited
• Slop reservation: ReservesslopScale * thunkSize bytes (default: 256 × 12 = 3072 byteson ARM64) to leave room for future thunks
• Thunk naming:<function>.thunk.<sequence> where sequenceincrements per target

Thunkstarvation problem: If many consecutive branches need thunks, eachthunk (12 bytes) consumes slop faster than call sites (4 bytes apart)advance. The test lld/test/MachO/arm64-thunk-starvation.sdemonstrates this edge case. Mitigation is increasing--slop-scale, but pathological cases with hundreds ofconsecutive out-of-range callees can still fail.

mold's thunk creationalgorithm

mold uses a two-pass approach:

• Pessimistically over-allocate thunks. Out-of-section relocations andrelocations referencing to a section not assigned address yetpessimistically need thunks.(requires_thunk(ctx, isec, rel, first_pass) whenfirst_pass=true)
• Then remove unnecessary ones.

Linker pass ordering:

• compute_section_sizes() callscreate_range_extension_thunks() — final section addressesare NOT yet known
• set_osec_offsets() assigns section addresses
• remove_redundant_thunks() is called AFTER addresses areknown — check unneeded thunks due to out-of-section relocations
• Rerun set_osec_offsets()

Pass 1 (create_range_extension_thunks):Process sections in batches using a sliding window. The window tracksfour positions:

1
2
3
4
5
6
7
8
9

Sections:   [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] ...
             ^       ^       ^           ^
             A       B       C           D
             |       |_______|           |
             |         batch             |
             |                           |
             earliest                    thunk
             reachable                   placement
             from C

• [B, C) = current batch of sections to process (size≤ branch_distance/5)
• A = earliest section still reachable from C (forthunk expiration)
• D = where to place the thunk (furthest pointreachable from B)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Simplified from OutputSection<E>::create_range_extension_thunks
while (b < sections.size()) {
  // Advance D: find furthest point where thunk is reachable from B
  while (d < size && thunk_at_d_reachable_from_b)
    assign_address(sections[d++]);

  // Compute batch [B, C)
  c = b + 1;
  while (c < d && sections[c] < sections[b] + batch_size) c++;

  // Advance A: expire thunks no longer reachable
  while (a < b && sections[a] + branch_distance < sections[c]) a++;
  // Expire thunk groups before A: clear symbol flags.
  for (; t < thunks.size() && thunks[t].offset < sections[a]; t++)
    for (sym in thunks[t].symbols) sym->flags = 0;

  // Scan [B,C) relocations. If a symbol is not assigned to a thunk group yet,
  // assign it to the new thunk group at D.
  auto &thunk = thunks.emplace_back(new Thunk(offset));
  parallel_for(b, c, [&](i64 i) {
    for (rel in sections[i].relocs) {
      if (requires_thunk(rel)) {
        Symbol &sym = rel.symbol;
        if (!sym.flags.test_and_set()) {  // atomic: skip if already set
          lock_guard lock(mu);
          thunk.symbols.push_back(&sym);
        }
      }
    }
  });
  offset += thunk.size();
  b = c;  // Move to next batch
}

Pass 2 (remove_redundant_thunks): Afterfinal addresses are known, remove thunk entries for symbols actually inrange.

Key characteristics:

• Pessimistic over-allocation: Assumes allout-of-section calls need thunks; safe to shrink later
• Batch size: branch_distance/5 (25.6 MiB forAArch64, 3.2 MiB for AArch32)
• Parallelism: Uses TBB for parallel relocationscanning within each batch
• Single branch range: Uses one conservativebranch_distance per architecture. For AArch32, uses ±16 MiB(Thumb limit) for all branches, whereas lld/ELF uses ±32 MiB for A32branches.
• Thunk size not accounted in D-advancement: Theactual thunk group size is unknown when advancing D, so the end of alarge thunk group may be unreachable from the beginning of thebatch.
• No convergence loop: Single forward pass foraddress assignment, no risk of non-convergence

GNU ld's thunk creationalgorithm

Each port implements the algorithm on their own. There is no codesharing.

GNU ld's AArch64 port (bfd/elfnn-aarch64.c) uses aniterative algorithm but with a single stub type and no lookup table.

Main iteration loop(elfNN_aarch64_size_stubs()):

1
2
3
4
5
6
7
8
9
10
11

group_sections(htab, stub_group_size, ...);  // Default: 127 MiB
layout_sections_again();

for (;;) {
  stub_changed = false;
  _bfd_aarch64_add_call_stub_entries(&stub_changed, ...);
  if (!stub_changed)
    return true;
  _bfd_aarch64_resize_stubs(htab);
  layout_sections_again();
}

GNU ld's ppc64 port (bfd/elf64-ppc.c) uses an iterativemulti-pass algorithm with a branch lookup table(.branch_lt) for long-range stubs.

Section grouping: Sections are grouped bystub_group_size (~28-30 MiB default); each group gets onestub section. For 14-bit conditional branches(R_PPC64_REL14, ±32KiB range), group size is reduced by1024x.

Main iteration loop(ppc64_elf_size_stubs()):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

while (1) {
  // Scan all relocations in all input sections
  for (input_bfd; section; irela) {
    // Only process branch relocations (R_PPC64_REL24, R_PPC64_REL14, etc.)
    stub_type = ppc_type_of_stub(section, irela, ...);
    if (stub_type == ppc_stub_none)
      continue;
    // Create or merge stub entry
    stub_entry = ppc_add_stub(...);
  }

  // Size all stubs, potentially upgrading long_branch to plt_branch
  bfd_hash_traverse(&stub_hash_table, ppc_size_one_stub, ...);

  // Check for convergence
  if (!stub_changed && all_sizes_stable)
    break;

  // Re-layout sections
  layout_sections_again();
}

Convergence control:

• STUB_SHRINK_ITER = 20 (PR28827): After 20 iterations,stub sections only grow (prevents oscillation)
• Convergence when:!stub_changed && all section sizes stable

Stub type upgrade: ppc_type_of_stub()initially returns ppc_stub_long_branch for out-of-rangebranches. Later, ppc_size_one_stub() checks if the stub'sbranch can reach; if not, it upgrades toppc_stub_plt_branch and allocates an 8-byte entry in.branch_lt.

Comparing linker thunkalgorithms

Linker relaxation

Some architectures take a different approach: instead of onlyexpanding branches, the linker can also shrinkinstruction sequences when the target is close enough. RISC-V andLoongArch both use this technique. See Thedark side of RISC-V linker relaxation for a deeper dive into thecomplexities and tradeoffs.

Consider a function call using the callpseudo-instruction, which expands to auipc +jalr:

1
2
3
4
5

# Before linking (8 bytes)
call ext
# Expands to:
#   auipc ra, %pcrel_hi(ext)
#   jalr ra, ra, %pcrel_lo(ext)

If ext is within ±1MiB, the linker can relax this to:

1
2

# After relaxation (4 bytes)
jal ext

This is enabled by R_RISCV_RELAX relocations thataccompany R_RISCV_CALL relocations. TheR_RISCV_RELAX relocation signals to the linker that thisinstruction sequence is a candidate for shrinking.

Example object code before linking:

1
2
3
4
5
6
7
8
9

0000000000000006 <foo>:
       6: 97 00 00 00   auipc   ra, 0
                R_RISCV_CALL ext
                R_RISCV_RELAX *ABS*
       a: e7 80 00 00   jalr    ra
       e: 97 00 00 00   auipc   ra, 0
                R_RISCV_CALL ext
                R_RISCV_RELAX *ABS*
      12: e7 80 00 00   jalr    ra

After linking with relaxation enabled, the 8-byteauipc+jalr pairs become 4-bytejal instructions:

1
2
3
4
5
6

0000000000000244 <foo>:
     244: 41 11         addi    sp, sp, -16
     246: 06 e4         sd      ra, 8(sp)
     248: ef 00 80 01   jal     ext
     24c: ef 00 40 01   jal     ext
     250: ef 00 00 01   jal     ext

When the linker deletes instructions, it must also adjust:

• Subsequent instruction offsets within the section
• Symbol addresses
• Other relocations that reference affected locations
• Alignment directives (R_RISCV_ALIGN)

This makes RISC-V linker relaxation more complex than thunkinsertion, but it provides code size benefits that other architecturescannot achieve at link time.

LoongArch uses a similar approach. Apcaddu12i+jirl sequence(R_LARCH_CALL36, ±128GiB range) can be relaxed to a singlebl instruction (R_LARCH_B26, ±128MiB range)when the target is close enough.

Diagnosing out-of-rangeerrors

When you encounter a "relocation out of range" error, check thelinker diagnostic and locate the relocatable file and function.Determine how the function call is lowered in assembly.

Summary

Handling long branches requires coordination across thetoolchain:

The linker's thunk generation is particularly important for largeprograms where function calls may exceed branch ranges. Differentlinkers use different algorithms with various tradeoffs betweencomplexity, optimality, and robustness.

Linker relaxation approaches adopted by RISC-V and LoongArch is analternative that avoids range extension thunks but introduces othercomplexities.

Related

• Relocationoverflow and code models
• Linker notes onAArch32
• Linker notes onAArch64
• Linker notes onPower ISA
• Linker notes onx86
• Toolchain noteson MIPS
• Toolchainnotes on z/Architecture

Branch instructions on most architectures use PC-relative addressingwith a limited range. When the target is too far away, the branchbecomes "out of range" and requires special handling.

Consider a large binary where main() at address 0x10000calls foo() at address 0x8010000-over 128MiB away. OnAArch64, the bl instruction can only reach ±128MiB, so thiscall cannot be encoded directly. Without proper handling, the linkerwould fail with an error like "relocation out of range." The toolchainmust handle this transparently to produce correct executables.

This article explores how compilers, assemblers, and linkers worktogether to solve the long branch problem.

• Compiler (IR to assembly): Handles branches within a function thatexceed the range of conditional branch instructions
• Assembler (assembly to relocatable file): Handles branches within asection where the distance is known at assembly time
• Linker: Handles cross-section and cross-object branches discoveredduring final layout

Branch range limitations

Different architectures have different branch range limitations.Here's a quick comparison of unconditional branch/call ranges:

The following subsections provide detailed per-architectureinformation, including relocation types relevant for linkerimplementation.

AArch32

In A32 state:

• Branch (b/b<cond>), conditionalbranch and link (bl<cond>)(R_ARM_JUMP24): ±32MiB
• Unconditional branch and link (bl/blx,R_ARM_CALL): ±32MiB

Note: R_ARM_CALL is for unconditionalbl/blx which can be relaxed to BLX inline;R_ARM_JUMP24 is for branches which require a veneer forinterworking.

In T32 state:

• Conditional branch (b<cond>,R_ARM_THM_JUMP8): ±256 bytes
• Short unconditional branch (b,R_ARM_THM_JUMP11): ±2KiB
• ARMv5T branch and link (bl/blx,R_ARM_THM_CALL): ±4MiB
• ARMv6T2 wide conditional branch (b<cond>.w,R_ARM_THM_JUMP19): ±1MiB
• ARMv6T2 wide branch (b.w,R_ARM_THM_JUMP24): ±16MiB
• ARMv6T2 wide branch and link (bl/blx,R_ARM_THM_CALL): ±16MiB. R_ARM_THM_CALL can berelaxed to BLX.

AArch64

• Test and compare branches(tbnz/tbz/cbnz/cbz):±32KiB
• Conditional branches (b.<cond>): ±1MiB
• Unconditional branches (b/bl):±128MiB

PowerPC

• Conditional branch (bc/bcl,R_PPC64_REL14): ±32KiB
• Unconditional branch (b/bl,R_PPC64_REL24/R_PPC64_REL24_NOTOC):±32MiB

RISC-V

• Compressed c.beqz: ±256 bytes
• Compressed c.jal: ±2KiB
• jalr (I-type immediate): ±2KiB
• Conditional branches(beq/bne/blt/bge/bltu/bgeu,B-type immediate): ±4KiB
• jal (J-type immediate, PseudoBR):±1MiB
• PseudoJump (using auipc +jalr): ±2GiB

Qualcomm uC Branch Immediate extension (Xqcibi):

• qc.beqi/qc.bnei/qc.blti/qc.bgei/qc.bltui/qc.bgeui(32-bit, 5-bit compare immediate): ±4KiB
• qc.e.beqi/qc.e.bnei/qc.e.blti/qc.e.bgei/qc.e.bltui/qc.e.bgeui(48-bit, 16-bit compare immediate): ±4KiB

Qualcomm uC Long Branch extension (Xqcilb):

• qc.e.j/qc.e.jal (48-bit,R_RISCV_VENDOR(QUALCOMM)+R_RISCV_QC_E_CALL_PLT): ±2GiB

SPARC

• Compare and branch (cxbe, R_SPARC_5): ±64bytes
• Conditional branches (bcc,R_SPARC_WDISP19): ±1MiB
• call (R_SPARC_WDISP30): ±2GiB

Note: lld does not implement range extension thunks for SPARC.

x86-64

• Short conditional jump (Jcc rel8): -128 to +127bytes
• Short unconditional jump (JMP rel8): -128 to +127bytes
• Near conditional jump (Jcc rel32): ±2GiB
• Near unconditional jump (JMP rel32): ±2GiB

With a ±2GiB range for near jumps, x86-64 rarely encountersout-of-range branches in practice. A single text section would need toexceed 2GiB before thunks become necessary. For this reason, mostlinkers (including lld) do not implement range extension thunks forx86-64.

Compiler: branch relaxation

The compiler typically generates branches using a form with a largerange. However, certain conditional branches may still go out of rangewithin a function.

The compiler measures branch distances and relaxes out-of-rangebranches. In LLVM, this is handled by the BranchRelaxationpass, which runs just before AsmPrinter.

Different backends have their own implementations:

• BranchRelaxation: AArch64, AMDGPU, AVR, RISC-V
• HexagonBranchRelaxation: Hexagon
• PPCBranchSelector: PowerPC
• SystemZLongBranch: SystemZ
• MipsBranchExpansion: MIPS
• MSP430BSel: MSP430

For a conditional branch that is out of range, the pass typicallyinverts the condition and inserts an unconditional branch:

1
2
3
4
5
6
7

# Before relaxation (out of range)
beq .Lfar_target       # ±4KiB range on RISC-V

# After relaxation
bne .Lskip             # Inverted condition, short range
j .Lfar_target         # Unconditional jump, ±1MiB range
.Lskip:

Assembler: instructionrelaxation

The assembler converts assembly to machine code. When the target of abranch is within the same section and the distance is known at assemblytime, the assembler can select the appropriate encoding. This isdistinct from linker thunks, which handle cross-section or cross-objectreferences where distances aren't known until link time.

Assembler instruction relaxation handles two cases (see Clang-O0 output: branch displacement and size increase for examples):

• Span-dependent instructions: Select a largerencoding when the displacement exceeds the range of the smallerencoding. For x86, a short jump (jmp rel8) can be relaxedto a near jump (jmp rel32).
• Conditional branch transform: Invert the conditionand insert an unconditional branch. On RISC-V, a blt mightbe relaxed to bge plus an unconditional branch.

The assembler uses an iterative layout algorithm that alternatesbetween fragment offset assignment and relaxation until all fragmentsbecome legalized. See Integratedassembler improvements in LLVM 19 for implementation details.

Linker: range extensionthunks

When the linker resolves relocations, it may discover that a branchtarget is out of range. At this point, the instruction encoding isfixed, so the linker cannot simply change the instruction. Instead, itgenerates range extension thunks (also called veneers,branch stubs, or trampolines).

A thunk is a small piece of linker-generated code that can reach theactual target using a longer sequence of instructions. The originalbranch is redirected to the thunk, which then jumps to the realdestination.

Range extension thunks are one type of linker-generated thunk. Othertypes include:

• ARM interworking veneers: Switch between ARM andThumb instruction sets (see Linker notes onAArch32)
• MIPS LA25 thunks: Enable PIC and non-PIC codeinteroperability (see Toolchain notes onMIPS)
• PowerPC64 TOC/NOTOC thunks: Handle calls betweenfunctions using different TOC pointer conventions (see Linker notes on PowerISA)

Short range vs long rangethunks

A short range thunk (see lld/ELF's AArch64implementation) contains just a single branch instruction. Since ituses a branch, its reach is also limited by the branch range—it can onlyextend coverage by one branch distance. For targets further away,multiple short range thunks can be chained, or a long range thunk withaddress computation must be used.

Long range thunks use indirection and can jump to (practically)arbitrary locations.

1
2
3
4
5
6
7
8
9

// Short range thunk: single branch, 4 bytes
__AArch64AbsLongThunk_dst:
  b dst                         // ±128MiB range

// Long range thunk: address computation, 12 bytes
__AArch64ADRPThunk_dst:
  adrp x16, dst                 // Load page address (±4GiB range)
  add x16, x16, :lo12:dst       // Add page offset
  br x16                        // Indirect branch

Thunk examples

AArch32 (PIC) (see Linker notes onAArch32):

1
2
3
4
5

__ARMV7PILongThunk_dst:
  movw ip, :lower16:(dst - .)   ; ip = intra-procedure-call scratch register
  movt ip, :upper16:(dst - .)
  add ip, ip, pc
  bx ip

PowerPC64 ELFv2 (see Linker notes on PowerISA):

1
2
3
4
5

__long_branch_dst:
  addis 12, 2, .branch_lt@ha    # Load high bits from branch lookup table
  ld 12, .branch_lt@l(12)       # Load target address
  mtctr 12                      # Move to count register
  bctr                          # Branch to count register

Thunk impact ondebugging and profiling

Thunks are transparent at the source level but visible in low-leveltools:

• Stack traces: May show thunk symbols (e.g.,__AArch64ADRPThunk_foo) between caller and callee
• Profilers: Samples may attribute time to thunkcode; some profilers aggregate thunk time with the target function
• Disassembly: objdump orllvm-objdump will show thunk sections interspersed withregular code
• Code size: Each thunk adds bytes; large binariesmay have thousands of thunks

lld/ELF's thunk creationalgorithm

lld/ELF uses a multi-pass algorithm infinalizeAddressDependentContent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

assignAddresses();
for (pass = 0; pass < 30; ++pass) {
  if (pass == 0)
    createInitialThunkSections();  // pre-create empty ThunkSections
  bool changed = false;
  for (relocation : all_relocations) {
    if (pass > 0 && normalizeExistingThunk(rel))
      continue;  // existing thunk still in range
    if (!needsThunk(rel)) continue;
    Thunk *t = getOrCreateThunk(rel);
    ts = findOrCreateThunkSection(rel, src);
    ts->addThunk(t);
    rel.sym = t->getThunkTargetSym();  // redirect
    changed = true;
  }
  mergeThunks();  // insert ThunkSections into output
  if (!changed) break;
  assignAddresses();  // recalculate with new thunks
}

Key details:

• Multi-pass: Iterates until convergence (max 30passes). Adding thunks changes addresses, potentially puttingpreviously-in-range calls out of range.
• Pre-allocated ThunkSections: On pass 0,createInitialThunkSections places emptyThunkSections at regular intervals(thunkSectionSpacing). For AArch64: 128 MiB - 0x30000 ≈127.8 MiB.
• Thunk reuse: getThunk returns existingthunk if one exists for the same target;normalizeExistingThunk checks if a previously-created thunkis still in range.
• ThunkSection placement: getISDThunkSecfinds a ThunkSection within branch range of the call site, or createsone adjacent to the calling InputSection.

lld/MachO's thunk creationalgorithm

lld/MachO uses a single-pass algorithm inTextOutputSection::finalize:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

for (callIdx = 0; callIdx < inputs.size(); ++callIdx) {
  // Finalize sections within forward branch range (minus slop)
  while (finalIdx < endIdx && fits_in_range(inputs[finalIdx]))
    finalizeOne(inputs[finalIdx++]);

  // Process branch relocations in this section
  for (Relocation &r : reverse(isec->relocs)) {
    if (!isBranchReloc(r)) continue;
    if (targetInRange(r)) continue;
    if (existingThunkInRange(r)) { reuse it; continue; }
    // Create new thunk and finalize it
    createThunk(r);
  }
}

Key differences from lld/ELF:

• Single pass: Addresses are assigned monotonicallyand never revisited
• Slop reservation: ReservesslopScale * thunkSize bytes (default: 256 × 12 = 3072 byteson ARM64) to leave room for future thunks
• Thunk naming:<function>.thunk.<sequence> where sequenceincrements per target

Thunkstarvation problem: If many consecutive branches need thunks, eachthunk (12 bytes) consumes slop faster than call sites (4 bytes apart)advance. The test lld/test/MachO/arm64-thunk-starvation.sdemonstrates this edge case. Mitigation is increasing--slop-scale, but pathological cases with hundreds ofconsecutive out-of-range callees can still fail.

mold's thunk creationalgorithm

mold uses a two-pass approach: first pessimistically over-allocatethunks, then remove unnecessary ones.

Intuition: It's safe to allocate thunk space andlater shrink it, but unsafe to add thunks after addresses are assigned(would create gaps breaking existing references).

Pass 1 (create_range_extension_thunks):Process sections in batches using a sliding window. The window tracksfour positions:

1
2
3
4
5
6
7
8
9

Sections:   [0] [1] [2] [3] [4] [5] [6] [7] [8] [9] ...
             ^       ^       ^           ^
             A       B       C           D
             |       |_______|           |
             |         batch             |
             |                           |
             earliest                    thunk
             reachable                   placement
             from C

• [B, C) = current batch of sections to process (size≤ branch_distance/5)
• A = earliest section still reachable from C (forthunk expiration)
• D = where to place the thunk (furthest pointreachable from B)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Simplified from OutputSection<E>::create_range_extension_thunks
while (b < sections.size()) {
  // Advance D: find furthest point where thunk is reachable from B
  while (d < size && thunk_at_d_reachable_from_b)
    assign_address(sections[d++]);

  // Compute batch [B, C)
  c = b + 1;
  while (c < d && sections[c] < sections[b] + batch_size) c++;

  // Advance A: expire thunks no longer reachable
  while (a < b && sections[a] + branch_distance < sections[c]) a++;
  // Expire thunk groups before A: clear symbol flags.
  for (; t < thunks.size() && thunks[t].offset < sections[a]; t++)
    for (sym in thunks[t].symbols) sym->flags = 0;

  // Scan [B,C) relocations. If a symbol is not assigned to a thunk group yet,
  // assign it to the new thunk group at D.
  auto &thunk = thunks.emplace_back(new Thunk(offset));
  parallel_for(b, c, [&](i64 i) {
    for (rel in sections[i].relocs) {
      if (requires_thunk(rel)) {
        Symbol &sym = rel.symbol;
        if (!sym.flags.test_and_set()) {  // atomic: skip if already set
          lock_guard lock(mu);
          thunk.symbols.push_back(&sym);
        }
      }
    }
  });
  offset += thunk.size();
  b = c;  // Move to next batch
}

Pass 2 (remove_redundant_thunks): Afterfinal addresses are known, remove thunk entries for symbols actually inrange.

Key characteristics:

• Pessimistic over-allocation: Assumes allout-of-section calls need thunks; safe to shrink later
• Batch size: branch_distance/5 (25.6 MiB forAArch64, 3.2 MiB for AArch32)
• Parallelism: Uses TBB for parallel relocationscanning within each batch
• Single branch range: Uses one conservativebranch_distance per architecture. For AArch32, uses ±16 MiB(Thumb limit) for all branches, whereas lld/ELF uses ±32 MiB for A32branches.
• Thunk size not accounted in D-advancement: Theactual thunk group size is unknown when advancing D, so the end of alarge thunk group may be unreachable from the beginning of thebatch.
• No convergence loop: Single forward pass foraddress assignment, no risk of non-convergence

Comparing thunk algorithms

Linker relaxation (RISC-V)

RISC-V takes a different approach: instead of only expandingbranches, it can also shrink instruction sequences whenthe target is close enough.

Consider a function call using the callpseudo-instruction, which expands to auipc +jalr:

1
2
3
4
5

# Before linking (8 bytes)
call ext
# Expands to:
#   auipc ra, %pcrel_hi(ext)
#   jalr ra, ra, %pcrel_lo(ext)

If ext is within ±1MiB, the linker can relax this to:

1
2

# After relaxation (4 bytes)
jal ext

This is enabled by R_RISCV_RELAX relocations thataccompany R_RISCV_CALL relocations. TheR_RISCV_RELAX relocation signals to the linker that thisinstruction sequence is a candidate for shrinking.

Example object code before linking:

1
2
3
4
5
6
7
8
9

0000000000000006 <foo>:
       6: 97 00 00 00   auipc   ra, 0
                R_RISCV_CALL ext
                R_RISCV_RELAX *ABS*
       a: e7 80 00 00   jalr    ra
       e: 97 00 00 00   auipc   ra, 0
                R_RISCV_CALL ext
                R_RISCV_RELAX *ABS*
      12: e7 80 00 00   jalr    ra

After linking with relaxation enabled, the 8-byteauipc+jalr pairs become 4-bytejal instructions:

1
2
3
4
5
6

0000000000000244 <foo>:
     244: 41 11         addi    sp, sp, -16
     246: 06 e4         sd      ra, 8(sp)
     248: ef 00 80 01   jal     ext
     24c: ef 00 40 01   jal     ext
     250: ef 00 00 01   jal     ext

When the linker deletes instructions, it must also adjust:

• Subsequent instruction offsets within the section
• Symbol addresses
• Other relocations that reference affected locations
• Alignment directives (R_RISCV_ALIGN)

This makes RISC-V linker relaxation more complex than thunkinsertion, but it provides code size benefits that other architecturescannot achieve at link time.

Diagnosing out-of-rangeerrors

When you encounter a "relocation out of range" error, here are somediagnostic steps:

1. Check the error message: lld reports the sourcelocation, relocation type, and the distance. For example:

   1	ld.lld: error: a.o:(.text+0x1000): relocation R_AARCH64_CALL26 out of range: 150000000 is not in [-134217728, 134217727]

2. Use --verbose or-Map: Generate a link map to see sectionlayout and identify which sections are far apart.

3. Consider -ffunction-sections:Splitting functions into separate sections gives the linker moreflexibility in placement, potentially reducing distances.

4. Check for large data in .text:Embedded data (jump tables, constant pools) can push functions apart.Some compilers have options to place these elsewhere.

5. LTO considerations: Link-time optimization candramatically change code layout. If thunk-related issues appear onlywith LTO, the optimizer may be creating larger functions or differentinlining decisions.

Summary

Handling long branches requires coordination across thetoolchain:

The linker's thunk generation is particularly important for largeprograms where cross-compilation-unit calls may exceed branch ranges.Different linkers use different algorithms with various tradeoffsbetween complexity, optimality, and robustness.

RISC-V's linker relaxation is unique in that it can both expand andshrink code, optimizing for both correctness and code size.

老司机 iOS 周报，只为你呈现有价值的信息。

你也可以为这个项目出一份力，如果发现有价值的信息、文章、工具等可以到 Issues 里提给我们，我们会尽快处理。记得写上推荐的理由哦。有建议和意见也欢迎到 Issues 提出。

文章

🐕 精通 UITableViewDiffableDataSource ——从入门到重构的现代 iOS 列表开发指南

@阿权：本文围绕 iOS 现代列表 UITableViewDiffableDataSource 展开，核心是替代传统数据源代理模式，解决列表开发中的崩溃、状态不一致等痛点，并在最后提供一个轻量工具集 DiffableDataSourceKit 来简化系统 API 的调用。文章核心内容如下：

1. 使用 UITableViewDiffableDataSource API，通过声明式的“快照”来管理数据状态，系统自动计算并执行 UI 更新动画，从而一劳永逸地解决了传统模式中数据与 U 状态不同步导致的崩溃问题。
2. 全文通过构建一个音乐播放列表 App 来贯穿始终，从移除 Storyboard、定义遵循 Hashable 协议的数据模型开始，一步步教你初始化数据源和填充数据。
3. 文章还详细讲解了：
   • 自定义多样化的单元格：包括使用传统的 Auto Layout 布局，以及利用 iOS 14+ 的 UIContentConfiguration 进行现代化配置。
   • 实现核心交互：具体涉及了拖拽重排、滑动删除，以及如何通过 Cell 的代理事件处理等交互。
   • 处理复杂逻辑：特别讲解了如何利用模型的 Hashable 来实现“原地刷新”而非替换的刷新机制。

除了文章提到的 UITableViewDiffableDataSource，用好这些技术，不妨可以再看看以下几个 WWDC：

1. WWDC19 - 215 - Advances in Collection View Layout
2. WWDC19 - 220 - Advances in UI Data Sources
3. WWDC20 - 10026 - Lists in UICollectionView
4. WWDC20 - 10027 - Modern cell configuration

另外，与其用 UITableView 承载数据，其实 Apple 更推荐使用 UICollectionView 来实现列表，甚至还提供了增强版的 Cell。

恰逢 App Store 要求用 Xcode 26 带来的强制升级，不少 App 也终于抛弃了 iOS 12、iOS 13，也是用新技术（也不新了）升级项目架构的最好时机。

除了 API 本身，我们也应关注到一些架构或设计模式上的变化与趋势：

1. 声明式。新的 API 更多使用构造时定义逻辑的声明式语法，在一开始就把相关的布局、样式等逻辑给定义好，后续不再通过各种存储属性配置逻辑。极大地减少了开发者对状态的维护。例如 UICollectionViewCompositionalLayout 通过 Item、可嵌套的 Group、Section 一层一层地在初始化配置布局。
2. 数据驱动。声明式常常是为了数据驱动，因为声明式定义的不是最终对象，而是一些前置的配置数据结构。例如 Cell 提供了 Configuration 结构体，通过配置和重新赋值结构体来实现 UI 更新，而不是直接操作 View。类似的，UIButton 也提供了类型的 Configuration 结构体用于配置 UI。更深一层的意义，驱动 UI 的配置数据、视图甚至可以复用的和无痛迁移的。例如 UITableViewCell 和 UICollectionViewCell 的配置类及其关联子视图是通用的，自定义 Cell 可以把重心放在自定义 Configuration 配置上，这样就可以把相同的视图样式套用在各种容器中。
3. 数据绑定。将索引替换为 id 甚至是具体业务类型。以往 UITableView、UICollectionView 的 API 都是围绕索引（IndexPath）展开的，所有的数据（DataSource）、布局（CollectionViewLayout）和视图（Presentation: Cell、ReuseableView）即使有分离，但都需要通过索引来交换。虽然这样简化了不同模块的耦合和通信逻辑，但因为大多数业务场景数据是动态的，这让索引只是个临时态，一不小心就会用错，轻则展示错误，重则引入崩溃。DiffableDataSource 最具里程碑的一点是剔除了索引，直接让具体业务模型跟 Cell 直接绑定，不经过索引。
4. 类型安全。不再是 Any/AnyObject，而是直接绑定一个具体的类型。常见做法是通过泛型机制将类型传入。
5. 用轮子，而不是造轮子。系统 API 足够自由，直接使用实例，而不是子类化自定义逻辑。以往的开发经验，都是一言不合就重写实现，重新造控件、布局，UIButton 和 UICollectionViewLayout 就是两个典型的 case。近年来系统 API 都在丰富使用的自由度和易用程度，例如 UIButton 提供了许多拿来就能用的灵活样式，开发者只需要微调个 Configuration 就是能实现业务效果。UICollectionViewCompositionalLayout 则是用 Item、Group、Section 构造足够复杂的布局场景。另外一点验证了这个趋势的是，iOS 26 中，只有官方提供的控件、导航框架才有完整的液态玻璃交互。

架构的演进一般是为了提高研效、减少出错。一个合理、高效的代码架构，在当业务需求变得复杂的时候，业务调用代码不会随业务的复杂而线性增长，而是逐渐减少。

🐎 Dart 官方再解释为什么放弃了宏编程，并转向优化 build_runner ? 和 Kotlin 的区别又是什么？

@Crazy：本文主要介绍了 Dart 官方放弃宏编程改为优化 build_runner 的原因，在读本文之前，要先明白什么是宏编程。文章中介绍了 Dart 在实现宏编程的过程中试用的方案与思考，放弃的原因总结起来有三个 :

1. 编译会卡在一个“先有鸡还是先有蛋”的死结
2. 工具链双前端导致宏支持会引发“工作量爆炸 + 性能灾难”
3. 即使做成了，也“高不成低不就”：替代不了 build_runner，不如直接扩展 build_runner 能力

文章最后还对比了 Kotlin 的 Compiler Plugins、KSP 与 Swift 的 Swift Macros 的差距，总的来说 build_runner 还有很长的一段路要走。

🐕 @_exported import VS public import

@AidenRao：Swift 6 带来了全新的 import 访问级别控制：@_exported import。它和我们熟悉的 public import 有什么不同？简单来说，public import 只是将一个模块声明为公开 API 的一部分，但使用者仍需手动导入它；而 @_exported import 则是将依赖的符号完全“吸收”，调用方无需关心底层依赖。文章深入对比了两者的意图和应用场景，并给出了明确建议：日常开发中应优先选择官方支持的 public import，仅在封装 SDK 或构建聚合模块（Umbrella Module）这类希望为用户简化导入操作的场景下，才考虑使用 @_exported。

🐕 MVVM + Reducer Pattern

@含笑饮砒霜：这篇文章主要讲述如何将 MVVM 架构与 Reducer 模式结合来提升 iOS 应用中状态管理的可控性和可维护性。作者指出：传统的 MVVM 模式在复杂状态下易出现分散的状态变更和难以追踪的问题，这会导致难调试、隐式状态转换、竞态条件等不良后果；而 Reducer 模式（受 Redux/TCA 启发）通过 “单一状态源 + 明确 action + 纯函数 reduce ” 的方式，使状态变更更可预测、更易测试。文章建议在 ViewModel 内部局部引入 reducer，把所有状态通过单一 reduce(state, action) 处理，并把副作用（如异步任务）当作 effects 处理，从而达到更明确、可追踪且易单元测试的效果，同时保留 MVVM 和领域层的清晰分层，不强依赖某个框架。

🐢 用第一性原理拆解 Agentic Coding：从理论到实操

@Cooper Chen：文章从第一性原理出发，系统拆解了 Agentic Coding 背后的底层逻辑与工程现实，澄清了一个常见误区：效率瓶颈不在于上下文窗口不够大，而在于我们如何与 AI 协作。作者以 LLM 的自回归生成与 Attention 机制为起点，深入分析了 Coding Agent 在长任务中常见的“走偏”“失忆”“局部最优”等问题，并指出这些并非工具缺陷，而是模型工作方式的必然结果。

文章最有价值之处，在于将理论约束转化为可执行的工程实践：通过“短对话、单任务”的工作方式控制上下文质量；用结构化配置文件和工具设计引导 Agent 行为；通过 Prompt Caching、Agent Loop、上下文压缩等机制提升系统稳定性。更进一步，作者提出“复利工程（Compounding Engineering）”这一关键理念——不把 AI 当一次性工具，而是通过文档、规范、测试和审查，将每一次经验沉淀为系统的长期记忆。

最终，文章给出的启示非常清晰：AI 编程不是魔法，而是一门需要刻意练习的协作技能。当你真正理解模型的边界，并用工程化方法加以约束和放大，AI 才能从“能写代码”进化为“可靠的编程合作者”。

🐎 Universal Links At Scale: The Challenges Nobody Talks About

@Damien：文章揭示了 Universal Links 在大规模应用中的隐藏复杂性：AASA 文件缺乏 JSON 模式验证导致静默失效，Apple CDN 缓存延迟使问题修复滞后，苹果特有通配符语法和 substitutionVariables 变量无现成工具支持。作者提出通过 CI 集成模式验证、CDN 同步检查、自定义正则解析和 staging 环境测试的完整方案，并开源了 Swift CLI 工具实现全链路自动化验证。

🐕 How I use Codex GPT 5.2 with Xcode (My Complete Workflow)

@JonyFang: 本视频深入介绍了如何让 AI 代理（如 Codex GPT 5.2）真正提升 iOS/macOS 开发效率的三个核心策略：

1. 构建脚本自动化（Build Scripts）：通过标准化的构建流程，让 AI 能够理解和复现你的构建环境
2. 让构建失败显而易见（Make Build Failures Obvious）：优化错误信息的呈现方式，使 AI 能够快速定位问题根源
3. 给你的代理装上"眼睛"（Give Your Agent Eyes）：这是最核心的部分 - 让 AI 能够"看到"应用运行时的状态，而不仅仅是读取代码

最有价值之处：作者强调了一个常被忽视的问题 - AI 代码助手不仅需要理解代码逻辑，更需要理解应用的运行时状态。通过工具如 Peekaboo 等，让 AI 能够获取视觉反馈（截图、UI 层级等），从而提供更精准的问题诊断和代码建议。这种"可观测性优先"的思路，与传统的代码审查工作流形成了有趣的对比，值得所有尝试将 AI 工具深度集成到开发流程中的团队参考。

视频时长约 49 分钟，适合希望系统性提升 AI 辅助开发效率的 iOS/macOS 开发者观看。

工具

🐎 Skip Is Now Free and Open Source

@Crazy：Skip 框架正式免费并且开源，该库从 2023 年开始开发，已有三年的开发历程。该库的目的是让开发者能够仅用一套 Swift 与 SwiftUI 代码库，同时打造 iOS 与 Android 上的高品质移动应用——而且不必接受那些自“跨平台工具诞生以来就一直存在”的妥协。因为 Skip 是采用编译为 Kotlin 与 Compose 的方式，所以相应的执行效率是非常高的。相较于其他的跨平台开发，效率高，并且使用的是 Swift 语言。既然已经免费并开源，移动端开发的时候又多了一个可供选择的跨端技术。

内推

重新开始更新「iOS 靠谱内推专题」，整理了最近明确在招人的岗位，供大家参考

具体信息请移步：https://www.yuque.com/iosalliance/article/bhutav 进行查看（如有招聘需求请联系 iTDriverr）

关注我们

我们是「老司机技术周报」，一个持续追求精品 iOS 内容的技术公众号，欢迎关注。

关注有礼，关注【老司机技术周报】，回复「2024」，领取 2024 及往年内参

同时也支持了 RSS 订阅：https://github.com/SwiftOldDriver/iOS-Weekly/releases.atom 。

说明

🚧 表示需某工具，🌟 表示编辑推荐

预计阅读时间：🐎 很快就能读完（1 - 10 mins）；🐕 中等 （10 - 20 mins）；🐢 慢（20+ mins）

ARC 原理与 weak 底层实现（Side Table 深度解析）

面向：有一定 iOS / Runtime 基础的开发者

目标：真正搞清楚 weak 到底 weak 了谁、SideTable 里存的是什么、为什么能自动置 nil

一、先给结论（非常重要）

weak 不是修饰对象，而是修饰“指针变量”

SideTable 记录的是：某个对象，被哪些 weak 指针地址指向

换句话说：

• ❌ 不是「A weak 引用 B」
• ❌ 不是「对象记住了谁 weak 它」
• ✅ 是「Runtime 记住：哪些内存地址（weak 指针）指向了这个对象」

二、从一行代码开始

@property (nonatomic, weak) Person *person;

编译后本质是：

Person *__weak _person;

说明三点：

1. _person 是一个普通指针变量
2. weak 修饰的是这个指针变量的行为
3. 并不是 Person 对象“变成了 weak”

三、明确三个核心角色

Person *p = [[Person alloc] init];
self.person = p; // weak

此时内存中存在三样东西：

weak 的对象不是 Person，而是 _person 这个指针变量。

四、objc_storeWeak 到底做了什么？

self.person = p;

编译后：

objc_storeWeak(&self->_person, p);

注意这里传入的两个参数：

• &self->_person 👉 weak 指针的地址

• p 👉 对象地址

Runtime 的真实意图：

登记：对象 p，被这个 weak 指针地址弱引用了

五、SideTable / weak_table 的真实逻辑结构

1️⃣ SideTable（简化）

struct SideTable {
    spinlock_t lock;
    RefcountMap refcnts;     // 强引用计数
    weak_table_t weak_table; // 弱引用表
};

2️⃣ weak_table_t

struct weak_table_t {
    weak_entry_t *weak_entries;
};

3️⃣ weak_entry_t（重点）

struct weak_entry_t {
    DisguisedPtr<objc_object> referent; // 被 weak 的对象
    weak_referrer_t *referrers;         // weak 指针地址数组
};

六、SideTable 中真正存的是什么？

用一张逻辑图表示：

SideTable
└── weak_table
    └── weak_entry
        ├── referent = Person 对象
        └── referrers = [
              &self->_person,
              &vc->_delegate,
              &cell->_model
          ]

关键点（一定要记住）：

• weak_table 的 key 是对象
• value 是 所有指向它的 weak 指针地址

七、谁被 weak？谁被记录？

以：

self.person = p;

为例：

八、对象释放时为什么能自动置 nil？

当 Person 的引用计数降为 0：

objc_destroyWeak(obj);

Runtime 的逻辑流程：

1. 找到 obj 对应的 weak_entry
2. 遍历 referrers（weak 指针地址）
3. 对每个地址执行：
      *(Person **)referrer = nil
4. 移除 weak_entry

⚠️ Runtime 完全不知道变量名，只操作内存地址。

九、用内存视角完整走一遍

1️⃣ 内存布局

0x1000  Person 对象

0x2000  p (strong)        → 0x1000
0x3000  self->_person     → 0x1000

2️⃣ weak_table

key: 0x1000
value: [0x3000]

3️⃣ Person 释放

free(0x1000)
*(0x3000) = nil

最终：

self.person == nil

十、为什么 weak 不会产生野指针？

weak 的安全性来自 Runtime 的集中清理机制

十一、为什么 weak_table 以“对象”为中心？

因为：

对象释放是一个确定事件

以对象为 key：

• 对象销毁 → 一次性清理所有 weak 指针
• 性能可控
• 逻辑集中

十二、常见误解澄清

❌ A weak 引用 B

✅ A 的某个指针 weak 指向 B

❌ 对象知道谁 weak 它

✅ Runtime 知道，对象本身不知道

❌ weak 是对象属性

✅ weak 是指针语义

❌ weak 只是“不 retain”

✅ weak = 不 retain + 注册 weak_table + 自动置 nil

十三、一句话总结

weak 的本质不是弱引用对象，

而是 Runtime 记录“哪些指针弱指向了这个对象”，

并在对象销毁时统一把这些指针置为 nil。

十四、下一步可继续深入

• block 捕获下 weak_table 的变化过程

• __unsafe_unretained 与 weak 的实现对比

• objc-runtime 源码中 weak_entry 的真实实现

一、Flutter 渲染原理（最高频考点）

Q1：Flutter 的渲染原理是什么？为什么 Flutter 能做到高性能跨平台？

核心答案：Flutter 采用自绘引擎架构，不依赖平台原生控件，而是通过 Skia 引擎直接在 GPU 上绘制 UI，从而实现跨平台一致性和高性能。

深入原理：

Flutter 与其他跨平台方案的本质区别在于渲染方式：

Flutter 只需要平台提供一个"画布"（Surface），然后自己完成所有渲染工作。这就像你给我一张白纸，我自己画画，而不是让你帮我画。

串联知识点：

这也解释了为什么 Flutter 的 Platform Channel 只用于功能调用（相机、传感器）而不用于 UI 渲染——UI 完全由 Flutter 自己处理，不走原生。

Q2：Flutter 的三棵树是什么？它们之间的关系是什么？

核心答案：Widget 树是配置描述，Element 树是实例管理，RenderObject 树是布局绘制。三者分离是为了实现"配置与渲染解耦"，从而支持高效的增量更新。

深入原理：

第一层理解——各自职责：

• Widget：不可变的配置对象，描述"UI 应该长什么样"。类似于 React 的 Virtual DOM 节点。
• Element：Widget 的实例化，是真正"活着"的对象，管理生命周期、父子关系、状态。
• RenderObject：负责布局（计算大小位置）和绘制（生成绘制指令）。

第二层理解——为什么要分三层？

这是经典的"关注点分离"设计：

1. Widget 可以频繁重建：因为它只是配置，创建成本极低（就是个普通对象）
2. Element 负责复用决策：通过 diff 算法决定是复用还是重建 RenderObject
3. RenderObject 尽量复用：因为布局和绘制成本高

如果没有 Element 这一层，每次 setState 都要重建整个 RenderObject 树，性能会很差。

第三层理解——diff 复用机制：

Element 的复用规则：

1. 同一个 Widget 实例（const）→ 直接复用，什么都不做
2. 类型相同 + Key 相同 → 复用 Element，调用 update 更新配置
3. 类型不同 或 Key 不同 → 销毁重建

串联知识点：

这就是为什么推荐使用 const 构造函数——const Widget 是编译期常量，同一实例直接复用，连 diff 都省了。

这也解释了为什么 Key 很重要——没有 Key 时只比较类型，列表项交换位置会导致状态错乱。

Q3：setState 调用后发生了什么？完整流程是什么？

核心答案：setState 本身是同步的，但 UI 更新是异步的。它只是标记当前 Element 为 dirty，然后在下一帧的 Build 阶段统一重建。

完整流程：

setState() 调用
    ↓
执行传入的闭包，修改成员变量
    ↓
调用 _element.markNeedsBuild()
    ↓
将 Element 加入 dirty 列表
    ↓
如果还没请求过，调用 scheduleFrame() 请求下一帧
    ↓
setState 返回（此时 UI 还没变化）
    ↓
等待 VSync 信号
    ↓
handleBeginFrame → handleDrawFrame
    ↓
BuildOwner.buildScope() 遍历 dirty 列表
    ↓
对每个 dirty Element 调用 rebuild()
    ↓
rebuild 调用 build() 生成新 Widget
    ↓
updateChild 进行 diff 比较
    ↓
复用或重建子 Element
    ↓
如果需要，更新 RenderObject
    ↓
标记 needsLayout 或 needsPaint
    ↓
后续的 Layout 和 Paint 阶段处理

xyz追问：为什么 setState 是异步更新？

1. 合并多次调用：同一帧内多次 setState 只会触发一次重建
2. 批量处理：所有 dirty Element 统一处理，而不是逐个处理
3. 与渲染管线同步：在 VSync 信号驱动下统一更新，保证流畅

xyz追问：在 build 方法里调用 setState 会怎样？

会报错！因为正在 build 的过程中不能再标记 dirty。这是一个保护机制，防止无限循环。

串联知识点：

这与 React 的 setState 机制类似——都是"标记脏，批量更新"。但 Flutter 更进一步，与渲染管线（VSync）深度绑定。

Q4：Flutter 一帧的渲染流程是什么？

核心答案：VSync → Animate → Build → Layout → Paint → Composite → Rasterize

详细阶段：

深入理解——标记传播机制：

这里有一个关键设计：标记是向上传播的。

比如你调用 setState：

1. 当前 Element 标记 dirty
2. 重建时可能更新 RenderObject 的配置
3. RenderObject 检测到配置变化，标记 needsLayout
4. needsLayout 向上传播到布局边界（Relayout Boundary）
5. Layout 阶段只处理边界内的节点

同理，needsPaint 也会向上传播到重绘边界（Repaint Boundary）。

xyz追问：为什么要标记传播而不是直接更新？

性能优化！标记只是打个记号（O(1)），真正的计算延迟到统一处理阶段。这样可以合并多次变化，避免重复计算。

串联知识点：

这就是为什么 RepaintBoundary 能优化性能——它阻断了 needsPaint 的向上传播，让重绘范围最小化。

Q5：Flutter 的布局原理是什么？Constraints 是怎么传递的？

核心答案：Flutter 采用单次遍历的盒约束布局，约束从上往下传，尺寸从下往上返，父节点决定子节点位置。

核心原则：

Constraints go down, Sizes go up, Parent sets position.

详细流程：

1. 父节点调用 child.layout(constraints)，把约束传给子节点
2. 子节点在约束范围内确定自己的 size，存到 size 属性
3. 父节点读取 child.size，决定子节点的偏移量（通过 ParentData）
4. 子节点不知道自己在父节点中的位置

xyz追问：为什么子节点不知道自己的位置？

这是性能优化！如果子节点位置变化，不需要重新布局子树。比如动画移动一个 Widget，只需要改 offset，不需要重新计算子节点的大小。

约束类型：

xyz追问：为什么会有"RenderBox was not laid out"错误？

常见于无界约束场景。比如在 Column 里放 ListView，Column 给 ListView 的高度约束是无界的（infinity），而 ListView 需要一个确定的高度。解决方案：用 Expanded 包裹或设置固定高度。

串联知识点：

这也解释了为什么 Flex 布局中要用 Expanded/Flexible——它们会把无界约束转换为有界约束。

Q6：RenderObject 的 Relayout Boundary 是什么？为什么能优化性能？

核心答案：Relayout Boundary 是布局边界，它的布局变化不会影响父节点，也不受兄弟节点影响，从而减少布局计算范围。

触发条件（满足任一）：

1. parentUsesSize = false（父节点不关心子节点大小）
2. sizedByParent = true（大小完全由约束决定）
3. 约束是紧约束（大小固定）
4. 是根节点

原理：

正常情况下，子节点大小变化 → 父节点需要重新布局 → 可能影响兄弟节点 → 连锁反应。

但如果子节点是 Relayout Boundary：

• 它的大小变化不会通知父节点
• 布局只在边界内进行
• 大大减少计算量

xyz追问：和 RepaintBoundary 什么区别？

前者是自动的（满足条件就是），后者需要手动添加 RepaintBoundary Widget。

串联知识点：

这就是为什么固定大小的组件性能更好——它们自动成为 Relayout Boundary，布局变化不会影响外部。

二、Element 与 State 生命周期

Q7：StatefulWidget 的完整生命周期是什么？

核心答案：createState → initState → didChangeDependencies → build → (didUpdateWidget/setState → build)* → deactivate → dispose

详细流程：

xyz追问：initState 里能调用 setState 吗？

可以调用，但没必要。因为 initState 之后会自动调用 build。

xyz追问：initState 里能使用 context 吗？

可以使用，但不能调用 dependOnInheritedWidgetOfExactType。因为此时依赖关系还没建立完成。正确做法是在 didChangeDependencies 中获取。

xyz追问：deactivate 和 dispose 的区别？

deactivate：从树中移除，但可能重新激活（比如 GlobalKey 跨树移动） dispose：永久销毁，不会再使用

如果在 deactivate 中释放资源，重新激活时就没有资源可用了。所以资源释放应该放在 dispose。

串联知识点：

这就是为什么 GlobalKey 能跨树保持状态——它让 Element 在 deactivate 后不立即 dispose，而是等待可能的重新激活。

Q8：Key 的作用是什么？什么时候需要用 Key？

核心答案：Key 用于标识 Element 的身份，控制 Element 的复用逻辑。在列表项可能变化（增删、重排序）时必须使用。

原理：

没有 Key 时的匹配：只比较 Widget 类型 有 Key 时的匹配：比较类型 + Key

经典问题：列表项交换

假设列表：[A, B] 变为 [B, A]

没有 Key：

• 位置 0：类型相同 → 复用 Element，更新配置（A→B）
• 位置 1：类型相同 → 复用 Element，更新配置（B→A）
• 结果：Element 被复用，但 State 没有跟着移动！

有 Key：

• 位置 0：Key 不匹配 → 从其他位置找到匹配的 Element
• Flutter 会正确移动 Element 而不是更新
• 结果：Element 和 State 一起移动

Key 的类型：

xyz追问：GlobalKey 为什么慎用？

1. 有注册/注销开销
2. 会阻止 Element 回收
3. 全局维护 Map，内存占用

串联知识点：

Key 的本质是给 Element 一个"身份证"，让 Flutter 知道"这个 Widget 对应的是哪个 Element"，而不只是"这个位置应该放什么类型的 Widget"。

三、InheritedWidget 与状态管理

Q9：InheritedWidget 的原理是什么？为什么查找是 O(1)？

核心答案：每个 Element 持有一个 Map，记录祖先中所有 InheritedWidget 的类型到 Element 的映射，查找时直接用类型做 key。

原理详解：

每个 Element 有个属性：Map<Type, InheritedElement>? _inheritedWidgets

当 Element 挂载（mount）时：

1. 继承父节点的 _inheritedWidgets（浅拷贝）
2. 如果自己是 InheritedElement，添加自己：_inheritedWidgets[MyWidget] = this

当调用 dependOnInheritedWidgetOfExactType<T>() 时：

1. 直接 _inheritedWidgets[T] 获取，O(1)
2. 把当前 Element 注册为依赖者
3. 返回 InheritedWidget

xyz追问：依赖是怎么建立的？

InheritedElement 维护一个 Set<Element> _dependents。

调用 dependOnInheritedWidgetOfExactType 时，会把调用者加入这个 Set。

当 InheritedWidget 更新且 updateShouldNotify 返回 true 时，遍历 _dependents，对每个依赖者调用 didChangeDependencies，并标记 dirty。

xyz追问：of(context) 和 maybeOf(context) 的区别？

of：找不到会抛异常 maybeOf：找不到返回 null

串联知识点：

Provider、Riverpod、GetX 等状态管理库的核心都是对 InheritedWidget 的封装。它们本质上都在利用这个 O(1) 查找和自动依赖追踪机制。

Q10：Provider 的原理是什么？ChangeNotifier 是怎么工作的？

核心答案：Provider = InheritedWidget + ChangeNotifier。InheritedWidget 负责数据传递，ChangeNotifier 负责变化通知。

工作流程：

1. ChangeNotifierProvider 创建并持有 ChangeNotifier 实例
2. 内部使用 InheritedWidget 向下传递
3. ChangeNotifier 调用 notifyListeners() 时
4. Provider 监听到变化，重建 InheritedWidget
5. updateShouldNotify 返回 true
6. 所有依赖者收到通知并重建

xyz追问：Consumer 和 Provider.of 的区别？

本质相同，但 Consumer 把 rebuild 范围限制在 builder 内部。

Provider.of(context) 会让整个 build 方法重建。 Consumer 只重建 builder 返回的部分。

xyz追问：Selector 是怎么优化的？

Selector 增加了一层"选择"：

1. 用 selector 函数从数据中提取需要的部分
2. 只有提取的部分变化时才重建
3. 使用 == 比较（或自定义 shouldRebuild）

这避免了"数据的其他字段变化导致我重建"的问题。

串联知识点：

这就是为什么状态管理要"细粒度"——把大状态拆成小状态，每个组件只依赖需要的部分，减少不必要的重建。

四、Dart 异步机制

Q11：Dart 的事件循环是怎么工作的？microtask 和 event 的区别？

核心答案：Dart 是单线程模型，通过事件循环处理异步。事件循环维护两个队列：microtask 队列（高优先级）和 event 队列（低优先级）。每次处理完所有 microtask 后才处理一个 event。

执行顺序：

同步代码
    ↓
所有 microtask（直到队列空）
    ↓
一个 event
    ↓
所有 microtask（直到队列空）
    ↓
一个 event
    ↓
...循环...

加入队列的方式：

xyz追问：为什么要有 microtask？

microtask 用于"在当前事件处理完成后、下一个事件开始前"执行的操作。

典型场景：Future.then 的回调需要在 Future 完成后立即执行，而不是等其他事件。

xyz追问：输出顺序题

print('1');
Future(() => print('2'));
Future.microtask(() => print('3'));
scheduleMicrotask(() => print('4'));
print('5');

答案：1, 5, 3, 4, 2

解析：

• 1, 5：同步代码
• 3, 4：microtask（按加入顺序）
• 2：event

串联知识点：

这就是为什么 setState 后 UI 不会立即更新——setState 只是把重建任务加入了调度，真正的重建在下一帧的事件中执行。

Q12：Future 和 async/await 的原理是什么？

核心答案：Future 是对异步操作的封装，代表一个未来会完成的值。async/await 是 Future 的语法糖，编译器会将其转换为 then 链。

Future 的三种状态：

• Uncompleted：操作进行中
• Completed with value：成功完成
• Completed with error：失败

async/await 转换：

// 源代码
Future<int> foo() async {
  var a = await bar();
  var b = await baz(a);
  return a + b;
}

// 等价于
Future<int> foo() {
  return bar().then((a) {
    return baz(a).then((b) {
      return a + b;
    });
  });
}

xyz追问：async 函数一定是异步的吗？

async 函数总是返回 Future，但不一定真的异步执行。

Future<int> foo() async {
  return 42;  // 同步返回
}

这个函数同步执行完，但返回的是 Future<int>，获取值需要 await 或 then。

xyz追问：多个 await 是并行还是串行？

串行！每个 await 都要等上一个完成。

并行需要用 Future.wait：

var results = await Future.wait([foo(), bar(), baz()]);

串联知识点：

理解 async/await 是语法糖，就能理解很多"诡异"行为：

• 为什么 async 函数返回的 Future 即使没 await 也能执行——then 的回调会被调度
• 为什么 catchError 能捕获 async 函数中的异常——编译器转换成了 try-catch

Q13：Isolate 是什么？和 Future 什么区别？

核心答案：Future 是单线程内的异步，用于 I/O 操作；Isolate 是真正的多线程，用于 CPU 密集型计算。Isolate 之间内存隔离，通过消息传递通信。

本质区别：

为什么 I/O 用 Future 就够了？

I/O 操作（网络请求、文件读写）是"等待"，不占用 CPU。Dart 通过事件循环调度，等待期间可以处理其他事件。

为什么 CPU 密集操作需要 Isolate？

CPU 密集操作（JSON 解析、图片处理）会阻塞事件循环，导致 UI 卡顿。Isolate 在独立线程执行，不阻塞主线程。

Isolate 通信机制：

Main Isolate          New Isolate
     |                     |
 SendPort ──────────► ReceivePort
     |                     |
 ReceivePort ◄────────── SendPort
     |                     |
  独立堆内存            独立堆内存

消息是深拷贝的，不共享内存，所以没有锁和竞争条件。

xyz追问：compute 函数是什么？

Flutter 提供的便捷函数，封装了 Isolate 的创建、通信、销毁：

final result = await compute(parseJson, jsonString);

适合一次性计算任务。

串联知识点：

这就是为什么 Flutter 有时候会"卡一下"——可能是同步的 CPU 密集操作阻塞了事件循环。解决方案：用 compute 或 Isolate 把计算移到后台。

五、Platform Channel

Q14：Flutter 如何与原生通信？三种 Channel 的区别？

核心答案：通过 Platform Channel 通信，本质是二进制消息传递。MethodChannel 用于方法调用，EventChannel 用于事件流，BasicMessageChannel 用于基础消息。

三种 Channel 对比：

通信流程：

Dart 调用 invokeMethod
    ↓
参数序列化为二进制
    ↓
通过 C API 传递到原生层
    ↓
原生层反序列化，执行方法
    ↓
结果序列化为二进制
    ↓
传回 Dart 层
    ↓
反序列化，完成 Future

xyz追问：在哪个线程执行？

Dart 侧：UI 线程 原生侧：也应该在主线程调用

如果原生有耗时操作，应该切到后台线程，完成后再切回主线程返回结果。

xyz追问：StandardMessageCodec 支持哪些类型？

null、bool、int、double、String、Uint8List、List、Map

复杂对象需要手动序列化为上述类型。

串联知识点：

Platform Channel 只用于"功能调用"，不用于"UI 渲染"——因为 Flutter 自己渲染 UI。这是 Flutter 与 React Native 的本质区别。

六、热重载

Q15：热重载的原理是什么？为什么能保持状态？

核心答案：热重载利用 JIT 编译的能力，增量编译变化的代码，注入到运行中的 Dart VM，然后触发 Widget 树重建，但保持 Element 树和 State 不变。

原理详解：

文件保存
    ↓
检测变化的 Dart 文件
    ↓
增量编译为 Kernel（.dill）
    ↓
通过 VM Service 发送到设备
    ↓
Dart VM 加载新代码，替换类定义
    ↓
Flutter Framework 调用 reassemble()
    ↓
从根节点开始 rebuild
    ↓
Widget 树重建，Element 树复用
    ↓
State 保持不变

为什么能保持状态？

• 只是 Widget（配置）变了
• Element 被复用（类型没变）
• State 对象没有被销毁

相当于给 State 换了一套新的 Widget 配置，但 State 本身还是那个 State。

xyz追问：什么情况下热重载不生效？

1. 修改 main() 函数
2. 修改全局变量/静态变量的初始化
3. 修改枚举定义
4. 修改泛型类型参数
5. 原生代码修改

这些情况需要热重启（Hot Restart）或完全重启。

xyz追问：为什么 Release 模式不支持热重载？

因为 Release 模式使用 AOT 编译，代码已经编译为机器码，无法动态替换。

热重载依赖 JIT 编译器的动态代码注入能力。

串联知识点：

这就是 Debug 模式启动慢但支持热重载、Release 模式启动快但不支持热重载的原因——编译方式不同。

七、动画原理

Q16：Flutter 动画的原理是什么？Ticker 是什么？

核心答案：Flutter 动画由 Ticker 驱动，Ticker 与 VSync 同步，每帧回调一次。AnimationController 接收 Ticker 信号，更新动画值，通知监听者重建。

核心组件：

• Ticker：时钟信号源，与 VSync 同步，每帧回调
• AnimationController：持有 Ticker，管理动画值（0.0-1.0）
• Tween：值映射，把 0.0-1.0 映射到目标范围
• Curve：时间曲线，控制动画的速度变化

动画更新流程：

VSync 信号
    ↓
SchedulerBinding.handleBeginFrame()
    ↓
Ticker 收到回调
    ↓
AnimationController 更新 value
    ↓
notifyListeners()
    ↓
AnimatedBuilder.setState()
    ↓
rebuild → 新的 Widget 配置
    ↓
RenderObject 更新 → 重绘

xyz追问：为什么要用 TickerProviderStateMixin？

Ticker 需要在页面不可见时暂停，避免浪费资源。

TickerProviderStateMixin 会在 State deactivate 时暂停 Ticker。

xyz追问：隐式动画和显式动画的区别？

串联知识点：

动画本质是"每帧改变一点点"。Ticker 保证与屏幕刷新同步，AnimationController 计算每帧的值，Widget 根据值重建——这就是 Flutter 动画的完整链路。

八、图片与列表

Q17：ListView 的懒加载原理是什么？Sliver 是什么？

核心答案：ListView 内部使用 Sliver 协议，只构建可视区域及缓存区的子项，滚动时动态创建和回收，实现按需加载。

Sliver 协议 vs Box 协议：

懒加载流程：

用户滚动
    ↓
Viewport 计算可视范围
    ↓
SliverList 收到新的 SliverConstraints
    ↓
根据 scrollOffset 计算首个可见项
    ↓
按需调用 builder 创建子项
    ↓
创建直到填满可视区域 + 缓存区
    ↓
回收离开缓存区的子项

xyz追问：itemExtent 为什么能优化性能？

没有 itemExtent：需要逐个布局子项才知道高度，才能计算滚动范围 有 itemExtent：高度固定，直接计算，不需要实际布局

对于 1000 项的列表，跳转到第 800 项：

• 没有 itemExtent：可能需要布局前 800 项
• 有 itemExtent：直接计算偏移 = 800 * itemExtent

xyz追问：为什么 ListView 里放 ListView 会报错？

Column 给 ListView 的高度约束是 infinity（无界）。 ListView 需要确定的高度来计算滚动范围。 无界约束 + 需要确定高度 = 冲突。

解决：用 Expanded 包裹，或给 ListView 设置固定高度。

串联知识点：

Sliver 的设计思想是"只做需要做的事"——只构建可见的，只布局可见的，只绘制可见的。这是 Flutter 列表高性能的根本。

Q18：图片加载和缓存的原理是什么？

核心答案：Flutter 使用 ImageCache 进行内存缓存，ImageProvider 负责加载逻辑。图片加载是异步的，解码后缓存，下次直接复用。

加载流程：

Image Widget 创建 ImageProvider
    ↓
ImageProvider 生成缓存 Key
    ↓
检查 ImageCache
    ↓
命中 → 直接返回 ImageInfo
    ↓
未命中 → 调用 load()
    ↓
下载/读取原始数据
    ↓
解码为 ui.Image
    ↓
缓存到 ImageCache
    ↓
通知 Image Widget 更新

ImageCache 策略：

• 最大数量：默认 1000
• 最大字节：默认 100MB
• 淘汰策略：LRU（最近最少使用）

xyz追问：为什么图片会内存溢出？

1. 图片尺寸过大：4000x4000 的图片解码后占 64MB
2. 缓存不释放：没有限制缓存大小
3. 同时加载太多：列表快速滚动

解决：

• 使用 ResizeImage 限制解码尺寸
• 调整 ImageCache 大小
• 使用 cached_network_image 等库

串联知识点：

图片缓存是内存缓存，应用重启就没了。如果需要磁盘缓存（跨会话），需要使用专门的库（如 cached_network_image）。

九、内存与性能

Q19：Dart 的垃圾回收机制是什么？

核心答案：Dart 使用分代垃圾回收。年轻代使用复制算法（快速但需要双倍空间），老年代使用标记-清除-整理（节省空间但较慢）。

分代假设：

大多数对象很快死亡（临时变量、短期 Widget），少数对象活很久（State、全局对象）。

基于这个假设，年轻代频繁 GC、老年代较少 GC。

年轻代 GC：

• 分为 From 和 To 两个半空间
• 新对象分配在 From
• GC 时，存活对象复制到 To，From 一次性清空
• 交换 From 和 To

优点：速度快，无碎片 缺点：需要双倍空间

老年代 GC：

• 标记：找出所有存活对象
• 清除：释放死对象的内存
• 整理：移动对象，消除碎片

Dart 使用并发 GC，大部分工作在后台线程，减少主线程停顿。

xyz追问：Flutter 的 Widget 频繁创建会影响性能吗？

影响很小：

1. Widget 是小对象，分配快
2. Widget 存活时间短，年轻代 GC 效率高
3. 复制算法对短命对象友好

这就是 Flutter "每帧重建 Widget 树" 可行的原因。

串联知识点：

理解 GC 机制，就能理解为什么 const 重要——const 对象不参与 GC，直接从常量池读取。

Q20：Flutter 有哪些常见的性能优化手段？

核心答案：减少 Build 范围、减少 Layout 范围、减少 Paint 范围、减少图层、合理使用缓存。

Build 优化：

Layout 优化：

Paint 优化：

列表优化：

xyz追问：如何定位性能问题？

1. DevTools 的 Performance 面板
2. 看 Build/Layout/Paint 耗时
3. 看 GPU 线程是否拥堵
4. 使用 debugProfileBuildsEnabled 等 flag

串联知识点：

所有优化都指向一个核心——"减少不必要的工作"。理解渲染管线每个阶段做什么，就知道如何针对性优化。

十、高频对比题

Q21：StatelessWidget 和 StatefulWidget 的区别？

深入理解：

StatelessWidget 只是"简化版"——它也有 Element，只是 Element 没有持有 State。

StatefulWidget 拆分成两个对象（Widget + State）是为了分离"配置"和"状态"：

• Widget 可以频繁重建
• State 跨越 Widget 重建存活

Q22：Widget、Element、RenderObject 的对应关系？

关键理解：

并不是每个 Widget 都有 RenderObject！

StatelessWidget、StatefulWidget 只是"组合"其他 Widget，不直接渲染。真正渲染的是 RenderObjectWidget（如 Container 内部的 DecoratedBox、Padding）。

Q23：Hot Reload vs Hot Restart vs 完全重启？

Q24：JIT vs AOT？

深入理解：

Debug 用 JIT 是为了热重载；Release 用 AOT 是为了性能。

Q25：Future vs Stream？

十一、总结性问题

Q26：为什么 Flutter 能做到高性能跨平台？

核心答案：

1. 自绘引擎：不依赖原生控件，避免跨语言通信开销
2. Skia + GPU：直接 GPU 渲染，接近原生性能
3. AOT 编译：Release 模式直接运行机器码
4. 高效的 diff：三棵树设计，最小化更新
5. 智能边界：Relayout/Repaint Boundary 减少计算范围
6. 懒加载：Sliver 按需构建

Q27：Flutter 的设计哲学是什么？

1. 一切皆 Widget：统一的组件模型
2. 组合优于继承：小组件组合成大组件
3. 声明式 UI：描述目标状态，而非操作步骤
4. 不可变配置：Widget 不可变，变化时重建
5. 分层架构：关注点分离
6. 自绘引擎：完全控制渲染

Q28：如何回答"Flutter 的渲染原理"这种开放题？

答题框架：

1. 先说架构：三层架构，自绘引擎
2. 再说三棵树：Widget/Element/RenderObject 的分工
3. 然后说管线：VSync → Build → Layout → Paint → Composite → Rasterize
4. 最后说优化：边界机制、缓存复用

答题技巧：

• 从宏观到微观
• 主动引出下一个话题（"这里涉及到 xxx"）
• 用对比（"和 RN 不同的是..."）
• 说明设计原因（"这样设计是为了..."）

十二、知识点串联图谱

Flutter 高性能
    │
    ├── 自绘引擎 ────────────────────┐
    │                               │
    ├── 三棵树分离                    │
    │   ├── Widget 轻量 ← const 优化  │
    │   ├── Element 复用 ← Key 机制   │
    │   └── RenderObject 专注渲染     │
    │                               │
    ├── 渲染管线                      │
    │   ├── Build ← setState 批量     │
    │   ├── Layout ← Relayout Boundary│
    │   └── Paint ← Repaint Boundary  │
    │                               │
    ├── 异步机制                      │
    │   ├── Future ← Event Loop       │
    │   └── Isolate ← 多线程          │
    │                               │
    ├── 懒加载                        │
    │   └── Sliver ← ListView.builder │
    │                               │
    └── GC 友好                       │
        └── 分代回收 ← Widget 短命     │

以上就是 Flutter 底层原理的融会贯通版八股文。每个问题都可以层层深入，知识点之间相互串联，形成完整的知识体系。

KVC / KVO 与 ivar / property 的底层关系

关键词：KVC、KVO、ivar、property、Runtime、isa-swizzling

一、为什么 KVC / KVO 一定要和 ivar / property 一起理解

在 Objective-C 中：

• ivar 是数据的真实存储

• property 是访问 ivar 的规则

• KVC / KVO 本质上都是“访问规则之上的机制”

如果不理解 ivar 和 property，就一定理解不清 KVC / KVO

二、KVC（Key-Value Coding）底层原理

1️⃣ 什么是 KVC

KVC 是一种：

通过字符串 key 间接访问对象属性的机制

[person setValue:@"Hanqiu" forKey:@"name"];
NSString *name = [person valueForKey:@"name"];

2️⃣ KVC 的本质

• 本质是 一套查找规则

• 最终结果：

  • 要么调用方法

  • 要么直接访问 ivar

📌 KVC 并不依赖 property 是否存在

3️⃣ KVC 的 setValue:forKey: 查找顺序（重点）

当执行：

[person setValue:value forKey:@"name"];

查找顺序如下：

1. setName:
2. _setName:
3. +accessInstanceVariablesDirectly == YES ?
   3.1 _name
   3.2 _isName
   3.3 name
   3.4 isName
4. 调用 setValue:forUndefinedKey:

⚠️ 关键点

• 默认 +accessInstanceVariablesDirectly 返回 YES
• KVC 可以绕过 setter，直接改 ivar

4️⃣ KVC 的 valueForKey: 查找顺序

1. getName
2. name
3. isName
4. _name
5. _isName
6. 调用 valueForUndefinedKey:

5️⃣ KVC 与 ivar / property 的关系总结

KVC 是“方法优先，ivar 兜底”的机制****

三、KVO（Key-Value Observing）底层原理

1️⃣ 什么是 KVO

KVO 是一种：

监听属性变化的观察机制

[person addObserver:self
         forKeyPath:@"name"
            options:NSKeyValueObservingOptionNew
            context:nil];

2️⃣ KVO 的本质（一句话）

KVO 监听的是 setter 的调用，而不是 ivar 的变化

3️⃣ KVO 的底层实现机制（核心）

当第一次添加观察者时，系统会：

1. 动态生成一个子类（NSKVONotifying_XXX）
2. 修改对象的 isa 指针（isa-swizzling）
3. 在子类中重写 setter

Person
  ↑ isa
NSKVONotifying_Person

4️⃣ 重写的 setter 做了什么

伪代码如下：

- (void)setName:(id)value {
    [self willChangeValueForKey:@"name"];
    [super setName:value];
    [self didChangeValueForKey:@"name"];
}

👉 通知发生在 setter 内部

5️⃣ 为什么直接修改 ivar 不触发 KVO

_name = @"A";      // ❌ 不触发 KVO
self.name = @"B"; // ✅ 触发 KVO

原因：

• ivar 赋值不走 setter
• KVO 根本无法感知

四、KVO 与 property / ivar 的强关联关系

1️⃣ KVO 是否依赖 property？

📌 KVO 实际依赖的是 setter，而不是 property 关键字

2️⃣ 手动触发 KVO

如果你必须直接改 ivar：

[self willChangeValueForKey:@"name"];
_name = @"C";
[self didChangeValueForKey:@"name"];

五、KVC + KVO 联合场景分析（高频面试）

场景：用 KVC 修改属性，是否触发 KVO？

[person setValue:@"D" forKey:@"name"];

结论：

• 如果最终调用 setter → ✅ 触发 KVO

• 如果直接命中 ivar → ❌ 不触发

是否触发，取决于 KVC 查找路径

六、Runtime 视角看 KVC / KVO

1️⃣ KVC 使用的 Runtime 能力

• objc_msgSend
• class_getInstanceVariable
• object_setIvar

2️⃣ KVO 使用的 Runtime 能力

• objc_allocateClassPair
• object_setClass
• 动态方法重写

七、常见面试陷阱总结

❌ 误区 1：KVO 监听的是 ivar

❌ 错

✔ 监听的是 setter 的调用

❌ 误区 2：没有 property 就不能 KVO

❌ 错

✔ 只要有 setter 方法即可

❌ 误区 3：KVC 一定会触发 KVO

❌ 错

✔ 是否触发取决于是否调用 setter

八、一张关系总图（文字版）

           ┌──────────────┐
           │   property   │
           │ getter/setter│
           └──────┬───────┘
                  │
        KVO 监听   │ setter
                  ▼
               ivar（真实数据）
                  ▲
                  │
            KVC 兜底访问

九、终极总结

KVC 是“方法优先、ivar 兜底”的键值访问机制；KVO 是通过 isa-swizzling 重写 setter 来监听属性变化的机制，本质与 ivar 无关，只与 setter 是否被调用有关。