副標：用一套設定搞定環境變數、安全儲存 API Key 與跨專案共用。
問題背景與需求
- 目標： 在 Google Apps Script（GAS）中統一管理專案設定。 將 API Key、環境參數等敏感資料安全儲存，避免硬編碼在程式中。 讓多個 GAS 專案可共用同一組設定，減少重複維護。
- 限制： PropertiesService 的容量限制（約 9KB/專案屬性）。 無法直接在不同帳號間共用，需透過 API 或同步機制。
- 輸出： 初始化與存取屬性值的範例。 安全性建議與常見錯誤整理。
💡 為什麼我會做這個？ 一開始我在 GAS 裡用 const API_KEY = '...' 直接寫死 API Key，結果上傳到 GitHub 後被掃到。後來改用 PropertiesService，不但安全性提升，還能切換測試與正式環境，不必一行行改程式。
架構與流程
[初始化設定]
↓
[透過 PropertiesService 寫入 Script Properties]
↓
[程式執行時讀取屬性值]
↓
[跨專案共用 → 發布為 Web App 或同步到 Google Sheet]
環境與版本
- OS：不限（雲端執行）
- Runtime：Google Apps Script V8
- 套件：無需額外安裝
- API：內建 PropertiesService
步驟實作
1) 初始化與寫入屬性
檔案與路徑：/gas/init/properties_init.gsfunction setProjectConfig() {
const props = PropertiesService.getScriptProperties();
props.setProperties({
'API_KEY': 'your_api_key_here',
'ENV': 'production',
'DB_URL': 'https://example.com/db'
});
Logger.log('設定已完成');
}
setProperties() 可一次寫入多個屬性，避免多次呼叫。
2) 讀取屬性
檔案與路徑：/gas/utils/config.gs
function getConfig(key) {
return PropertiesService.getScriptProperties().getProperty(key);
}
function exampleUsage() {
const apiKey = getConfig('API_KEY');
Logger.log(`目前使用的 API_KEY：${apiKey}`);
}
3) 更新或刪除屬性
function updateConfig(key, value) {
PropertiesService.getScriptProperties().setProperty(key, value);
}
function deleteConfig(key) {
PropertiesService.getScriptProperties().deleteProperty(key);
}
4) 跨專案共用設定
由於 ScriptProperties 無法直接跨專案，需要：
- 將設定存到 Google Sheet。
- 或將設定專案發布為 Web App，其他專案透過 UrlFetchApp 讀取。
範例：透過 Google Sheet 共用
function syncConfigToSheet() {
const props = PropertiesService.getScriptProperties().getProperties();
const ss = SpreadsheetApp.openById('<SHEET_ID>');
const sh = ss.getSheetByName('config');
sh.clearContents();
let i = 1;
for (let k in props) {
sh.getRange(i, 1).setValue(k);
sh.getRange(i, 2).setValue(props[k]);
i++;
}
}
5) 安全儲存 API Key
- 避免將 Key 寫死在程式碼。
- 只在需要的地方呼叫 getProperty()。
- 減少日誌中輸出完整 Key，可只顯示部分。
function safeLogKey() {
const key = getConfig('API_KEY');
Logger.log(`API_KEY (部分)：${key.substring(0, 4)}****`);
}
驗證與結果
> 執行 setProjectConfig()
設定已完成
> 執行 exampleUsage()
目前使用的 API_KEY：your_api_key_here
常見錯誤與排錯表
訊息 可能原因 解法 null 屬性未設定或拼字錯誤 確認 setProperty() 有成功執行且 key 名稱一致 Exceeded maximum size 屬性資料超過容量限制 將大資料存 Google Sheet 或 Cloud Storage undefined 讀取變數時未宣告 key 使用 getProperties() 確認有哪些 key
PropertiesService 類型差異與適用場景
類型 範圍 常見用途 優點 限制 ScriptProperties 整個專案共用 API Key、環境變數、全域設定 所有使用者共用、存取簡單 容量約 9KB；不同專案不互通 UserProperties 依使用者分開 個人偏好設定、會員等級 針對不同使用者儲存不同值 無法跨使用者共用；容量限制 DocumentProperties 與特定文件/試算表綁定 與文件綁定的設定（欄位名稱、範本 ID） 自動隨文件保存 僅適用於綁定的檔案
🔹 建議：
- 大多數情況下用 ScriptProperties 管理 API Key 與全域設定。 需要針對使用者儲存獨立資料時用 UserProperties。 綁定特定 Google 文件或試算表的情境才用 DocumentProperties。
延伸與 TODO
- 增加 UserProperties 管理個別使用者設定。
- 加入自動備份與還原機制。
- 與 Secret Manager 或 Firebase Config 整合，提升安全性。
版本資訊（Changelog）
- 2025-08-14：初稿完成
工具小筆記｜ PropertiesService 有三種型態：
- ScriptProperties：整個專案共用，最常用。
- UserProperties：每位使用者獨立儲存。
- DocumentProperties：與特定 Google 文件/試算表綁定。
