【文章翻譯】Announcing stable direct native interoperability

發表於 2026-11-12 更新於 2026-11-13 分類於 Flutter

【文章內容使用 Gemini 2.5 Flash 自動翻譯產生】

原文：https://flutter.dev/blog/stable-native-interop

宣布穩定直接原生互通性

FFIgen for Objective-C 和 JNIgen for Java/Kotlin 現已穩定，Pigeon 將它們投入使用，因此您的 Plugin 可以直接呼叫原生程式碼

由 Mariam Hasnany 發佈
2026 年 11 月 12 日 · 閱讀時間 6 分鐘

去年，我們介紹了我們對直接原生互通性的願景，旨在讓 Flutter 開發人員更輕鬆地存取平台 API。我們的最初目標是解決使用平台通道在 Android 和 iOS 上呼叫原生 API 的基本挑戰。

今天，我們正朝著這個目標邁出巨大一步。我們很高興地宣布，FFIgen for Objective-C 和 JNIgen 現已穩定，並且 Pigeon 已經進化，將這些工具應用於幕後。

這是我們構建 Plugin 方式的一大轉變。我們正在從傳統平台通道的序列化和延遲轉向直接、型別安全、令人難以置信的快速程式碼生成綁定。

我們為什麼要建立新的東西

如果您曾經構建過 Flutter Plugin，您可能已經與平台通道搏鬥過。多年來，它們一直是存取原生 API 的預設方式，但它們帶來了許多摩擦。

平台通道依賴於訊息傳遞。當您的 Dart 程式碼想要與 iOS 或 Android 通訊時，它必須將資料序列化為二進位緩衝區，透過橋接器發送，在原生端反序列化，運行原生 API，然後反轉整個過程以將結果發送回來。

這個過程耗時、容易出錯，並可能導致效能問題。如果原生 API 發生變化，您必須手動更新兩端的基於字串的訊息處理器。此外，平台通道是嚴格非同步的，以保持 UI 的響應性，這導致了大量的非同步樣板程式碼和潛在的延遲，對於應該是即時的原生呼叫。

Pigeon 解決了部分問題。您在 Dart 檔案中描述 API 一次，Pigeon 會為兩端生成型別安全的程式碼，因此方法名稱中的拼寫錯誤會變成編譯時錯誤，而不是運行時錯誤。但實際上，Pigeon 仍然生成平台通道程式碼，因此每次呼叫都會進行相同的序列化、非同步往返。

這個往返就是我們著手解決的問題：我們希望 Dart 直接呼叫原生程式碼。

建立直接路徑

我們首先構建了程式碼產生器 FFIgen 和 JNIgen，它們為原生 API 建立 Dart 綁定。您的 Dart 程式碼不是傳遞訊息，而是透過 FFI (外部函式介面) 或 JNI (Java 原生介面) 直接呼叫原生程式碼：

FFIgen 為 C 和 Objective-C API 產生綁定。C 的 FFIgen 已經穩定多年，而從今天起，Objective-C 的 FFIgen 也穩定。
JNIgen 從 Android 系統 API 到您自己的 JAR 和 AAR，為 Java 和 Kotlin API 產生綁定。從今天起，JNIgen 穩定。

直接呼叫解鎖了使用訊息傳遞非常困難的事情，例如同步呼叫原生 API，或在 Dart 和原生程式碼之間傳遞原生物件和大量原始資料而無需序列化步驟。您甚至可以直接從 Dart 呼叫平台 API，通常無需編寫任何原生程式碼。而且因為 FFIgen 和 JNIgen 產生的是純 Dart 程式碼，它們可以在任何 Dart 專案中工作，無論有沒有 Flutter。

原始 FFIgen 和 JNIgen 綁定適用於單平台程式碼和 C-ABI 函式庫。無論您是呼叫僅限 Android 的 API、使用 iOS 框架，還是包裝像 sqlite3 這樣的 C 函式庫，都有一個原生 API 可以綁定，綁定讓您直接存取所有這些。

透過設計，FFIgen 和 JNIgen 是低階的，並透過直接記憶體存取為您提供更好的效能，但在某些情況下，這會以記憶體管理和執行緒處理成為使用它們的開發人員的責任為代價。

預覽：帶有原生互通的 Pigeon

許多 Flutter Plugin 跨越多個平台（例如 Android + iOS）。這也意味著每個平台都有單獨的綁定集，加上您自己的 Dart 層來保持它們的一致性。這種開發人員體驗不像我們希望的那樣沒有摩擦。

因此，我們決定將 Pigeon 的開發人員人體工程學與原生互通的效能結合起來。**Pigeon v30.0+ 現在可以在幕後使用 FFIgen 和 JNIgen。**

帶有原生互通的 Pigeon 現已作為預覽版提供。您獲得了 Pigeon 契約的型別安全性和直接 FFI 和 JNI 呼叫的速度：沒有序列化往返、在需要時進行同步呼叫，以及從背景隔離區進行呼叫。Pigeon 處理資料轉換和原生物件生命週期，並且只生成您需要的綁定，因此您可以跳過低階工作。

帶有原生互通的 Pigeon 目前僅支援 Android、iOS 和 macOS。在 Windows 和 Linux 上，帶有平台通道的 Pigeon 仍然像以前一樣工作，您可以從同一個 Pigeon 檔案生成兩者。在我們將帶有原生互通的 Pigeon 推薦為構建 Plugin 的預設方式之前，我們想聽聽它對您的工作方式，特別是如果您嘗試遷移已經使用 Pigeon 的現有 Plugin。

如何使用它

工作流程與帶有平台通道的 Pigeon 相同：在 Pigeon 檔案中定義您的 API，運行 Pigeon，然後在 Swift 或 Kotlin 中實作生成的介面。該實作仍然是您呼叫所需平台 API 的地方。Pigeon 處理 Dart 程式碼和該介面之間的所有內容。

若要開啟原生互通，請在該 Pigeon 檔案頂部的 @ConfigurePigeon 註釋中設定一些選項。

pigeons/messages.dart: (您今天使用的相同 Pigeon 定義檔案)

@ConfigurePigeon(
  // ...保留您現有的輸入和輸出路徑...

  // 告訴 FFIgen 和 JNIgen 您的編譯應用程式在哪裡 (對於 Plugin，是其範例應用程式)。
  appDirectory: 'example/',
  // iOS 和 macOS：透過 FFI 直接呼叫您的 Swift 實作。
  swiftOptions: SwiftOptions(useFfi: true),
  // Android：透過 JNI 直接呼叫您的 Kotlin 實作。
  kotlinOptions: KotlinOptions(useJni: true),
)

我們最近更新了 shared_preferences，這是 pub.dev 上最受歡迎的 Plugin 之一，以使用帶有原生互通的 Pigeon。如果您已經有一個 Pigeon Plugin，shared_preferences 原始碼是一個很好的範例。

將現有 Plugin 遷移到帶有原生互通的 Pigeon 主要在於配置：添加互通依賴項，設定 useFfi 和 useJni，然後重新運行 Pigeon。遷移指南基於從 shared_preferences 遷移的經驗，它將引導您完成其餘的構建和註冊更新。如果您使用 AI 編碼代理，還有一個原生互通遷移技能，可以引導您的代理完成相同的步驟。

AI 代理在從原始 FFIgen 和 JNIgen 輸出生成慣用 Dart 包裝器方面越來越好，但仍然受益於 Pigeon 提供的功能：一致的跨平台 API、Dart 和原生運行時之間的記憶體安全、可單元測試的 Plugin 程式碼、每個平台工具鏈的協調，以及隨著時間推移保持確定且可維護的生成程式碼。您對預覽的回饋將塑造我們如何達到目標。

立即嘗試直接原生互通

這個里程碑是多年設計、迭代和回饋的結果。我們要向所有套件作者、貢獻者、開發人員以及早期存取計畫 (EAP) 參與者，特別是 Jon Holtan、Rody Davis、Dominik Roszkowski、Alexander Thiele 和 Morgan McKenzie 致以衷心的感謝，他們測試了早期預覽版、審查了我們的新文件、提交了錯誤，並幫助塑造了這些發行版。

如果您正在構建 Plugin 或需要存取原生 API，我們很樂意您嘗試直接原生互通。請前往 flutter.dev 上我們重新組織的互通文件以獲取每個工具的更多詳細資訊以及如何開始使用。如果您將 Plugin 遷移到帶有原生互通的 Pigeon，請告訴我們您是否有任何問題。

我們迫不及待想看看您會建立什麼！