Skip to main content
Extension.js 會收集極少量的匿名遙測資料，用來了解你執行了哪些指令、哪些指令失敗。它不會收集原始碼、檔案路徑、URL 或專案內容。 隱私標準刻意設得很嚴格：
  • 共兩個事件：command_executed 與 command_failed
  • 每個事件三個屬性：command、success、version
  • 可用環境變數、CLI 旗標或永久同意指令退出
  • Extension.js 會取樣並限額，確保使用量遠在 PostHog（開源分析工具）的免費額度內

​
Extension.js 收集什麼

每次 CLI 執行最多送出其中一個事件： create 指令可能會多帶兩個屬性：template（清理過的範本名稱）與 source（範本的來源）。create 指令也不參與取樣，因此範本使用量的數字能保持準確。 附加在每個事件上的共用情境：os（darwin／linux／win32）、arch、node_major、is_ci、is_source_build。其他都沒有。is_source_build 是單一布林值，只回答「這是一次 registry 安裝，還是一份儲存庫檢出」。它由安裝路徑的形狀推算而來（CLI 之上是否有 node_modules 形式的路徑片段）。路徑本身永遠不會被讀進事件、送出，也不會被雜湊。

​
流量控制

三個獨立的控制機制，限制離開機器的資料量：
  • 取樣： Extension.js 預設以 20% 對 command_executed 取樣。可用 EXTENSION_TELEMETRY_SAMPLE_RATE（0.0–1.0）覆寫。失敗事件永不取樣。
  • 每次執行上限： 每個 CLI 程序最多 3 個事件。可用 EXTENSION_TELEMETRY_MAX_EVENTS 覆寫。
  • 去抖動（重複抑制）： 60 秒內重複的 (event, command, success) 元組會被 Extension.js 丟棄。可用 EXTENSION_TELEMETRY_DEBOUNCE_MS 覆寫。

​
Extension.js 永不收集什麼

Extension.js 的遙測約定明確排除以下內容：
  • 原始碼、manifest 內容、HTML 輸出或 package.json 內容
  • 儲存庫名稱、Git 遠端、GitHub 組織／使用者名稱、分支名稱、commit SHA 或預覽 URL
  • 相依套件清單、權限清單，或自由格式的專案識別字串
  • 環境變數值、檔案系統路徑或本機 URL
  • 堆疊追蹤、錯誤訊息或自由文字的錯誤名稱
  • IP 位址（Extension.js 在每個 payload 上將 $ip 設為 null）

​
退出方式

三種停用遙測的方法，依優先順序列出：
同意檔位於 $XDG_CONFIG_HOME/extensionjs/telemetry/consent（或平台對應位置）。當該位置不可寫入時，儲存位置會依序後備：平台快取目錄，接著是系統暫存目錄下的資料夾，最後是工作目錄中的 ./.cache/extensionjs。

​
預設行為

在互動式終端機中，遙測採 opt-out。在首次未套用上述任何覆寫的執行中，Extension.js 會印出一行說明如何停用的通知，並紀錄 enabled 同意標記，讓通知不再重複出現。

​
CI 預設關閉

在 stdout 沒有接上任何東西的 CI 環境中（有設定 CI 標記且沒有 TTY），遙測預設是關閉的，並回報 source: ci。已儲存的 enabled 同意不會帶進流水線：由真人在鍵盤前記錄的同意，無法涵蓋一條繼承了同一個家目錄的流水線，因此這個已儲存的選擇加入會被降到 CI 閘門之下。已儲存的 disabled 是一次拒絕，而拒絕在任何地方都優先，CI 中也一樣。 若要刻意從流水線送出遙測，請設定 EXTENSION_TELEMETRY=1。這個明確的機器層級選擇加入位於 CI 閘門之上。

​
本地稽核紀錄

Extension.js 會把每個它考慮送出的事件（不論是否真的送出）附加到同意檔旁邊的 events.jsonl。你可以隨時檢視，也可以放心刪除。 稽核紀錄的大小是有界的。到達 1 MiB 時，它會輪替成單一的 events.jsonl.1 備份，取代先前的備份。可用 EXTENSION_TELEMETRY_AUDIT_MAX_BYTES 覆寫這個上限。遠超上限（達 10 倍以上）的檔案會直接丟棄，而不是保留。如果稽核寫入本身失敗，Extension.js 會在該次執行中停用後續所有送出：一個無法在本地留下稽核紀錄的事件，不會被送出。

​
最佳實務

  • 政策要求不送遙測時，在 CI 中使用 EXTENSION_TELEMETRY_DISABLED=1。
  • 把隱私回歸視為產品回歸對待。
  • 閱讀儲存庫層級的合約以取得確切的事件清單。

​
下一步

  • 在 全域旗標 檢視 --no-telemetry 與環境變數覆寫。
  • 透過 build 與 dev 進行發佈與自動化流程。
  • 閱讀儲存庫層級的 docs/TELEMETRY.md 合約以取得確切的事件清單。