疑難排解

即使是經驗最豐富的開發人員，在第一次嘗試時卻很少正確編寫程式碼，疑難排解是開發過程中的重要一環。在本節中，我們會介紹一些技巧，協助您在指令碼中找出、理解錯誤並進行偵錯。

錯誤訊息

當您的指令碼發生錯誤時，系統會顯示錯誤訊息。訊息會附帶一個用於疑難排解的行號。以這種方式顯示兩種基本錯誤：「語法錯誤」和「執行階段錯誤」。

語法錯誤

語法錯誤是由編寫不遵循 JavaScript 文法的程式碼編寫而成，因此會在您嘗試儲存指令碼時立即偵測到錯誤。例如，下列程式碼片段包含語法錯誤：

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ";
  MailApp.sendEmail('john@example.com',
                    'Data in row ' + rowNumber,
                    rowData);
}

這裡的語法問題在第四行結尾缺少 ) 字元。嘗試儲存指令碼時，您會收到以下錯誤：

引數清單之後遺漏 )。(第 4 行)

這類錯誤通常在疑難排解時簡單，因為系統會立即找到這些錯誤，原因通常十分簡單。您無法儲存包含語法錯誤的檔案，也就是說，只有有效的程式碼會儲存至專案中。

執行階段錯誤

這些錯誤是因為使用函式或類別不正確而導致，只能在指令碼執行時偵測。舉例來說，下列程式碼會導致執行階段錯誤：

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ");
  MailApp.sendEmail('john',
                    'Data in row ' + rowNumber,
                    rowData);
}

程式碼的格式正確，但我們會在呼叫 MailApp.sendEmail 時傳送電子郵件地址的「john」值。這不是有效的電子郵件地址，因此系統會在執行指令碼時擲回以下錯誤：

電子郵件地址無效：john (第 5 行)

造成這些錯誤難以進行疑難排解的原因，通常是您傳入函式的資料不會寫入程式碼中，而是從試算表、表單或其他外部資料來源提取。您可以使用下列偵錯技術找出這些錯誤的原因。

常見錯誤

以下列出一些常見錯誤及其原因。

服務叫用次數過多：<action name>

這個錯誤表示您已超過特定動作的每日配額。例如，如果您在一天內傳送的電子郵件數量過多，就可能遇到這個錯誤。針對消費者、網域和專業版帳戶，配額設有不同層級的限制，且隨時可能變更，恕不另行通知。如要查看各種動作的配額限制，請參閱 Apps Script 配額說明文件。

伺服器無法使用。或伺服器發生錯誤，請再試一次。

造成這類錯誤的可能原因如下：

  • Google 伺服器或系統暫時無法使用。請稍候片刻，然後再次嘗試執行指令碼。
  • 您的指令碼中有沒有對應的錯誤訊息。請試著對指令碼進行偵錯，看看是否能找出問題。
  • Google Apps Script 中發生錯誤，導致這項錯誤。如需搜尋及提交錯誤報告的操作說明，請參閱錯誤相關資訊。提交新錯誤前，請搜尋看看是否已有人回報該錯誤。

必須取得授權才能執行此動作。

這個錯誤代表指令碼缺少執行所需的授權。在指令碼編輯器或自訂選單項目中執行指令碼時，系統會顯示授權對話方塊。不過，透過觸發條件、嵌入 Google 協作平台頁面的觸發條件或以服務形式執行指令碼時，系統無法顯示對話方塊，而會顯示這項錯誤訊息。

如要授權指令碼，請開啟指令碼編輯器並執行任一函式。畫面上會顯示授權提示，方便您授權指令碼專案。如果指令碼包含新的未經授權服務，您必須重新授權指令碼。

這個錯誤通常是由使用者授權前觸發的觸發條件所造成。如果您無法存取指令碼專案 (例如使用的外掛程式發生錯誤)，通常可以使用外掛程式再次授權指令碼。如果觸發條件持續觸發並導致這項錯誤，您可以按照下列步驟移除觸發條件：

  1. 按一下 Apps Script 專案左側的「觸發條件」圖示 。
  2. 在要移除的觸發條件右側，依序按一下「更多」圖示 >「刪除觸發條件」。

您也可以解除安裝外掛程式，移除有問題的外掛程式觸發條件。

存取權遭拒：DriveApp 或 網域政策已停用第三方雲端硬碟應用程式

Google Workspace 網域的管理員可以停用所屬網域的 Drive API，讓使用者無法安裝及使用 Google 雲端硬碟應用程式。此外，這項設定也會禁止使用者使用使用雲端硬碟服務或進階雲端硬碟服務的 Apps Script 外掛程式 (即使指令碼已在管理員停用 Drive API 前已取得授權)。

不過，如果使用雲端硬碟服務的外掛程式或網頁應用程式是發布用於全網域安裝的外掛程式或網頁應用程式，且管理員為網域中的部分或所有使用者安裝，則即使網域中已停用 Drive API，這些使用者的指令碼函式仍會正常運作。

指令碼權限不足，無法取得有效使用者的身分。

表示指令碼無法使用活躍使用者的身分和電子郵件。此警告來自呼叫 Session.getActiveUser()。如果指令碼是在 AuthMode.FULL 以外的授權模式執行，也可能因為呼叫 Session.getEffectiveUser() 而產生。如果收到這則警告，對 User.getEmail() 的後續呼叫只會傳回「」。

視執行指令碼的授權模式而定，有多種方式可以排解這項警告的問題。授權模式會在觸發函式中公開，做為 e 事件參數的 authMode 屬性。

缺少媒體庫

如果您在指令碼中新增熱門程式庫，即使程式庫已列為指令碼依附元件，您可能會收到有關該檔案缺少的錯誤訊息。這可能是因為同時存取程式庫的人數過多。如要避免發生這項錯誤，請嘗試下列其中一種解決方案：

  • 複製程式庫的程式碼並貼到指令碼中，並移除程式庫依附元件。
  • 複製程式庫指令碼，並部署為帳戶中的程式庫。請務必將原始指令碼中的依附元件更新為新程式庫，而非公開程式庫。

缺少程式庫版本或部署作業版本，因此發生錯誤。找不到錯誤代碼

看到這則錯誤訊息表示發生下列其中一種情況：

  • 指令碼的部署版本已刪除。如要更新已部署的指令碼版本，請參閱編輯版本化部署。
  • 指令碼使用的程式庫版本已刪除。如要查看缺少的程式庫，請在程式庫名稱旁邊，依序點選「更多」>「在新分頁中開啟」。缺少的程式庫會顯示錯誤訊息。找到需要更新的程式庫後，請採取下列任一做法：
    • 更新程式庫以使用其他版本。請參閱「更新程式庫」。
    • 從指令碼專案和程式碼中移除已刪除的程式庫。請參閱「移除程式庫」一節。
  • 指令碼使用的程式庫指令碼包含另一個使用已刪除版本的程式庫。執行下列其中一項操作：
    • 如果您具有指令碼所用程式庫的編輯權限，請將該指令碼中的次要程式庫更新為現有版本。
    • 更新程式庫以使用其他版本。請參閱「更新程式庫」。
    • 從指令碼專案和程式碼中移除程式庫。請參閱「移除程式庫」一節。

使用進階服務呼叫 Google Chat API 時 Error 400: invalid_scope

如果 Error 400: invalid_scope 顯示錯誤訊息 Some requested scopes cannot be shown，表示您尚未在 Apps Script 專案的 appsscript.json 檔案中指定任何授權範圍。在大多數情況下，Apps Script 會自動判斷指令碼所需的範圍，但使用 Chat 進階服務時，您必須手動將指令碼使用的授權範圍新增至 Apps Script 專案的資訊清單檔案。請參閱設定明確範圍的說明。

如要解決錯誤，請將適當的授權範圍新增至 Apps Script 專案的 appsscript.json 檔案，做為 oauthScopes 陣列的一部分。舉例來說，如要呼叫 spaces.messages.create 方法，請新增以下內容：

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

偵錯

並非所有錯誤都會導致系統顯示錯誤訊息。可能有更細微的錯誤，即程式碼技術正確且可執行，但結果並非您預期。以下列出一些處理這類情況的策略，並進一步調查指令碼未以您預期的方式執行。

記錄

雖然偵錯時，將資訊記錄在指令碼專案執行期間，通常很有幫助。Google Apps Script 提供兩種記錄資訊方法：Cloud 記錄服務，以及 Apps Script 編輯器內建的更基本的記錄器和主控台服務。

詳情請參閱記錄指南。

Error Reporting

系統會使用 Google Cloud Error Reporting 服務，自動記錄因執行階段錯誤而發生的例外狀況。這項服務可讓您搜尋及篩選指令碼專案建立的例外狀況訊息。

如要存取 Error Reporting，請參閱在 Google Cloud Platform 控制台中查看 Cloud 記錄檔和錯誤報告。

執行作業

每次執行指令碼時，Apps Script 都會記錄執行作業，包括 Cloud 記錄檔。這些記錄可協助您瞭解指令碼執行了哪些動作。

如要查看 Apps Script 專案中的指令碼執行作業，請按一下左側的「執行」圖示 。

正在檢查 Apps Script 服務狀態

雖然很少見，但有時特定 Google Workspace 服務 (例如 Gmail 或雲端硬碟) 遇到暫時性問題，可能導致服務中斷。在這種情況下，與這些服務互動的 Apps Script 專案可能無法正常運作。

您可以查看 Google Workspace 狀態資訊主頁，確認 Google Workspace 服務是否中斷。如果目前發生服務中斷情形，您可以等待問題解決，或是前往 Google Workspace 說明中心或 Google Workspace 已知問題說明文件尋求其他協助。

使用偵錯工具和中斷點

如要找出指令碼的問題，可以在偵錯模式中執行。在偵錯模式下執行時，指令碼會在達到中斷點時暫停，這一行是您在指令碼中醒目顯示的問題行。指令碼暫停時，會顯示該時間點上每個變數的值，讓您不必新增大量記錄陳述式，即可檢查指令碼的內部作業。

新增中斷點

如要新增中斷點，請將遊標懸停在要新增中斷點的行數上。按一下行號左側的圓圈。下圖為新增至指令碼的中斷點範例：

新增中斷點

在偵錯模式中執行指令碼

如要在偵錯模式中執行指令碼，請按一下編輯器頂端的「Debug」。

在指令碼執行包含中斷點的行之前，會暫停並顯示偵錯資訊表格。您可以使用這個表格檢查資料，例如參數值和儲存在物件中的資訊。

如要控制指令碼的執行方式，請使用「Debugger」面板頂端的「Step in」、「Step over」和「Step out」按鈕。可讓您一次執行一行指令碼，並檢查值的變化趨勢。

多個 Google 帳戶的問題

如果您同時登入多個 Google 帳戶，可能會無法存取外掛程式和網頁應用程式。Apps Script、外掛程式或網頁應用程式不支援多帳戶登入或一次登入多個 Google 帳戶。

  • 如果您在登入多個帳戶時開啟 Apps Script 編輯器，Google 會提示您選擇要使用的帳戶。

  • 如果您在開啟網頁應用程式或外掛程式時遇到多帳戶登入問題，請嘗試下列其中一項解決方案：

    • 登出所有 Google 帳戶，只登入包含所需外掛程式或網頁應用程式的帳戶。
    • 在 Google Chrome 中開啟無痕式視窗或同等的私密瀏覽視窗，然後登入包含您要存取的外掛程式或網頁應用程式的 Google 帳戶。

取得協助

使用上述工具和技術對問題進行偵錯可以解決各種問題，但您可能會遇到遇到的問題，需要額外協助才能解決。請參閱我們的支援頁面，瞭解可以在哪裡提出問題和回報錯誤。