iOS开发实战：HarfBuzz文本塑形引擎API详解与Swift集成指南

1. 项目概述：为什么我们需要深入HarfBuzz的API？

如果你在iOS或者任何涉及复杂文本渲染的平台上做过开发，大概率遇到过这样的问题：一段阿拉伯文或泰文显示出来位置错乱，一个精心设计的“fi”连字怎么也显示不出来，或者自定义字体在特定字号下间距诡异。这些问题背后，往往不是简单的UILabel或CoreText能解决的，它们触及了文本渲染的核心——文字塑形。

HarfBuzz就是这个领域的“隐形冠军”。它是一个开源的文本塑形引擎，被广泛应用于Android、Chrome、Firefox、Qt等众多知名项目中。简单来说，它的工作是把一串Unicode字符，根据字体文件（如.ttf, .otf）中复杂的规则（比如连字、字距调整、上下文替换），转换成一系列需要绘制的字形以及每个字形的精确位置。iOS/macOS自带的CoreText底层也使用了HarfBuzz（或其变体），但直接使用HarfBuzz的C API，能让我们获得更底层的控制力，实现一些高级定制，比如精确控制连字特性、实现自定义的字体回退逻辑，或者构建自己的排版引擎。

网上关于HarfBuzz的概览和概念文章不少，但一涉及到具体怎么用，尤其是如何在Swift/iOS环境下把这一套C API玩转，资料就变得零散且晦涩。很多人看了理论还是一头雾水，不知道从何下手。这篇文章的目的，就是填补这个缺口。我将以一个在iOS项目中实际集成并使用了HarfBuzz的开发者视角，带你逐一拆解五大核心API：hb-blob、hb-face、hb-font、hb-buffer和hb-shape。我不会面面俱到地罗列所有函数，而是聚焦于那些在实战中最常用、最容易踩坑的关键API，并通过完整的Swift示例，让你能真正把代码“抄”过去，跑起来，理解每一步背后的“为什么”。

无论你是想深入理解文本渲染原理，还是需要在App中实现多语言高级排版、自定义文本编辑器，或者仅仅是好奇CoreText下面一层发生了什么，这篇文章都能给你提供一条清晰的实践路径。我们直接从内存中的字体数据开始，一步步走到屏幕上精确绘制的字形。

2. 核心API深度解析与实战要点

直接调用C库，尤其是在Swift这种内存管理严格的语言里，最大的挑战往往不是逻辑本身，而是资源管理和数据转换。HarfBuzz的API设计遵循着清晰的层次结构：数据（Blob） -> 字体定义（Face） -> 字体实例（Font） -> 处理容器（Buffer） -> 执行塑形（Shape）。理解每一层的职责和生命周期，是避免内存泄漏和崩溃的关键。

2.1 hb-blob：字体数据的“安全包装器”

hb_blob_t是HarfBuzz世界里一切的开端。你可以把它理解为一个智能指针，它封装了一段原始的二进制数据（通常就是整个字体文件的内容），并负责管理这段数据的内存生命周期。在Swift中操作C的二进制数据，首要原则就是明确所有权和生命周期。

2.1.1 创建Blob的两种方式与内存策略抉择

创建Blob主要有两种方式，选择哪一种取决于你的字体数据来源。

方式一：从内存数据创建 (hb_blob_create)当你已经将字体文件读入到Data或[UInt8]数组时，使用这个方法。它的核心在于hb_memory_mode_t参数，这个参数直接决定了性能和安全性，选错了可能导致崩溃。

// 假设我们有一个字体文件的 Data let fontData: Data = // ... 从Bundle或网络加载的字体数据 let blob = fontData.withUnsafeBytes { (rawBufferPointer: UnsafeRawBufferPointer) -> OpaquePointer? in // 1. 将 UnsafeRawBufferPointer 转换为指向 CChar (Int8) 的指针 let charPtr = rawBufferPointer.baseAddress?.bindMemory(to: CChar.self, capacity: fontData.count) // 2. 创建Blob，使用 DUPLICATE 模式最安全 return hb_blob_create(charPtr, UInt32(fontData.count), HB_MEMORY_MODE_DUPLICATE, nil, nil) }

这里有几个关键点：

1. withUnsafeBytes的使用：这是Swift安全访问底层字节的标准做法。闭包内的rawBufferPointer仅在闭包执行期间有效。绝对不能在闭包外保存或使用这个指针。
2. HB_MEMORY_MODE_DUPLICATE的选择：我强烈建议在Swift中始终使用这个模式。它会让HarfBuzz内部复制一份数据。虽然有一次内存拷贝的开销，但它彻底解耦了SwiftData的生命周期和HarfBuzz对象的生命周期。你的fontData可以立即被释放，Blob依然有效。如果使用HB_MEMORY_MODE_READONLY，你必须保证原始的fontData在整个HarfBuzz对象树（Blob -> Face -> Font）存活期间都保持有效且不被修改，这在复杂的异步或自动释放池场景下极易出错。
3. 指针类型转换：hb_blob_create期望一个const char*，在Swift中对应UnsafePointer<CChar>?。通过bindMemory进行正确的类型绑定是必要的。

方式二：从文件路径创建 (hb_blob_create_from_file)如果你的字体文件已经在磁盘上，这是更高效的方式。

let fontURL = Bundle.main.url(forResource: "MyFont", withExtension: "ttf")! let blob = fontURL.path.withCString { filePathPtr in hb_blob_create_from_file(filePathPtr) }

注意：withCString会将Swift字符串转换为C字符串指针，同样只在闭包内有效。hb_blob_create_from_file内部通常会使用mmap来映射文件，这意味着：

• 优点：可能共享系统的字体缓存，减少物理内存占用，并且避免了将整个文件读入内存。
• 缺点：文件在映射期间不能被删除或移动。同时，你需要确保应用有权限访问该路径。

实操心得：内存模式选择在移动端，我几乎总是选择HB_MEMORY_MODE_DUPLICATE。理由很简单：安全第一。一次字体数据的拷贝（通常几百KB到几MB）对现代设备的内存和性能影响微乎其微，但因此避免的野指针崩溃风险是巨大的。只有在处理极大字体文件且内存极度受限的特定场景下，我才会考虑基于mmap的文件映射方式（即hb_blob_create_from_file）。

2.1.2 Blob的生命周期管理

HarfBuzz使用引用计数。hb_blob_create或hb_blob_create_from_file返回的blob，其引用计数为1。当你将它传递给hb_face_create后，face内部会对其reference，此时引用计数变为2。随后，你应该立即调用hb_blob_destroy(blob)。这并不会立即释放内存，只是将计数减回1。真正的释放会发生在face也被销毁时。这是一个固定模式：创建 -> 传递给下一级对象 -> 立即销毁。

let blob = hb_blob_create_from_file(...) let face = hb_face_create(blob, 0) // face 对 blob 进行了引用 hb_blob_destroy(blob) // 立即销毁我们持有的引用，现在blob由face管理 // ... 后续使用 face

2.2 hb-face：字体信息的“解析器”

hb_face_t代表一个具体的字体。它负责解析Blob中的二进制数据，构建起对字体内部各种表（Table）的访问能力，比如获取字形轮廓的glyf表、进行替换的GSUB表、调整位置的GPOS表，以及将字符码映射到字形索引的cmap表。

2.2.1 创建Face与字体集合索引

创建Face很简单，但要注意第二个参数index。

let face = hb_face_create(blob, 0)

对于常见的.ttf或.otf文件（单一字体），index传0。但如果你的字体文件是.ttc（TrueType Collection，字体集合），这个index就用于选择集合中的第几个字体。你可以通过遍历index并尝试创建face，直到失败（返回nil）来获取集合中的字体总数。

2.2.2 关键信息获取：UPEM与Unicode支持

hb_face_get_upem函数返回字体的unitsPerEm值。这是一个非常重要的概念。字体设计师是在一个抽象的坐标系中设计字形的，这个坐标系的单位就是unitsPerEm。常见的值是2048或1000。当我们在屏幕上以fontSize（例如16pt）渲染时，需要将字体设计单位的坐标缩放至像素单位。换算公式为：像素值 = (设计单位值 * fontSize) / upem。

let upem = hb_face_get_upem(face) // 例如 2048

hb_face_collect_unicodes函数极其有用，它能获取字体文件所支持的所有Unicode码点。这在实现字体回退时是核心工具。当系统字体不支持某个字符时，你可以遍历自己的备用字体列表，用这个函数快速检查哪个字体支持该字符。

let unicodeSet = hb_set_create() hb_face_collect_unicodes(face, unicodeSet) let targetChar: Unicode.Scalar = "𓀀" // 一个古埃及象形文字 let targetCodePoint = UInt32(targetChar.value) if hb_set_has(unicodeSet, targetCodePoint) != 0 { print("该字体支持字符 \(targetChar)") } else { print("字体不支持，需要回退") } // 不要忘记销毁 set hb_set_destroy(unicodeSet)

注意事项：hb_set_t对象也需要手动管理生命周期（create/destroy）。hb_face_collect_unicodes的遍历是基于cmap表的，对于超大字集字体，这个操作可能有开销，建议缓存结果。

2.3 hb-font：可配置的“字体实例”

hb_font_t是hb_face_t的一个具体实例化。你可以把它类比为UIFont，它是带有具体大小、缩放、变形等属性的“活”的字体。同一个Face可以创建出无数个不同大小的Font。

2.3.1 创建Font与关键设置

创建Font后，有两项设置至关重要，缺少它们会导致塑形失败或结果异常。

guard let font = hb_font_create(face) else { return } // 1. 设置OpenType函数集（必须！） hb_ot_font_set_funcs(font) // 2. 设置字体缩放（即字号） let fontSize: CGFloat = 18.0 let scale = Int32(fontSize * 64) // 转换为 26.6 定点数 hb_font_set_scale(font, scale, scale)

1. hb_ot_font_set_funcs(font)：这行代码告诉HarfBuzz，使用其内置的OpenType函数来从字体中获取字形轮廓、度量信息等。对于现代字体（.otf, .ttf），这是必须调用的。如果忘记，后续的hb_shape可能无法获取字形数据，或者回退到非常基础的渲染，导致连字、字距调整等高级特性失效。
2. hb_font_set_scale：这里设置了字体的缩放比例，实际上就是设置了字号。HarfBuzz内部使用26.6定点数来存储坐标和度量值。这是一种用整数表示小数的高性能方式：将浮点数乘以64（2^6）后取整。所以18.0 * 64 = 1152。这个缩放值会影响所有后续获取的advance（前进量）、offset（偏移量）等位置信息。

2.3.2 字形查询与变体选择

hb_font_get_glyph函数用于查询某个Unicode码点在当前字体中对应的字形ID（glyph ID）。这是字符到字形映射的第一步。

var glyphId: hb_codepoint_t = 0 let success = hb_font_get_glyph(font, unicode, variationSelector, &glyphId)

• unicode: 要查询的Unicode码点。
• variationSelector:变体选择符。这是一个高级功能。例如，同一个汉字“户”可能有“戶”（U+6236）和“户”（U+6237）等不同变体。Unicode通过变体选择序列来指定。如果你需要获取特定变体，就传入对应的选择符码点；如果只需要默认字形，传0。
• glyphId: 输出参数，查询成功时存放字形ID。这个ID是字体内部的索引，用于后续的绘制（例如传给Core Graphics的CTFontDrawGlyphs）。

2.4 hb-buffer：塑形过程的“工作台”

hb_buffer_t是塑形操作的输入输出缓冲区。你先把要处理的文本放进去，设置一些属性，然后交给hb_shape处理，处理完的结果再从里面取出来。

2.4.1 添加文本与编码

添加文本时，需要根据字符串的原始编码选择对应的函数。在Swift中，我们通常处理UTF-8或UTF-16。

let buffer = hb_buffer_create() let text = "Hello, 世界！" // 方式一：UTF-8 (Swift String 内部通常是UTF-8) text.withCString { utf8Ptr in hb_buffer_add_utf8(buffer, utf8Ptr, -1, 0, -1) } // 方式二：UTF-16 (NSString 或某些场景) let utf16Text = text as NSString let utf16Chars = utf16Text.utf16 utf16Chars.withContiguousStorageIfAvailable { ptr in hb_buffer_add_utf16(buffer, ptr.baseAddress, Int32(ptr.count), 0, -1) }

参数解释：-1表示自动计算字符串长度（直到遇到NULL终止符或数组末尾），0表示从开头开始，最后一个-1表示处理整个字符串。如果你想处理字符串的一部分，可以调整item_offset和item_length。

2.4.2 设置文本属性：脚本、语言与方向

文本塑形需要知道文本的书写方向（LTR从左到右，RTL从右到左）、文字系统（拉丁文、阿拉伯文、梵文等）和语言（用于某些上下文替换规则）。你可以手动设置：

hb_buffer_set_direction(buffer, HB_DIRECTION_LTR) // 或 HB_DIRECTION_RTL hb_buffer_set_script(buffer, hb_script_from_string("Latn", -1)) // 拉丁文 hb_buffer_set_language(buffer, hb_language_from_string("en", -1)) // 英语

更常用的方法是让HarfBuzz自动猜测：

hb_buffer_guess_segment_properties(buffer)

这个函数会分析buffer中的文本内容（通常是第一个字符），来推断出最可能的属性。对于纯文本，这很方便。但对于混合了多种语言/脚本的文本，它的猜测可能不准。例如，一段以英文开头但包含阿拉伯文的文本，可能会被错误地猜测为LTR。在复杂场景下，更可靠的做法是由上层业务逻辑预先对文本进行分段，然后为每一段buffer手动设置正确的属性。

2.5 hb-shape：执行塑形的“引擎”

这是最核心的一步。hb_shape函数接收配置好的font和填充了文本的buffer，执行一整套复杂的OpenType规则处理，最终将buffer中的字符序列转换为一串字形序列及其位置信息。

// features 参数可以启用或禁用特定的OpenType特性，如连字、小型大写字母等。 // 传 nil 表示使用字体默认特性。 hb_shape(font, buffer, nil, 0)

塑形完成后，所有的结果都存储在buffer中。我们需要通过两个函数来提取结果。

2.5.1 获取字形信息 (hb_buffer_get_glyph_infos)

这个函数返回一个hb_glyph_info_t数组，包含每个输出字形的核心信息。

var glyphCount: UInt32 = 0 let infosPtr = hb_buffer_get_glyph_infos(buffer, &glyphCount) let infos = Array(UnsafeBufferPointer(start: infosPtr, count: Int(glyphCount))) for info in infos { let glyphID = info.codepoint // 字形ID，用于绘制 let cluster = info.cluster // **关键：关联回原始文本的字节索引** }

cluster字段是理解输入与输出映射关系的关键。它记录了该字形对应到原始输入字符串（UTF-8编码）中的字节偏移量。

• 一对多：一个字符（如阿拉伯语的“ل”+“ا”连成“لا”）输出为一个字形，这个字形的cluster指向第一个字符的字节索引。
• 多对一：一个字符（如某些复杂脚本的分解）可能输出为多个字形，这些字形会有相同的cluster值。
• 应用：实现文本选区高亮、光标定位时，你需要根据字符索引（或字节索引）找到对应的字形范围，cluster就是桥梁。

2.5.2 获取字形位置 (hb_buffer_get_glyph_positions)

这个函数返回一个hb_glyph_position_t数组，包含每个字形的精确排版位置。

let positionsPtr = hb_buffer_get_glyph_positions(buffer, &glyphCount) let positions = Array(UnsafeBufferPointer(start: positionsPtr, count: Int(glyphCount))) for pos in positions { let x_advance = pos.x_advance // x方向前进量 (26.6格式) let y_advance = pos.y_advance // y方向前进量 let x_offset = pos.x_offset // x方向绘制偏移 let y_offset = pos.y_offset // y方向绘制偏移 }

• x_advance,y_advance：这是前进量。绘制完当前字形后，“光标”应该移动多远才能开始绘制下一个字形。对于水平文本，y_advance通常为0。这个值已经包含了字距调整等所有GPOS规则计算后的结果。
• x_offset,y_offset：这是偏移量。字形实际绘制的位置，相对于“光标”的偏移。例如，一个重音符号（如´）的y_offset会是负值，使其绘制在基础字母的上方。

26.6定点数转换：这些位置值都是26.6格式的整数。要得到真实的点（point）或像素值，需要除以64.0。

let advanceInPoints = Double(x_advance) / 64.0 let offsetInPoints = Double(x_offset) / 64.0

3. 完整iOS/Swift实战示例：从字体文件到屏幕绘制

理论讲完了，我们来看一个完整的、可运行的Swift示例。这个例子将展示从加载字体、配置、塑形到最终计算绘制位置的完整流程，并处理了C指针与Swift内存安全之间的所有细节。

import Foundation import CoreText import HarfBuzz // 假设已通过Swift Package Manager或CocoaPods引入 class HarfBuzzShapingDemo { /// 对一段文本进行HarfBuzz塑形，并打印详细结果 /// - Parameters: /// - text: 要塑形的文本 /// - fontName: 字体在Bundle中的名称（不带后缀） /// - fontSize: 字体大小（点） func shapeAndAnalyze(text: String, fontName: String, fontSize: CGFloat) { // ===== 第1步：准备字体数据 ===== guard let fontURL = Bundle.main.url(forResource: fontName, withExtension: "ttf") else { print("错误：找不到字体文件 \(fontName)") return } // 使用文件路径创建Blob（效率较高） let blob = fontURL.path.withCString { filePathPtr in hb_blob_create_from_file(filePathPtr) } guard let blob = blob else { print("错误：无法从文件创建Blob") return } // ===== 第2步：创建字体Face ===== // 第二个参数0表示字体索引（对于.ttc集合字体有用） let face = hb_face_create(blob, 0) hb_blob_destroy(blob) // Blob已被Face引用，可以安全销毁我们的引用 guard let face = face else { print("错误：无法从Blob创建Face") return } // ===== 第3步：创建可配置的字体实例 ===== let font = hb_font_create(face) guard let font = font else { print("错误：无法创建Font") hb_face_destroy(face) return } // **关键设置1：启用OpenType函数** hb_ot_font_set_funcs(font) // **关键设置2：设置字体大小（缩放）** let scale = Int32(fontSize * 64.0) // 转换为26.6定点数 hb_font_set_scale(font, scale, scale) // 可选：设置斜体合成（模拟斜体） // hb_font_set_synthetic_slant(font, 0.2) // 20度斜体 // ===== 第4步：创建并设置缓冲区 ===== let buffer = hb_buffer_create() guard let buffer = buffer else { print("错误：无法创建Buffer") hb_font_destroy(font) hb_face_destroy(face) return } // 添加UTF-8编码的文本到缓冲区 text.withCString { utf8Ptr in hb_buffer_add_utf8(buffer, utf8Ptr, -1, 0, -1) } // 自动猜测文本属性（方向、脚本、语言） hb_buffer_guess_segment_properties(buffer) // 你也可以手动设置，例如对于阿拉伯文： // hb_buffer_set_direction(buffer, HB_DIRECTION_RTL) // hb_buffer_set_script(buffer, hb_script_from_string("Arab", -1)) // ===== 第5步：执行塑形 ===== // 第四个参数是特性数组，nil表示使用字体默认特性 hb_shape(font, buffer, nil, 0) // ===== 第6步：提取并处理塑形结果 ===== var glyphCount: UInt32 = 0 guard let infosPtr = hb_buffer_get_glyph_infos(buffer, &glyphCount), let positionsPtr = hb_buffer_get_glyph_positions(buffer, &glyphCount) else { print("错误：无法获取塑形结果") cleanup(buffer: buffer, font: font, face: face) return } // 将不安全的C指针转换为Swift数组以便安全遍历 let infos = Array(UnsafeBufferPointer(start: infosPtr, count: Int(glyphCount))) let positions = Array(UnsafeBufferPointer(start: positionsPtr, count: Int(glyphCount))) print("\n======= HarfBuzz 塑形分析报告 =======") print("文本: \"\(text)\"") print("字体: \(fontName), 大小: \(fontSize)pt") print("输出字形数量: \(glyphCount)") print("----------------------------------------") var currentX: Double = 0.0 var currentY: Double = 0.0 for i in 0..<infos.count { let info = infos[i] let pos = positions[i] // 转换26.6定点数为浮点数 let xAdv = Double(pos.x_advance) / 64.0 let yAdv = Double(pos.y_advance) / 64.0 let xOff = Double(pos.x_offset) / 64.0 let yOff = Double(pos.y_offset) / 64.0 // 计算该字形的实际绘制位置 let drawX = currentX + xOff let drawY = currentY + yOff print("字形 #\(i):") print(" Glyph ID: \(info.codepoint)") print(" 关联文本索引 (cluster): \(info.cluster)") print(" 前进量: (x: \(String(format: "%.2f", xAdv)), y: \(String(format: "%.2f", yAdv))) pt") print(" 偏移量: (x: \(String(format: "%.2f", xOff)), y: \(String(format: "%.2f", yOff))) pt") print(" 绘制位置: (x: \(String(format: "%.2f", drawX)), y: \(String(format: "%.2f", drawY))) pt") print(" --") // 更新“光标”位置，为下一个字形做准备 currentX += xAdv currentY += yAdv } print("----------------------------------------") print("文本总宽度: \(String(format: "%.2f", currentX)) pt") print("========================================\n") // ===== 第7步：资源清理 ===== cleanup(buffer: buffer, font: font, face: face) } /// 统一的资源清理函数，按创建相反的顺序销毁 private func cleanup(buffer: OpaquePointer?, font: OpaquePointer?, face: OpaquePointer?) { if let buffer = buffer { hb_buffer_destroy(buffer) } if let font = font { hb_font_destroy(font) } if let face = face { hb_face_destroy(face) } } /// 演示：使用塑形结果进行简单绘制（概念性代码） func demonstrateDrawing(with text: String, in context: CGContext, at point: CGPoint) { // ... 此处省略具体的Core Graphics绘制代码 ... // 核心绘制循环逻辑如下： /* var penX = point.x let penY = point.y for i in 0..<glyphCount { let info = infos[i] let pos = positions[i] let glyphId = CGGlyph(info.codepoint) let drawX = penX + CGFloat(pos.x_offset) / 64.0 let drawY = penY - CGFloat(pos.y_offset) / 64.0 // 注意：Core Graphics Y轴向下，可能需要取反 // 1. 将笔移动到 drawX, drawY // 2. 使用 CTFontDrawGlyphs 绘制 glyphId CTFontDrawGlyphs(ctFont, &glyphId, &CGPoint(x: drawX, y: drawY), 1, context) // 3. 笔的位置前进 penX += CGFloat(pos.x_advance) / 64.0 penY += CGFloat(pos.y_advance) / 64.0 // 通常是0 } */ } } // 使用示例 let demo = HarfBuzzShapingDemo() demo.shapeAndAnalyze(text: "Hello, World! fi", fontName: "Helvetica", fontSize: 36.0) // 尝试连字 demo.shapeAndAnalyze(text: "affluent office", fontName: "TimesNewRomanPSMT", fontSize: 36.0) // 可能会看到 "ff", "ffi", "fi" 连字 // 尝试复杂文本 demo.shapeAndAnalyze(text: "مرحبا بالعالم", fontName: "GeezaPro", fontSize: 36.0) // 阿拉伯文，RTL方向

运行这段代码，你会看到控制台打印出每个字形的ID、关联的文本索引、前进量、偏移量和计算出的绘制位置。对于包含连字（如“fi”）的文本，你会发现输出的字形数量少于输入字符数，并且cluster值揭示了这种映射关系。

4. 常见问题、调试技巧与性能优化

在实际集成HarfBuzz的过程中，你肯定会遇到各种问题。下面是我踩过的一些坑和总结的经验。

4.1 内存管理与崩溃排查

这是新手最容易出问题的地方。HarfBuzz对象使用引用计数，必须成对调用create/destroy。

• 问题：随机崩溃，错误信息可能关于野指针。
• 排查清单：
  1. 检查销毁顺序：应该按创建顺序的逆序销毁。通常是Buffer -> Font -> Face -> Blob。但因为我们通常在创建Face后就销毁了Blob的引用，所以常见顺序是Buffer -> Font -> Face。
  2. 检查指针有效性：确保传递给HarfBuzz API的指针在调用期间有效。特别是withUnsafeBytes和withCString闭包内的指针，绝不能传出闭包外使用。
  3. 使用Address Sanitizer：在Xcode中启用Address Sanitizer，它能帮你快速定位内存滥用问题。
  4. 封装资源管理：像上面示例一样，使用一个cleanup函数或defer语句来确保资源被释放，即使发生错误。

  func safeShape() { guard let blob = hb_blob_create(...) else { return } defer { hb_blob_destroy(blob) } // 确保退出作用域时销毁 guard let face = hb_face_create(blob, 0) else { return } defer { hb_face_destroy(face) } // ... 其他操作 }

4.2 塑形结果异常或无效果

• 问题：文本塑形后，字形位置看起来和没处理一样，或者连字没有出现。
• 排查步骤：
  1. 确认hb_ot_font_set_funcs被调用：这是最常见的原因。没有它，HarfBuzz无法正确读取字体的OpenType特性表。
  2. 检查字体文件：确保你使用的字体文件确实包含了你期望的OpenType特性（如连字、字距）。可以用字体查看工具（如FontForge, Glyphs）检查。
  3. 检查hb_font_set_scale：如果缩放设置为0或极小，所有位置信息都会是0。
  4. 验证文本属性：对于从右向左（RTL）的文本，必须正确设置hb_buffer_set_direction(buffer, HB_DIRECTION_RTL)。hb_buffer_guess_segment_properties对纯RTL文本有效，但对混合文本可能不准。
  5. 检查features参数：hb_shape的第三个参数可以用于显式启用或禁用特性。如果你传入了自定义的hb_feature_t数组，可能会覆盖字体默认行为。尝试传入nil和0看看是否恢复正常。

4.3 性能优化考量

在iOS上处理大量文本（如富文本编辑器）时，性能很重要。

• 复用对象：频繁创建和销毁hb_font_t和hb_face_t是有开销的。对于同一种字体，应该缓存这些对象。可以创建一个FontCache，以字体PostScript名和大小为键缓存hb_font_t。
• 批量塑形：避免对每个短字符串都调用一次完整的hb_shape流程。如果可能，将相邻的、属性相同的文本合并到一个buffer中进行塑形。
• 异步操作：塑形计算是CPU密集型的。对于非常长的文本（如整篇文章），考虑在后台线程进行塑形，完成后再回到主线程进行绘制。
• 谨慎使用hb_face_collect_unicodes：对于大型字体，这个操作可能较慢。如果是为了字体回退，可以考虑只收集常用区段的码点，或者缓存结果。

4.4 与CoreText的协作与对比

你可能会问，既然iOS有CoreText，为什么还要用HarfBuzz？

• 更底层的控制：CoreText是一个黑盒，你无法精细控制其塑形过程。HarfBuzz允许你指定或禁用特定的OpenType特性，访问原始的cluster映射，这在实现自定义文本编辑器、语法高亮或复杂文本布局时是必须的。
• 跨平台一致性：如果你的代码需要同时在iOS、Android和Web上运行，使用HarfBuzz可以保证不同平台上的文本排版结果高度一致。
• 高级排版特性：对于一些极其复杂的排版需求（如某些学术符号排版、古文字排版），直接使用HarfBuzz可能比尝试配置CoreText更直接。

然而，在大多数标准UI显示场景下，CoreText或UILabel/UITextView仍然是更简单、更高效的选择。HarfBuzz是你工具箱里的高级武器，用于解决那些CoreText解决不了或解决不好的特定问题。

集成时，一个常见的模式是：使用HarfBuzz进行塑形和布局计算，得到字形ID和位置，然后使用CTFontDrawGlyphs配合从同一字体创建的CTFont进行实际绘制。这样可以兼顾灵活性和系统渲染的优化。

最后，调试时多打印中间结果，从cluster映射和advance/offset值入手，逐步验证每一步是否符合预期。理解数据流：字符 -> (cluster映射) -> 字形ID -> (位置计算) -> 绘制坐标，是驾驭HarfBuzz的关键。