Google Sheets Fetcher

一個 Node.js 庫，用於從 Google Sheets 獲取配置和國際化（i18n）數據。

功能特性

• 📊 從 Google Sheets 讀取配置數據
• 🌍 支持多語系國際化數據獲取
• 🔧 可配置的工作表名稱和輸出路徑
• 📝 自動生成 versionConfig.json 配置文件
• 🌐 自動生成 src/locales 目錄下的語系文件
• ⚙️ 根據平台和環境生成 .env 文件
• 📦 支持 ES Module 和 CommonJS
• 🎯 TypeScript 類型支持

安裝

npm install google-sheets-fetcher
# 或
yarn add google-sheets-fetcher
# 或
pnpm add google-sheets-fetcher

設置憑證文件

在使用本庫之前，請將 Google 服務帳號的 JSON 憑證文件放置在以下位置：

~/.google-sheets/credentials.json

注意： 憑證文件會自動從該位置讀取，無需在代碼中指定路徑。

快速開始

作為庫使用

import GoogleSheetsFetcher from "google-sheets-fetcher";

// 初始化（憑證文件會自動從 ~/.google-sheets/credentials.json 讀取）
const fetcher = new GoogleSheetsFetcher({
  spreadsheetId: "YOUR_GOOGLE_SHEETS_ID",
  configSheetName: "config-pc", // 可選，默認 'config-pc'
  localeSheetName: "i18n", // 可選，默認 'i18n'
});

// 獲取配置（自動創建/更新 versionConfig.json）
const config = await fetcher.fetchConfig();
console.log(config);
// 輸出: { platform1: { key1: value1, ... }, platform2: { ... } }
// 同時會自動創建/更新 versionConfig.json 文件

// 獲取國際化數據（自動創建/更新 src/locales 目錄下的語系文件）
const locale = await fetcher.fetchLocale();
// 會自動創建 src/locales/en.json, src/locales/zh.json 等文件

// 獲取所有數據
const { config, locale } = await fetcher.fetchAll();

// 根據平台和環境生成 .env 文件（獨立函數）
import { setVersion } from "google-sheets-fetcher";
setVersion("VITE", "vincetrust", "prod");
// 會生成 .env 文件，包含 VITE_APP_ENV, VITE_APP_* 等環境變數

Google Sheets 格式要求

配置工作表格式

第一行：參數名稱 | 平台 1 | 平台 2 | ... 從第二行開始：配置項名稱 | 平台 1 的值 | 平台 2 的值 | ...

示例：

參數名稱        | vincetrust | vincetrust2
BASE_PROJECT    | .vincetrust.tsx | .vincetrust2.tsx
API_URL         | https://api.example.com | https://api2.example.com
ENABLE_FEATURE  | true | false

國際化工作表格式

第一行：Key | EN | ZH | FR | ... 從第二行開始：翻譯鍵 | 英文值 | 中文值 | 法文值 | ...

示例：

Key           | EN          | ZH        | FR
welcome.title | Welcome     | 歡迎      | Bienvenue
welcome.desc  | Description | 描述      | Description

API 文檔

GoogleSheetsFetcher

構造函數

new GoogleSheetsFetcher(options);

參數：

• options.spreadsheetId (string, 必需) - Google Sheets ID
• options.configSheetName (string, 可選) - 配置工作表名稱，默認 'config-pc'
• options.localeSheetName (string, 可選) - 國際化工作表名稱，默認 'i18n'

注意： 憑證文件會自動從 ~/.google-sheets/credentials.json 讀取，無需在參數中指定。

方法

fetchConfig()

獲取配置數據，並自動創建/更新 versionConfig.json 文件到當前工作目錄。

返回： Promise<Object> - 配置對象，格式：{ platform: { key: value } }

注意： 如果當前目錄下不存在 versionConfig.json，會自動創建；如果已存在，會自動更新。

fetchLocale()

獲取國際化數據，並自動創建/更新 src/locales 目錄下的語系文件（如 en.json、zh.json 等）。

返回： Promise<Object> - 國際化對象，格式：{ locale: { key: value } }

注意：

• 如果 src/locales 目錄不存在，會自動創建
• 根據 Google Sheets 中檢測到的語系，分別創建對應的 JSON 文件
• 如果文件已存在，會自動更新

fetchAll()

獲取所有數據（配置和國際化）。

返回： Promise<{ config: Object, locale: Object }>

注意： 會同時執行 fetchConfig() 和 fetchLocale()，自動生成所有相關文件。

獨立函數

setVersion(codeLanguage, platformName, environment?)

根據平台和環境生成 .env 文件的獨立函數。

導入方式：

import { setVersion } from "google-sheets-fetcher";
// 或
const { setVersion } = require("google-sheets-fetcher");

參數：

• codeLanguage (string, 必需) - 程式語言前綴，如 "VITE"、"REACT_APP" 等
• platformName (string, 必需) - 平台名稱，必須存在於 versionConfig.json 中
• environment (string, 可選) - 環境類型，可選值："dev"、"stag"、"prod"，默認 "prod"

返回： void

使用示例：

import GoogleSheetsFetcher, { setVersion } from "google-sheets-fetcher";

const fetcher = new GoogleSheetsFetcher({
  spreadsheetId: "YOUR_SHEETS_ID"
});

// 先獲取配置
await fetcher.fetchConfig();

// 然後生成 .env 文件
setVersion("VITE", "vincetrust", "prod");

注意：

• 需要先執行 fetchConfig() 生成 versionConfig.json 文件
• 生成的環境變數格式：{codeLanguage}_APP_ENV、{codeLanguage}_APP_{key} 等
• 支持配置值的環境特定覆蓋（如果配置值是對象，會根據環境選擇對應的值）
• 特殊處理 BASE_PROJECT 配置項，會生成擴展名列表

設置 Google 服務帳號

1. 前往 Google Cloud Console

2. 創建新項目或選擇現有項目

3. 啟用 Google Sheets API

4. 創建服務帳號

5. 下載 JSON 憑證文件

6. 將 Google Sheets 分享給服務帳號的郵箱地址

7. 將憑證文件放置在 ~/.google-sheets/credentials.json

   # 創建目錄（如果不存在）
   mkdir -p ~/.google-sheets
   
   # 移動憑證文件到該位置
   mv /path/to/your-credentials.json ~/.google-sheets/credentials.json
   
   # 設置適當的權限（僅自己可讀）
   chmod 600 ~/.google-sheets/credentials.json

類型支持

本庫提供 TypeScript 類型定義：

import GoogleSheetsFetcher from "google-sheets-fetcher";

// 憑證文件會自動從 ~/.google-sheets/credentials.json 讀取
const fetcher = new GoogleSheetsFetcher({
  spreadsheetId: "YOUR_SHEETS_ID",
});

許可證

MIT

貢獻

歡迎提交 Issue 和 Pull Request！