使用 Clasp 在本地環境開發 Google Sheets Apps Script：一個基於 Git 的版本控制方案

2025-03-30

/blog/2025-03-31-clasp/ 林協霆

Table of Contents

## 使用 Clasp 在本地環境開發 Google Sheets Apps Script：一個基於 Git 的版本控制方案

# 摘要 (Introduction)

Google Sheets 的 Apps Script 提供了強大的功能擴展能力，但直接在瀏覽器中編輯這些腳本存在諸多限制。本文介紹如何透過 Command Line Apps Script Projects (clasp) 工具將 Apps Script 下載到本地環境進行開發，並利用 Git 進行版本控制，提高開發效率和程式碼品質。

# 研究方法 (Methods)

本研究採用實作導向的方法，依序說明從環境設置、連接 Google 帳戶到本地開發與部署的完整流程。特別著重於介紹如何整合 Git 版本控制系統，以實現更專業的 Apps Script 開發工作流。

# 研究結果 (Results)

## 環境準備與設置

安裝 clasp
```
npm install -g @google/clasp
```
啟用 Google Apps Script API
- 訪問 Google Apps Script 設定頁面
- 確認 Apps Script API 已開啟使用權限
登入 Google 帳戶
```
clasp login
```
執行此命令後，系統會自動開啟瀏覽器要求授權，允許 clasp 存取您的 Apps Script 專案。

## 專案設置與開發流程

取得 Script ID
- 開啟目標 Google Sheets 文件
- 進入「擴充功能」>「Apps Script」
- 在 Apps Script 編輯器中點選「檔案」>「專案屬性」
- 複製顯示的 Script ID
將 Script 下載到本地
```
clasp clone 您的_SCRIPT_ID
```
此操作會建立一個本地資料夾，包含所有 Apps Script 檔案。

整合 Git 版本控制

cd 您的專案資料夾
git init
git add .
git commit -m "初始提交：從 Google Sheets 導入 Apps Script"

使用本地編輯器進行開發
- 您可以使用任何偏好的程式碼編輯器（如 VS Code、Sublime Text）
- 享受程式碼格式化、語法檢查等進階功能

透過 Git 管理開發進度

git checkout -b 新功能分支
# 編輯檔案後
git add .
git commit -m "實現新功能：XXX"

## 部署與測試

將修改推送回 Google Sheets
```
clasp push
```
此命令會將本地變更同步回 Google Sheets。
執行與測試
```
clasp run 函數名稱
```
您也可以直接在 Google Sheets 中測試更新後的腳本。

# 討論 (Discussion)

在本地環境開發 Apps Script 相較於傳統的瀏覽器編輯器有諸多優勢：

提升開發效率：本地編輯器提供更豐富的功能，如代碼補全、自動格式化等。
版本控制的優勢：透過 Git 管理，可以：
- 追蹤所有程式碼變更
- 實現分支開發，隔離實驗性功能
- 方便團隊協作與代碼審查
- 在出現問題時快速回滾到穩定版本
增強程式碼品質：結合本地開發工具的程式碼分析功能，有助於發現潛在問題。
離線工作能力：可在無網絡連接的環境下繼續開發，稍後再同步更改。

這種開發方式特別適合複雜的 Apps Script 專案，或需要多人協作的團隊環境。

# 補充說明：使用 clasp run 執行操作 Google Sheets 的腳本

在本地環境執行並測試會操作 Google Sheets 的 Apps Script 時，需要注意以下重要事項：

## 1. 設定適當的權限範圍

為確保您的腳本能成功操作 Google Sheets，需在 appsscript.json 檔案中定義適當的 OAuth 授權範圍：

{
  "timeZone": "Asia/Taipei",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

這些授權範圍讓 clasp 在執行時有權存取並修改您的 Google Sheets 檔案。

## 2. 部署為 API 可執行版本

Google 目前不允許未部署的 Apps Script 直接透過 clasp run 執行，因此需完成以下部署步驟：

開啟 Google Apps Script 編輯器
點選「部署」>「新部署」
選擇「執行 API」（而非 Web 應用程式）
設定適當的授權範圍
點選「部署」並取得 Deployment ID

## 3. 執行具有參數的腳本

當您的函數需要參數時，可以：

clasp run 函數名稱 -p '["參數 1", "參數 2"]'

這會在 Google 伺服器上執行您的腳本，並能夠操作目標試算表。

## 4. 使用 Service Account 實現自動化

對於需要在 CI/CD 環境或伺服器上自動執行的腳本，建議設置 Google Cloud Service Account：

在 Google Cloud Console 建立 Service Account
下載 Service Account 的 JSON 金鑰檔案
將目標 Google Sheets 共享給該 Service Account（並授予編輯權限）

使用以下命令登入並執行腳本：

clasp login --creds service-account.json
clasp run 函數名稱

這種方式特別適合建立自動化工作流程，無需人工介入即可操作 Google Sheets。

# 結論 (Conclusion)

使用 clasp 將 Google Sheets 的 Apps Script 下載到本地進行開發，並結合 Git 進行版本控制，代表了一種更專業、更有效率的工作方式。這不僅可以提高代碼質量，還可以更好地組織開發流程，對於依賴 Google Sheets 自動化的企業和個人開發者來說，是一個值得採用的開發策略。特別是透過正確設定授權範圍和部署方式，您可以充分利用本地開發環境的優勢，同時保持對 Google Sheets 的完整操作能力。