授權

設定 Exchange 匯出授權、查詢剩餘額度並處理授權錯誤。

Exchange 在執行 @univerjs-pro/exchange-node 的伺服器端程序中讀取授權。轉換用法見 Office 檔案匯入匯出。

設定授權

建議透過環境變數 UNIVER_LICENSE 與 UNIVER_LICENSE_KEY 成對提供授權。無需呼叫 configureExchange；SDK 在首次匯出或額度查詢時自動讀取一次，後續呼叫沿用該設定。未提供環境憑證時使用 Free；已提供但無效的授權會報錯，不能用於匯出。

也可以使用 configureExchange({ license, licenseKey }) 明確設定，它傳回 Promise<void>。明確設定完全忽略環境變數；應等待設定完成後再開始使用新授權的匯出。

TypeScript
import { configureExchange, getExportQuota } from '@univerjs-pro/exchange-node'await configureExchange({  license: '<license content>',  licenseKey: '<licenseKey content>',})const quota = await getExportQuota()

license 與 licenseKey 使用授權提供者交付的完整內容，不是檔案路徑。兩項應成對設定，並透過應用程式的密鑰管理系統提供。

輸入使用方式
不呼叫 configureExchange首次使用時成對讀取環境變數；均未提供則使用 Free。
configureExchange({ license, licenseKey })只使用明確憑證，完全忽略環境變數。
configureExchange({})明確選擇 Free，忽略環境變數。
所選來源只提供一個欄位傳回 INVALID_ARGUMENT，不會從另一來源補齊。

完整的環境設定讀取後即固定，即使後續操作失敗也不會自動重讀。更換預設授權應明確呼叫並等待 configureExchange；設定失敗時保留先前設定，應處理錯誤後再開始新的匯出。

同一 JavaScript 環境中的 ESM 與 CommonJS 共用設定。每個 worker_threads Worker 都需獨立設定或從環境變數初始化。匯出使用呼叫公開匯出方法時的設定，後續更換憑證不會改變已發起的匯出。

為單次操作指定授權

匯出 API 和 getExportQuota 的選項可傳入完整的 license、licenseKey，僅作用於本次操作，不修改預設設定。例如，使用同一授權查詢額度並匯出：

TypeScript
import { UniverInstanceType } from '@univerjs/core'import { ExchangeFormat, exportToBuffer, getExportQuota } from '@univerjs-pro/exchange-node'const credentials = { license: '<license content>', licenseKey: '<licenseKey content>' }const quota = await getExportQuota(credentials)const output = await exportToBuffer(workbook, {  type: UniverInstanceType.UNIVER_SHEET,  format: ExchangeFormat.XLSX,  ...credentials,})

此方式同樣適用於檔案匯出、Snapshot 匯出和選用的 PDF 匯出。不傳這兩個欄位時使用預設設定；只傳一個欄位傳回 INVALID_ARGUMENT。明確傳入的完整憑證不會從預設設定或環境變數補齊，空字串也不會被視為省略；授權無效時傳回 LICENSE_INVALID，不會改用預設商業授權。

選用 PDF 支援

安裝 PDF 擴充套件，並在設定授權前匯入 PDF 進入點：

Shell
pnpm add @univerjs-pro/exchange-node @univerjs-pro/exchange-pdf-node-binding
TypeScript
import '@univerjs-pro/exchange-node/pdf'import { configureExchange, getExportQuota } from '@univerjs-pro/exchange-node'await configureExchange({  license: '<license content>',  licenseKey: '<licenseKey content>',})const quota = await getExportQuota()

該進入點註冊 PDF 支援，原生元件在實際使用時載入。PDF 仍使用 importBuffer、importFile、exportToBuffer、exportToFile 及對應 Snapshot API，指定 UniverInstanceType.UNIVER_PDF 和 ExchangeFormat.PDF；無需改用另一套轉換 API。僅處理 PDF 的應用程式不需要載入 Office 原生元件。環境變數設定同樣適用於 PDF。

查詢剩餘額度

getExportQuota({ license, licenseKey }) 傳回 Promise<ExportQuota>，查詢該授權在 Office 與 PDF 間共用的額度。不傳憑證時查詢預設設定。查詢不接收類型參數，也不判斷授權是否允許匯出某個類型；類型授權在實際匯出時檢查。

查詢不扣次、不預留額度，也不檢查 SDK 版本、授權是否已生效或匯出類型權限。餘額為零時仍成功傳回目前快照；其他並行請求可能隨後使用額度，請同時處理實際匯出的錯誤。

授權尚未生效時，有限額度傳回首個授權月的快照，periodStart 為未來日期。查詢成功或 licenseStatus 為 valid 均不代表目前允許匯出；版本、生效時間、類型權限、可用額度和並行名額在實際匯出時檢查。

欄位類型含義
licenseStatus'not_configured' | 'expired' | 'valid'匯出訂閱未設定、已到期或未到期；valid 不表示已通過匯出准入檢查。無效授權直接報錯。
expiresAtstring | null匯出訂閱到期的 UTC ISO 時間；未設定或無到期時間時為 null。
observedAtstring本次快照的 UTC ISO 時間。
limitnumber | null目前月額度上限；不限次數時為 null。
usednumber | null目前月已成功匯出的次數；不限次數時為 null。
reservednumber | null目前月正在處理的匯出佔用次數；不限次數時為 null。
remainingnumber | null目前可用次數，即 max(0, limit - used - reserved)；不限次數時為 null。
periodStartstring | null所查詢月額度區間的 UTC ISO 起點，包含該時刻；尚未生效時為首期起點，不限次數時為 null。
periodEndstring | null所查詢月額度區間的 UTC ISO 終點，不包含該時刻；不限次數時為 null。

periodEnd 表示下一個月額度開始的時間，expiresAt 表示整個匯出訂閱到期的時間。訂閱有效時始終使用商業額度；本月用盡不會使用 Free，下個月開始使用新的商業月額度。訂閱到期後使用原有 Free 剩餘額度，不重新發放或歸零。

有限額度快照範例：

JSON
{  "licenseStatus": "valid",  "expiresAt": "2027-10-19T23:59:59Z",  "observedAt": "2026-10-21T09:00:00Z",  "limit": 500,  "used": 20,  "reserved": 1,  "remaining": 479,  "periodStart": "2026-10-19T00:00:00Z",  "periodEnd": "2026-11-19T00:00:00Z"}

使用額度

Free 每授權月允許 10 次成功匯出。商業授權的次數、並行及版本範圍以所購授權為準。Free 與商業授權均不設定授權層面的檔案大小和儲存格數量上限。週期與剩餘額度以查詢結果為準，未用完的月額度不結轉。

匯入無需設定匯出授權，也不消耗匯出次數。同一部署中，Office 與 PDF 使用同一商業授權時共用額度。Office 轉換格式見 Office 檔案匯入匯出。

每次成功轉換計 1 次，傳回 Buffer 即視為轉換成功。轉換成功後的檔案寫入、上傳或下載失敗不退回次數；再次成功轉換會再次計次。本週期額度用盡後拒絕新的匯出，需等待下一授權週期或改用額度更高的有效授權；有效商業授權不會借用 Free 額度。

處理錯誤

使用結構化 code 判斷錯誤，不要解析 message 文字。使用者介面可依錯誤碼提供在地化提示；診斷資訊請保留供技術支援使用。

TypeScript
import { UniverInstanceType } from '@univerjs/core'import { ExchangeError, ExchangeFormat, exportToBuffer } from '@univerjs-pro/exchange-node'try {  const output = await exportToBuffer(workbook, {    type: UniverInstanceType.UNIVER_SHEET,    format: ExchangeFormat.XLSX,  })} catch (error) {  if (error instanceof ExchangeError) {    // 依 error.code 顯示對應提示，例如額度不足時為 LICENSE_EXPORT_QUOTA_EXCEEDED    console.error(error.code)  } else {    throw error  }}

下表區分額度查詢（getExportQuota）與實際匯出的報錯時機。兩類 API 均傳回 Promise，使用 await 搭配 try/catch 處理錯誤。

錯誤碼報錯時機含義及處理方式
LICENSE_EXPORT_QUOTA_EXCEEDED僅匯出目前週期的可用匯出額度不足；查詢額度或聯絡業務調整授權。
LICENSE_CONCURRENCY_TIMEOUT僅匯出等待可用匯出並行名額逾時；降低並行數後再發起匯出。
LICENSE_UNIT_TYPE_REJECTED僅匯出目前授權未包含此匯出類型或該類型授權已到期；使用包含該類型的有效授權。
LICENSE_INVALID查詢、匯出授權無效；檢查完整憑證或聯絡授權提供者更新授權。
LICENSE_POLICY_INVALID查詢、匯出授權設定不符合 SDK 要求；聯絡授權提供者更新授權。
LICENSE_NOT_YET_EFFECTIVE僅匯出授權尚未生效；在生效後使用。
LICENSE_VERSION_NOT_ALLOWED僅匯出目前 SDK 版本不在授權範圍內；使用相符版本或更新授權。
UNSUPPORTED_FORMAT僅匯出不支援指定的格式或格式與類型不相符；檢查匯出選項。
INVALID_FILE僅匯出轉換輸入無效；檢查輸入內容。
INCOMPLETE_SNAPSHOT僅匯出匯出資料不完整；提供完整資料或 Snapshot。
CONVERSION_FAILED僅匯出檔案轉換失敗；保留錯誤資訊並檢查輸入內容。
IO_ERROR僅匯出檔案讀寫失敗；成功轉換後的檔案寫入失敗已經消耗 1 次。
INVALID_ARGUMENT查詢、匯出參數或憑證不完整；檢查傳入設定。
NATIVE_LOAD_FAILED查詢、匯出SDK 原生元件無法載入；檢查已安裝套件及執行環境是否相符。
LICENSE_USAGE_STATE_INVALID查詢、匯出授權用量狀態無法驗證；保留錯誤資訊並聯絡技術支援。
LICENSE_USAGE_STORAGE_ERROR查詢、匯出授權用量處理失敗；保留錯誤資訊並聯絡技術支援，避免自動重複提交。

應用程式可依 licenseStatus 與 expiresAt 自行顯示到期提醒；SDK 不額外傳回提示清單。

遇到授權用量處理異常時，不應僅依錯誤推斷本次是否已計次，請保留完整錯誤並聯絡技術支援。

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.