markbase/docs/FSKIT_ERROR_GUIDE.md

FSKit 编译错误解决指南 ⭐⭐⭐⭐⭐

HelloFS 错误分析

错误 1: Entry Point 类名错误

错误信息：

error: cannot find type 'UnaryFilesystemExtension' in scope

原因：使用了错误的类名（理论分析）

解决方案：

// 错误 ❌
class HelloFSExtension: UnaryFilesystemExtension {
    // ...
}

// 正确 ✅
struct HelloFSExtension: FSKitExtension {
    func filesystem() -> FSFileSystem {
        return HelloFS()
    }
}

---

错误 2: 文件系统基类错误

错误信息：

error: cannot find type 'FSUnaryFileSystem' in scope

原因：使用了错误的基类名

解决方案：

// 错误 ❌
class HelloFS: FSUnaryFileSystem, FSUnaryFileSystemOperations {
    // ...
}

// 正确 ✅
class HelloFS: FSFileSystem {
    func probeResource(...) { }
    func loadResource(...) { }
}

---

错误 3: 方法签名错误

错误信息：

error: method does not override any method from its superclass

原因：没有使用 replyHandler 和 options 参数

解决方案：

// 错误 ❌
func start() -> Bool
func handleMountRequest(request: FSMountRequest) -> FSVolume?

// 正确 ✅
func probeResource(
    resource: FSResource,
    replyHandler: @escaping (FSProbeResult?) -> Void
)

func loadResource(
    resource: FSResource,
    options: FSTaskOptions,
    replyHandler: @escaping (Error?) -> Void
)

---

错误 4: Volume Protocols 缺失

错误信息：

error: type 'HelloVolume' does not conform to protocol 'FSVolumeOperations'

原因：FSVolume 需要实现 13+ protocols

解决方案：

class HelloVolume: FSVolume {
    // ...
}

// 必须实现所有 protocols ✅
extension HelloVolume: FSVolume.PathConfOperations { }
extension HelloVolume: FSVolume.OpenCloseOperations { }
extension HelloVolume: FSVolume.IOOperations { }
extension HelloVolume: FSVolume.DirectoryOperations { }
extension HelloVolume: FSVolume.AttributeOperations { }
extension HelloVolume: FSVolume.XattrOperations { }
extension HelloVolume: FSVolume.ActiveOperations { }
extension HelloVolume: FSVolume.CloneOperations { }
// ... 共 13+ protocols

---

错误 5: Info.plist 配置缺失

后果：Extension 无法加载，不会出现在 System Settings

解决方案：创建 Info.plist 并添加 FSExtension 配置

<key>FSExtension</key>
<dict>
    <key>FSExtensionPersonality</key>
    <string>HelloFS</string>
    <!-- 必需配置 -->
</dict>

---

错误 6: Entitlements 缺失

后果：Extension 无法运行，权限错误

解决方案：添加 entitlements

<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.files.user-selected.read-write</key>
<true/>

---

修正步骤清单

Step 1: 修正 Entry Point ✅

• 改 UnaryFilesystemExtension → FSKitExtension

Step 2: 修正 Filesystem Base ✅

• 改 FSUnaryFileSystem → FSFileSystem

Step 3: 修正 Method Signatures ✅

• 添加 replyHandler 参数
• 添加 options: FSTaskOptions 参数

Step 4: 实现 Volume Protocols ✅

• 实现 FSVolume.PathConfOperations
• 实现 FSVolume.OpenCloseOperations
• 实现 FSVolume.IOOperations
• 实现 FSVolume.DirectoryOperations
• 实现 FSVolume.AttributeOperations
• 实现 FSVolume.XattrOperations
• 等等 13+ protocols

Step 5: 创建 Info.plist ✅

• FSExtension 配置
• NSExtension 配置

Step 6: 创建 Entitlements ✅

• App Sandbox
• File access

Step 7: 测试编译 ✅

• swift build
• 验证无错误

Step 8: 测试挂载 ✅

• 创建 block device
• mount -t HelloFS
• 验证功能

---