做 Google 試算表自動化，第一步常卡在「到底要改哪個分頁？」getSheetByName() 就是那把鑰匙：用分頁名稱，準確拿到要動手的頁籤。

本篇文章會盡可能說明內容，內容涵蓋最小可用的範例、怎麼避免找不到分頁、名稱改了怎麼辦。也會補上常見坑點（例如大小寫、空白字元、綁定腳本 vs. 獨立腳本）和實用的可複用函式。

希望讀完你不只會用，還能寫出耐改名、耐擴充、可交接的腳本。

在自動化報表、資料清洗或產生月報時，你幾乎都會「按工作表名稱」去定位資料頁籤。getSheetByName(name) 就是拿到指定分頁（Sheet）的最快方式：給它一個精準的分頁名稱，回傳對應的 Sheet 物件，沒有就回傳 null。這是官方行為定義，不是鄉野傳說。

快速上手：基本語法與最小可用範例

基本語法

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheetByName('原始資料'); // 找不到會回傳 null
if (!sheet) throw new Error('找不到「原始資料」工作表');

getSheetByName() 精準比對名稱，大小寫、空白、全形半形都算數；找不到只會回傳 null，不會直接丟例外。

讀寫範例：把 A1 寫進時間戳記

function writeTimestamp() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('原始資料');
  if (!sheet) throw new Error('找不到「原始資料」工作表');

  sheet.getRange('A1').setValue(new Date());
}

建立後再取用：不存在就新建

function getOrCreateSheetByName(name) {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  let sheet = ss.getSheetByName(name);
  if (!sheet) sheet = ss.insertSheet(name);
  return sheet;
}

insertSheet(name) 可以直接用名稱建立分頁

正確的專案開檔方式（超重要）

綁定腳本（從試算表 → 擴充功能 → Apps Script 進入）時，用 SpreadsheetApp.getActiveSpreadsheet() 才有「作用中的檔案」。如果你在獨立腳本環境跑它，getActiveSpreadsheet() 可能是 null，任何串接方法都會變成 Cannot read properties of null 這類錯。

若腳本必須跨檔案操作，改用 openByUrl() 或 openById() 自行指向目標檔案，而不要期待「作用中」檔案。

進階：用 Sheet ID 穩固指向，避免「被改名就爆」

名字會被改，但 Sheet ID 幾乎不會變。Apps Script 現在提供：

sheet.getSheetId() 取得分頁的唯一 ID

ss.getSheetById(id) 直接以 ID 取回分頁

這對「月度複製樣板後重新命名」這類流程很重要：先抓到 ID，之後就算名稱被改寫，仍能穩定取到同一個分頁。

示例：寫入時盯 ID 而非名稱

function safeWriteById(sheetId, a1, value) {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetById(sheetId);
  if (!sheet) throw new Error(`找不到 ID=${sheetId} 的工作表`);
  sheet.getRange(a1).setValue(value);
}

樣板複製：先以樣板建立，再改名

你可以用 insertSheet(newName, index, { template: templateSheet }) 直接以某分頁為模板，產生新分頁並命名。這招在建置週／月度報表超好用。

function createFromTemplate(newName, templateName = 'TEMPLATE') {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const tpl = ss.getSheetByName(templateName);
  if (!tpl) throw new Error('找不到樣板分頁');

  // 在第 1 個位置插入，並以樣板複製內容/格式
  ss.insertSheet(newName, 1, { template: tpl });
}