萌典 CloudFlare Worker

這是 moedict-webkit 的 CloudFlare Worker 版本，將原本的 Node.js 後端遷移到無伺服器環境。

專案概念

技術棧

• CloudFlare Workers: 無伺服器運行環境
• TypeScript: 主要開發語言
• KV Storage: 字典資料儲存
• R2 Storage: 字體和靜態資源
• @cf-wasm/resvg: SVG 轉 PNG 轉換

功能對應

原功能	CloudFlare Worker 實現
/:text.json	字典查詢 API
/:text.png	文字轉圖片生成
/:text	HTML 頁面渲染
靜態資源	R2 Storage 服務

核心特色

• ✅ 無伺服器架構: 使用 CloudFlare Workers
• ✅ 自動擴展: 根據需求自動調整資源
• ✅ 全球 CDN: 利用 CloudFlare 的全球網路
• ✅ 成本效益: 按使用量計費
• ✅ 高可用性: 99.9% 服務可用性

快速開始

環境需求

• Node.js 18+
• npm 或 yarn
• CloudFlare 帳號

安裝依賴

npm install

本地開發

# 啟動開發伺服器
npx wrangler dev --remote

# 測試功能
curl "http://localhost:8787/萌.json"
curl "http://localhost:8787/萌.png"
curl "http://localhost:8787/萌"

設定資產端點（ASSET_BASE_URL）

• 本專案的 CSS/JS/圖片/字體會透過 ASSET_BASE_URL 從 R2 公開端點載入。
• 請先複製範本設定，並填上你自己的 bucket 與公開端點：

cp wrangler.jsonc.example wrangler.jsonc
# 編輯 wrangler.jsonc → vars.ASSET_BASE_URL: "https://<your-pub-id>.r2.dev"

• 若未設定 ASSET_BASE_URL，伺服器端渲染會直接報錯提示。

部署到 CloudFlare

1. 設置 CloudFlare 認證

wrangler auth login

2. 創建必要資源

# 創建 R2 Storage
wrangler r2 bucket create moedict-fonts
wrangler r2 bucket create moedict-fonts-preview
wrangler r2 bucket create moedict-assets
wrangler r2 bucket create moedict-assets-preview
wrangler r2 bucket create moedict-dictionary
wrangler r2 bucket create moedict-dictionary-preview

3. 更新配置

• 以 wrangler.jsonc.example 為範本建立 wrangler.jsonc
• 在 vars 設定你的公開資產端點：

{
  "vars": {
    "ASSET_BASE_URL": "https://<your-pub-id>.r2.dev"
  }
}

4. 部署 Worker

# 部署到生產環境
npm run deploy

# 或使用 wrangler 直接部署
wrangler deploy

專案結構

cf-moedict-webkit/
├── src/
│   ├── index.ts              # 主要入口點
│   ├── types.ts              # TypeScript 類型定義
│   ├── dictionary.ts         # 字典查詢邏輯
│   ├── image-generation.ts  # 圖片生成邏輯
│   ├── page-rendering.ts     # 頁面渲染邏輯
│   └── static-assets.ts      # 靜態資源處理
├── wrangler.jsonc            # CloudFlare Worker 配置
├── package.json              # 專案依賴
├── tsconfig.json             # TypeScript 配置
├── 工程計劃.md               # 開發計劃
└── DEPLOYMENT.md             # 詳細部署指南

API 端點

字典查詢

GET /:text.json

• 查詢指定文字的字典定義
• 支援華語、台語、客語、兩岸詞典

圖片生成

GET /:text.png?font=kai

• 將文字轉換為 PNG 圖片
• 支援多種字體 (kai, ming, song, hei)

頁面渲染

GET /:text

• 渲染完整的 HTML 頁面
• 包含字典定義和社交分享功能

開發指南

本地測試

# 啟動開發伺服器
npx wrangler dev --remote

# 測試不同功能
curl "http://localhost:8787/萌.json"      # 字典查詢
curl "http://localhost:8787/萌.png"        # 圖片生成
curl "http://localhost:8787/萌"            # 頁面渲染
curl "http://localhost:8787/about.html"   # 關於頁面

# 驗證靜態資源是否走 ASSET_BASE_URL：
# 打開瀏覽器 devtools → Network，確認 CSS/JS/字體/圖片皆從你的 r2.dev 載入

部置

npx wrangler deploy

除錯

# 查看 Worker 日誌
wrangler tail

# 查看特定請求
wrangler tail --format=pretty

性能監控

• 使用 CloudFlare Analytics 監控性能
• 監控 KV Storage 和 R2 Storage 使用量
• 設置告警機制

資料遷移

字典資料

需要將原始專案的字典資料遷移到 KV Storage：

• a/ 目錄 (華語詞典)
• t/ 目錄 (台語詞典)
• h/ 目錄 (客語詞典)
• c/ 目錄 (兩岸詞典)

靜態資源

需要將字體和靜態資源上傳到 R2 Storage：

• fonts/ 目錄 (字體檔案)
• css/ 目錄 (樣式表)
• js/ 目錄 (JavaScript 檔案)
• images/ 目錄 (圖片資源)

可用 rclone 上傳（需先 rclone config 設定 Cloudflare R2，endpoint 形如 https://<account-id>.r2.cloudflarestorage.com）：

# 依你的 remote 名稱調整，例如 r2:
rclone sync assets r2:moedict-assets

故障排除

常見問題

1. 認證失敗

   wrangler auth login

2. KV namespace 不存在

   wrangler kv:namespace create "DICTIONARY"

3. R2 bucket 不存在

   wrangler r2 bucket create moedict-fonts
   wrangler r2 bucket create moedict-assets

4. 圖片生成失敗

   • 檢查字體檔案是否已上傳
   • 檢查 R2 Storage 配置
   • 查看 Worker 日誌

貢獻

1. Fork 專案
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交變更 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

授權

本專案基於原始 moedict-webkit 專案，遵循相同的授權條款。

相關連結

• 原始 moedict-webkit 專案
• CloudFlare Workers 文檔
• 萌典官網