與本機應用程式的 native messaging

1. 擴充功能宣告 nativeMessaging 權限。
2. 一個 host manifest，也就是向作業系統註冊的小型 JSON 檔案，指定應用程式與可以呼叫它的擴充功能。
3. 應用程式實作以長度為前綴的 stdio 協定。

​

宣告權限

{
  "manifest_version": 3,
  "name": "Ping",
  "version": "1.0",
  "permissions": ["nativeMessaging"],
  "background": {
    "service_worker": "background.js"
  }
}

​

撰寫 host manifest

{
  "name": "com.example.ping",
  "description": "Echo host for the docs example",
  "path": "/absolute/path/to/ping-host",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://<your-extension-id>/"]
}

• name 是擴充功能傳給 connectNative() 的識別碼。使用小寫字母、數字、底線與句點。
• path 在 macOS 與 Linux 上必須是絕對路徑。在 Windows 上可以相對於 manifest，而且必須指向可執行檔（Node.js 腳本要用 .bat 包裝器）。
• type 永遠是 stdio。
• allowed_origins 列出可以呼叫這個 host 的擴充功能 ID。開啟開發人員模式後，在 chrome://extensions 讀取你的 ID。

​

安裝位置

​

最小的 Node.js host

function send(message) {
  const json = Buffer.from(JSON.stringify(message));
  const header = Buffer.alloc(4);
  header.writeUInt32LE(json.length, 0);
  process.stdout.write(Buffer.concat([header, json]));
}

let buffer = Buffer.alloc(0);

process.stdin.on("data", (chunk) => {
  buffer = Buffer.concat([buffer, chunk]);

  while (buffer.length >= 4) {
    const length = buffer.readUInt32LE(0);
    if (buffer.length < 4 + length) break;

    const message = JSON.parse(buffer.subarray(4, 4 + length).toString());
    buffer = buffer.subarray(4 + length);

    send({ received: message });
  }
});

#!/bin/sh
exec node "$(dirname "$0")/ping-host.js"

​

從 background script 連線

const port = chrome.runtime.connectNative("com.example.ping");

port.onMessage.addListener((message) => {
  console.log("From host:", message);
});

port.onDisconnect.addListener(() => {
  console.log("Disconnected:", chrome.runtime.lastError?.message);
});

port.postMessage({ ping: Date.now() });

chrome.runtime.sendNativeMessage("com.example.ping", { ping: 1 }, (reply) => {
  console.log(reply);
});

​

Firefox 的差異

• 你的擴充功能需要透過 browser_specific_settings.gecko.id 指定明確的 ID。使用 firefox: manifest 前綴，讓這個鍵只進入 Firefox 建置。
• host manifest 以 allowed_extensions 取代 allowed_origins，列出該 ID。

{
  "name": "com.example.ping",
  "description": "Echo host for the docs example",
  "path": "/absolute/path/to/ping-host",
  "type": "stdio",
  "allowed_extensions": ["ping@example.com"]
}

​

extension dev 期間的 native messaging

• 以全系統方式安裝 host manifest（在 Windows 上則安裝到登錄檔）。這些位置不依賴設定檔。
• 改為使用你真實的瀏覽器設定檔執行：

extension dev --profile false

​

最佳實務

• 驗證每一則訊息：host 以使用者的完整作業系統權限執行，因此要把擴充功能的輸入視為不可信任，反之亦然。
• 保持 stdout 乾淨：host 裡一個多餘的 console.log 就會破壞訊息框串流。
• 處理中斷連線：在 onDisconnect 中檢查 chrome.runtime.lastError，以區分 host 不存在與 host 當機。
• 重複呼叫時優先使用 port：sendNativeMessage() 每則訊息都要付出一次行程啟動的成本。

​

後續步驟

• 在 Messaging 檢視擴充功能內部的通道。
• 在 權限與 host permissions 了解權限提示。
• 在 瀏覽器設定檔 了解開發設定檔如何運作。