如果你有在寫 Google Apps Script，應該都是用 Google 提供的網頁編輯器吧?
雖然網頁編輯器上手很快，但只要專案稍微大一點，或者開始寫 HTML 相關的內容，就會覺得用起來綁手綁腳。
這時候 CLASP 就派上用場了。
CLASP 是 Google 官方推出的命令列工具，名字是「Command Line Apps Script Projects」的縮寫。
它讓你可以把 Apps Script 專案下載到自己的電腦，用 VS Code 這類專業編輯器來開發，寫完之後再同步回 Google 伺服器。
這篇文章會從零開始，一步步帶你把 CLASP 裝起來，並學會最基本的「推送」與「拉取」工作流程。
什麼情況下需要用 CLASP
先說結論：小專案不一定需要，但大專案或含 HTML 的專案會差很多。
平常寫 Apps Script，通常是從 Google 試算表或文件點「擴充功能 → Apps Script」進入編輯器。
這個網頁編輯器在幾個情境下會覺得卡卡的：
第一，編輯體驗不如 VS Code 那麼流暢，自動完成、快捷鍵、Git 整合都相對陽春。
第二，寫 HTML 很痛苦，但做 Sidebar、Dialog 或 Web App 偏偏又離不開 HTML。
第三，檔案一多就很難管理，切換來切換去很混亂。
如果你只是在試算表裡寫個幾十行的小函式，其實網頁編輯器就夠了，裝 CLASP 反而會多出很多設定步驟。
第一步：先裝好 VS Code 與 Node.js
在安裝 CLASP 本身之前，有兩個工具一定要先裝。
安裝 VS Code（程式編輯器）
VS Code 是微軟推出的免費編輯器，Windows、Mac、Linux 都有版本。
到官網 code.visualstudio.com 點下載，然後一路「下一步」裝完就好。
安裝 Node.js（執行環境）
你可能會想：clasp 不就是一個終端機指令嗎？為什麼還要先裝 Node.js？
這裡要釐清一個觀念：終端機裡能打的指令有兩種。
一種是系統內建指令，像 ls、cd、pwd 這些，作業系統本身就有，開箱即用。
另一種是第三方 CLI 工具，像 git、clasp、docker 這些，別人開發的、你要自己裝。
這些工具各自用不同程式語言寫成——git 是 C 寫的，clasp 則是 Node.js 寫的。
所以當你在終端機輸入 clasp login，電腦背後其實是呼叫 Node.js 去執行一段 JavaScript 程式。
沒有 Node.js，clasp 就裝不起來、也跑不動。
安裝方式：到 nodejs.org 下載。
畫面會出現兩個版本：LTS（長期支援版）和 Current（最新版），一般選 LTS 就好。
下載完同樣一路「下一步」裝完。
確認 Node.js 裝好了
裝完之後，打開 VS Code，從上方選單選「View → Terminal」（中文叫「檢視 → 終端機」），VS Code 下方會開出一個命令列視窗。
這個叫做「整合終端機」。
在 Mac 上它背後其實就是你熟悉的 Terminal，在 Windows 上則是 Command Prompt 或 PowerShell。
在裡面輸入這個指令：
node -v如果看到類似 v20.10.0 的版本號碼，代表 Node.js 安裝成功。
如果看到「command not found」或「不是內部命令」這類錯誤訊息，代表 Node.js 沒裝好，請回去重新安裝。
安裝 Node.js 的同時，還會一併裝好一個叫 NPM 的工具。
NPM 是 Node.js 的「套件管理員」，等一下安裝 CLASP 就是靠它。
第二步：用 NPM 安裝 CLASP
在 VS Code 的終端機輸入：
npm install -g @google/clasp指令中的 -g 代表「全域安裝（global）」，意思是裝完之後，電腦任何地方都能直接執行 clasp 這個指令。
如果遇到權限錯誤怎麼辦
執行時你可能會看到一堆紅色錯誤訊息，大多跟「permission denied（權限不足）」有關。
這是因為全域安裝需要管理員權限。
解法依作業系統不同：
Mac 或 Linux：在指令前加上 sudo，系統會要求你輸入電腦的登入密碼：
sudo npm install -g @google/claspWindows：不能在 VS Code 的終端機裡解決，必須另外開一個「以系統管理員身分執行」的命令提示字元。
步驟是：
- 點開始選單，搜尋「命令提示字元」。
- 找到之後 按右鍵，選「以系統管理員身分執行」。
- 在新開的那個黑色視窗裡，重新輸入
npm install -g @google/clasp並執行。
確認 CLASP 裝好了
安裝完成後，回到 VS Code 的終端機，輸入：
clasp -v如果顯示版本號碼（例如 2.3.0），就代表 CLASP 已經成功裝好了。
第三步：打開 Google Apps Script API
CLASP 要能讀寫你的 Apps Script 專案，必須先到 Google 那邊把對應的 API 開關打開。
打開這個網址：https://script.google.com/home/usersettings
你會看到「Google Apps Script API」的開關顯示 Off。
把它切成 On 就可以了。
如果原本就是開著的，就不要動它。
第四步：用 CLASP 登入 Google 帳號
環境都準備好之後，下一步是讓 CLASP 跟你的 Google 帳號連線。
在終端機輸入：
clasp login按下 Enter 後，CLASP 會自動幫你打開瀏覽器，跳出 Google 的登入畫面。
一定要選「原本用來管理那個 Apps Script 專案的 Google 帳號」，不要選錯。
選完帳號，Google 會問你要不要授權 CLASP 存取 Apps Script，點「允許」。
回到瀏覽器看到「Logged in! You may close this page.」就可以關掉那個分頁了。
第五步：找到要下載專案的 Script ID
要把雲端的 Apps Script 專案抓到本地之前，必須先知道它的「Script ID」（也就是專案的唯一識別碼）。
打開你想下載的 Apps Script 專案，在網頁編輯器裡找「檔案 → 專案屬性」。
彈出的視窗裡會看到一個欄位叫 Script ID，是一串很長的字母數字組合。
把它完整複製起來，等一下會用到。
（新版 Apps Script 編輯器也可以從左側邊欄的「專案設定」齒輪圖示中找到。）
第六步：建立本地專案資料夾
在電腦上建立一個空資料夾，專門用來放這個專案，例如叫 clasp-tutorial。
然後在 VS Code 裡選「File → Open Folder」（開啟資料夾），把這個資料夾打開。
打開後，左側應該會看到這個資料夾名稱，代表 VS Code 已經把它當作「專案根目錄」。
初始化 Node 專案
所謂「Node 專案」，指的就是一個裡面有 package.json 這個檔案的資料夾。
package.json 是給 NPM 看的清單，記錄「這個專案用到哪些套件、各自什麼版本」。
就像 git 專案靠 .git 資料夾追蹤版本歷史，Node 專案靠 package.json 管理套件。
單純要跑 clasp push/pull，其實不需要 package.json 也能運作，所以這一步不是必要。
但文章後面會裝一個讓 VS Code 支援 Apps Script 自動完成的套件（@types/google-apps-script），那時就會用到 package.json 來記錄它。
既然早晚會用到，一開始就先初始化比較順。
在終端機輸入：
npm init它會問你一連串問題（名稱、版本、描述等等），全部按 Enter 使用預設值就好。
執行完資料夾裡會多出一個 package.json 檔案。
建立 src 子資料夾放程式碼
為什麼要多建一個子資料夾？
下一步執行 clasp clone 時，Apps Script 的程式檔（Code.js、appsscript.json、HTML 檔）就會下載進來。
如果這些檔案直接丟在根目錄，會跟 package.json、以後裝套件產生的 node_modules/ 等設定檔混在一起：
❌ 全部塞根目錄
clasp-tutorial/
├── package.json ← 專案設定
├── node_modules/ ← 專案設定
├── Code.js ← 程式碼
├── appsscript.json ← 程式碼
└── myHTML.html ← 程式碼眼睛要在「設定」和「程式碼」之間來回切，時間久了很煩，也容易不小心改錯檔案。
把程式碼挪到 src/ 之後，兩種檔案就分得開：
✅ 程式碼集中在 src/
clasp-tutorial/
├── package.json ← 專案設定
├── node_modules/ ← 專案設定
└── src/
├── Code.js ← 程式碼
├── appsscript.json
└── myHTML.html要改程式就點 src/，要改專案設定就看根目錄。
在 VS Code 左邊檔案區新增一個資料夾叫 src。
名字是 source 的縮寫（意思是「原始碼」），這是整個 Node 生態的共同慣例——其他開發者看到你的專案，會本能地先到 src/ 裡找程式碼。
技術上你當然可以命名成 code/、app/ 或其他名字，但用 src 最省溝通成本。
第七步：把 Apps Script 專案下載到本地（clasp clone）
現在可以把雲端的專案「克隆（clone）」到本地了。
在終端機輸入：
clasp clone "你的Script ID" --rootDir src有幾個細節要注意：
Script ID 要放在雙引號 " 裡面。
--rootDir src 這個參數，是在告訴 CLASP：「請把下載下來的檔案放到 src 這個子資料夾，不要放根目錄。」
參數裡的 rootDir，中間那個 D 要大寫，寫成 rootdir 會無效。
執行完之後，src 資料夾裡會出現兩個檔案：
Code.js：就是網頁編輯器裡原本那個Code.gs檔。appsscript.json：Apps Script 的設定檔。
appsscript.json 是什麼？Apps Script 的清單檔
這個檔案正式的名稱叫「manifest（清單檔）」，是 Apps Script 專案的身分證。
它不是程式碼，而是一份 JSON 格式的設定，用來告訴 Google：「這個專案是什麼東西、要用什麼執行環境跑、需要哪些權限。」
打開它會看到類似這樣的內容：
{
"timeZone": "Asia/Taipei",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8"
}逐欄解釋：
timeZone：這個專案用哪個時區跑。像是new Date()取出來的時間就會用這個時區。runtimeVersion：用哪個版本的 JavaScript 引擎。V8是現代版（支援let、箭頭函式等新語法），舊專案可能還留著STABLE（Rhino 引擎，語法比較舊）。dependencies：這個專案有用到哪些函式庫（libraries）或進階服務（例如進階 Drive API、進階 Gmail API）。新專案通常是空的{}。exceptionLogging：錯誤要記去哪。STACKDRIVER代表送到 Google Cloud 的日誌系統。
專案比較進階時，還會多出幾個欄位：
oauthScopes：這個專案要存取 Gmail、試算表還是雲端硬碟？每一個都是一個 scope。把專案發佈給別人用時，這邊列出什麼，Google 授權畫面就會跟使用者說「這個 App 要存取 OOO」。webapp：如果要把專案部署成 Web App（讓別人透過網址開啟），這邊會設定誰能存取、以誰的身份執行。
類比一下前面介紹過的 package.json：
為什麼網頁編輯器預設隱藏 appsscript.json
因為大部分情況下，你根本不用動這個檔案。
Apps Script 網頁編輯器會依據你的操作自動維護它——例如你呼叫了 GmailApp，它會自動加上對應的 oauthScopes；你新增了一個函式庫，它會自動更新 dependencies。
但用 CLASP 做本地開發，下載檔案時會一視同仁全部抓下來，所以你會看到 appsscript.json 出現在 src/ 裡。
如果想在網頁編輯器裡也看到它，可以到「檢視 → 顯示資訊清單檔案」開啟顯示。
Apps Script 的 .gs 和 .js 副檔名差在哪
在 Google 網頁編輯器裡，Apps Script 的檔案副檔名是 .gs（Google Script）。
但下載到本地之後，副檔名會自動變成 .js（JavaScript 的標準副檔名）。
之後推送回雲端時，CLASP 會再幫你自動轉回 .gs。
那 .gs 跟 .js 到底差在哪？
以現在來說，實際上只差在檔名本身，內容完全是同一套 JavaScript。
因為 2020 年之後，Apps Script 改用 V8 引擎（就是跑 Chrome、Node.js 的那顆），所以 .gs 裡寫的語法就是現代 JavaScript，能用 let、const、箭頭函式、模板字串、class 這些。
但歷史上不是這樣的。
2020 年之前，Apps Script 用的是一顆叫 Rhino 的舊引擎，當時 .gs 只支援 ES5 語法，很多現代 JavaScript 寫法會直接報錯。
Google 當年給它取名 .gs 而不是 .js，某種程度上就是暗示「這不完全是你熟悉的那個 JavaScript」。
升級到 V8 之後，這個差異消失了，但檔名沒跟著改，主要是為了向下相容（避免把幾百萬個舊專案搞壞）。
對你的實務影響：
- 在 VS Code 寫
.js檔時，編輯器會用標準 JavaScript 的語法高亮和自動完成——這比在網頁編輯器裡寫.gs體驗好很多，因為一般編輯器本來就不認識.gs。 - 推送上雲端後，Google 會把它當 Apps Script 執行，可以使用
SpreadsheetApp、GmailApp這些 Google 專屬的 API。 - 兩邊的語法能力一致，所以你不用為了副檔名不同而改寫任何程式碼。
簡單說：.gs 和 .js 的轉換只是 CLASP 做的「換個殼」而已，程式本身動都沒動。
核心觀念：push 與 pull 是兩條不同的路
這是整個 CLASP 工作流程裡最重要的觀念，請務必理解。
本地電腦和 Google 伺服器是兩個獨立的地方，檔案不會自動同步。
你在 VS Code 按存檔，只是把變更存到本地而已，雲端那邊完全不知道。
反之，直接在網頁編輯器改程式，本地這邊也不會更新。
要讓兩邊同步，得靠 CLASP 的兩個指令：
- clasp push：把「本地的版本」送到伺服器，覆蓋雲端的版本（本地 → 伺服器）。
- clasp pull：把「伺服器的版本」抓下來，覆蓋本地的版本（伺服器 → 本地）。
情境一：在本地改了程式，要同步上雲端
假設你的 Code.js 裡有這麼一個函式：
function sayHello() {
Logger.log('Hello');
}你在 VS Code 裡把字串 Hello 改成 Bye：
function sayHello() {
Logger.log('Bye');
}然後按 Ctrl+S（Windows） / Cmd+S（Mac）存檔。
這時候雲端上其實還是舊版本。
就算你重新整理 Apps Script 網頁編輯器，看到的還是原本的 Hello。
要真的讓修改生效，在終端機執行：
clasp push執行成功會顯示「2 files pushed」之類的訊息。
這時候再到網頁編輯器按重新整理，就會看到最新的內容。
情境二：在網頁編輯器改了程式，要抓回本地
反過來的情況也一樣。
如果你（或團隊其他人）直接在 Google 網頁編輯器改了程式並存檔，這些改動只存在雲端。
就算你把 VS Code 關掉再重開，本地的檔案還是舊的。
要把雲端最新版抓回本地，執行：
clasp pull執行完，本地檔案就會被更新成雲端的版本。
clasp push -w：存檔時自動推送
每次存檔都要手動打 clasp push 其實蠻煩的，尤其是你正在頻繁測試的時候。
CLASP 提供了「監看模式」，開著之後，它會盯著你的檔案，一存檔就自動推送。
指令是：
clasp push -w注意是 -w 不是 --watch（原始影片中講者一開始也打錯了，後來才更正）。
執行之後，終端機會卡在那邊、不回到一般提示符號，這是正常的。
它其實在「監聽」你的檔案變化。
之後每次你按存檔，幾秒內它就會自動把變更推到雲端。
怎麼停掉 clasp push -w（按 Ctrl+C）
當你想結束監看、回到一般終端機時：
- 先用滑鼠點一下終端機視窗，確認游標在裡面。
- 按下
Ctrl + C。
即使你是 Mac 使用者，這裡也要按 Ctrl，不是 Cmd。
讓 VS Code 支援 Apps Script 的自動完成
什麼是自動完成、為什麼 VS Code 沒反應
你可能注意到：在網頁版 Apps Script 編輯器裡，打 SpreadsheetApp. 的那個點一出現，編輯器就會彈出一張選單，列出 getActiveSpreadsheet()、getActiveSheet()、openById() 這些可用的方法。
這就是自動完成——你不用硬背 API 名稱，打幾個字看到選單就能挑，大幅提升寫程式的效率。
但同樣的操作在 VS Code 裡完全沒反應。
原因是：SpreadsheetApp、DriveApp、GmailApp 這些不是標準 JavaScript 的物件，而是 Google Apps Script 執行時才會出現的全域變數。
VS Code 只看你本地的 .js 檔，它無法知道 Google 後台有哪些物件。
解法是補上一份「外部說明書」，告訴 VS Code「有哪些全域物件、各自有哪些方法」。
這份說明書在 JavaScript 世界叫做型別定義檔（type definitions）。
安裝 Apps Script 的型別定義檔
在終端機執行：
npm install --save-dev @types/google-apps-script這行指令的幾個重點：
--save-dev：表示「這個套件只在開發時用」。它會被記錄到package.json的devDependencies區，不會被 CLASP 推送到 Google 伺服器，也不會影響線上執行。簡單說，這個套件只活在你的電腦上，讓 VS Code 看得懂 API 而已。@types/開頭：這是 JavaScript 社群 DefinitelyTyped 專案的命名慣例。它是 JavaScript 世界最大的型別定義收錄地，熱門套件（jQuery、React、Node.js 等）的型別定義都以@types/xxx的形式發佈在 NPM 上。
裝完之後，回到任何 .js 檔輸入 SpreadsheetApp.，VS Code 就會跳出 getActiveSpreadsheet()、getActiveSheet() 等方法的建議選單，體驗跟網頁編輯器一致。
型別定義檔的限制：新 API 可能還沒跟上
@types/google-apps-script 不是 Google 官方出的，是 DefinitelyTyped 社群的開發者人工維護的。
這代表偶爾會有落差——如果 Google 剛推出某個新 API，社群可能還沒跟上，你輸入 . 時那個新方法不會出現在選單。
不過這不代表方法不能用，只是 VS Code 不知道它存在而已，手動打完整個方法名照樣能 clasp push 上去正常執行。
對初學者來說這個落差幾乎不影響使用，不用太擔心。
在本地建立 HTML 檔案
CLASP 最大的好處之一，就是可以舒服地編輯 HTML 檔案。
在 src 資料夾裡新增一個檔案，副檔名用 .html，例如 myHTML.html。
VS Code 會自動辨識這是 HTML 檔，立刻啟用語法高亮、Emmet 快捷輸入等功能。
舉個例子，你可以在 HTML 檔裡寫：
<h1>Hello from Sidebar</h1>然後在 JavaScript 檔裡寫一個函式，把這個 HTML 顯示成試算表的側邊欄：
function addToSidebar() {
var html = HtmlService.createHtmlOutputFromFile('myHTML');
SpreadsheetApp.getUi().showSidebar(html);
}存檔後執行 clasp push（或是已經開著 -w 監看模式），然後回到網頁編輯器執行這個函式。
第一次執行會跳出權限授權畫面，授權完就會看到側邊欄顯示出你寫的 HTML 內容。
CLASP 安裝與使用重點整理
我們完整走過了用 CLASP 做本地開發的流程，重點整理如下：
安裝三步驟：先裝 VS Code，再裝 Node.js，最後用 npm install -g @google/clasp 安裝 CLASP。
Windows 使用者特別注意：全域安裝要用「以系統管理員身分執行」的命令提示字元。
環境設定：到 Google 帳號設定開啟 Apps Script API，然後執行 clasp login 連結帳號。
下載專案：先從專案屬性複製 Script ID，再用 clasp clone "Script ID" --rootDir src 把專案抓下來。
核心同步規則：clasp push 是本地 → 伺服器，clasp pull 是伺服器 → 本地，兩邊不會自動同步。
效率技巧：用 clasp push -w 開啟監看模式自動推送，按 Ctrl + C 結束。
自動完成：安裝 @types/google-apps-script 讓 VS Code 認得 Apps Script 的內建物件。
掌握這些之後，你就可以用自己熟悉的編輯器、搭配 Git 版本控制，用更專業的方式開發 Google Apps Script 了。