學 Apps Script 很像學開車：先會發動，再談技巧。對試算表來說，「發動」就是拿到當前這本文件，而 getActiveSpreadsheet() 是最直覺的鑰匙。它讓你能鎖定分頁、改值、插入表單按鈕；但在沒有「作用中文件」的情境（像排程或獨立專案），它就會交出 null。

其實要把 Google 試算表動起來，只需要先搞定一件小事：把「眼前這一份表」抓到手。getActiveSpreadsheet() 就在做這件事。有它，你就能找到分頁、讀寫儲存格、加自訂選單，甚至把日常報表自動化。

本文章盡力說明相關內容，直接用小範例帶您練習，希望文章內容可以幫助到需要的您。

function helloCell() {
  const ss = SpreadsheetApp.getActiveSpreadsheet(); // 可能為 null
  if (!ss) throw new Error('沒有作用中的試算表（可能是獨立專案或觸發器環境）');
  const sheet = ss.getActiveSheet();
  sheet.getRange('A1').setValue('Hello, Sheets!');
  Logger.log(ss.getUrl());
}

重點：在容器綁定專案直接執行就能看到效果；若你在獨立專案按下「執行」，多半會噴 null。

加一個自訂選單

function onOpen() {
  const ui = SpreadsheetApp.getUi();
  ui.createMenu('我的工具')
    .addItem('寫入問候語', 'helloCell')
    .addToUi();
}

這段需綁在某一份試算表才能與 UI 互動。

在觸發器裡的正確用法

onEdit(e) / onOpen(e)：拿 e.source，別再叫 getActiveSpreadsheet()

function onEdit(e) {
  const ss = e && e.source;          // 這就是當下那份試算表
  const sheet = ss.getActiveSheet();  // 仍可拿到作用中的分頁
  // ...你的邏輯
}

onEdit(e) 會把事件物件傳進來，裡面含有試算表來源與被改動的範圍；直接用 e.source 最穩。不要在這裡硬叫 getActiveSpreadsheet() 以免踩到 null。

時間驅動或排程觸發器：改用 openById()

const SPREADSHEET_ID = '填你的檔案ID';

function nightlyJob() {
  const ss = SpreadsheetApp.openById(SPREADSHEET_ID);
  const sheet = ss.getSheetByName('Report') || ss.getSheets()[0];
  sheet.getRange('A2').setValue(new Date());
}

背景執行沒有「作用中」文件，getActiveSpreadsheet() 自然是 null；請用 openById() / openByUrl() 指向目標。

常見錯誤訊息與處理

症狀／訊息	典型原因	快速修法
`TypeError: Cannot read properties of null (reading 'getActiveSheet')`	`getActiveSpreadsheet()` 回 `null`，多見於獨立專案、排程觸發器、外掛某些情境	改用 `openById()` / `openByUrl()`；或把專案改成容器綁定再執行。(Google 支援)
`e is undefined` 或 `Cannot read properties of undefined (reading 'range')`	在編輯器按「執行」測 `onEdit(e)`，沒有事件物件	請在表格實際編輯觸發；或改成安裝型觸發器並用測試資料。(Google for Developers)
背景排程「成功」但表格沒變	取得的對象是 `null` 或抓錯檔案；或觸發器權限問題	用 `openById()` 指定檔案；確認觸發器已授權且權限未過期。(Web Applications Stack Exchange)
Add-on 中 `getActiveSpreadsheet()` 是 `null`	當前沒有活躍的試算表脈絡	在可行處改用 `e.source`（若有事件物件）或 `openById()`；檢查外掛部署方式。(issuetracker.google.com)