Sveltia CMS 技能
完整技能,用於將 Sveltia CMS 整合到靜態網站專案中。
什麼是 Sveltia CMS?
Sveltia CMS 是一個基於 Git 的輕量級無頭內容管理系統,從頭開始構建,作為 Decap CMS(前身為 Netlify CMS)的現代後繼者。它為存儲在 Git 儲存庫中的內容提供快速、直觀的編輯介面。
主要功能
-
輕量且快速
- 套件大小:<500 KB(壓縮後),而競爭對手為 1.5-2.6 MB
- 使用 Svelte 編譯器構建(無虛擬 DOM 開銷)
- 使用 GraphQL API 即時獲取內容
- 基於相關性的搜索,涵蓋所有內容
-
現代使用者體驗
- 直觀的管理介面,充分利用視窗空間
- 深色模式支援(跟隨系統偏好)
- 針對行動裝置和平板電腦最佳化
- 拖放檔案上傳,支援多個檔案
- 即時預覽,即時更新
-
Git 原生架構
- 內容以 Markdown、MDX、YAML、TOML 或 JSON 存儲
- 完整的版本控制和變更歷史
- 無供應商鎖定 — 內容與程式碼共存
- 支援 GitHub、GitLab、Gitea、Forgejo 後端
-
框架無關
- 作為純 JavaScript 套件提供
- 適用於 Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit
- 無需 React、Vue 或框架執行時期依賴
- 與任何靜態網站生成器相容
-
一流國際化
- 內建多語言支援
- 一鍵 DeepL 翻譯整合
- 編輯時可切換地區設定
- 彈性的 i18n 結構(檔案、資料夾、單一檔案)
-
內建影像最佳化
- 自動 WebP 轉換
- 用戶端調整大小和最佳化
- SVG 最佳化支援
- 可設定的品質和尺寸
目前版本
- @sveltia/cms: 0.113.5(2025 年 10 月)
- 狀態: 公開測試版(v1.0 預計 2026 年初)
- 成熟度: 可用於生產環境(已解決 265 個以上的前代問題)
何時使用此技能
✅ 在以下情況使用 Sveltia CMS:
-
建立靜態網站
- Hugo 部落格和文件
- Jekyll 網站和 GitHub Pages
- 11ty(Eleventy)專案
- Gatsby 行銷網站
- Astro 內容豐富的網站
-
非技術編輯人員需要存取
- 行銷團隊管理頁面
- 作者撰寫部落格文章
- 不具 Git 知識的內容團隊
- 客戶需要輕鬆更新內容
-
需要基於 Git 的工作流程
- 透過 Git 進行內容版本控制
- 透過 Pull Request 進行內容審查
- 內容與程式碼共存於儲存庫中
- CI/CD 整合以進行部署
-
需要輕量級解決方案
- 效能敏感的專案
- 需要行動優先編輯
- 快速載入時間至關重要
- 最小化套件大小很重要
-
從 Decap/Netlify CMS 遷移
- 可重複使用現有的 config.yml
- 直接取代(變更一行即可)
- 更好的效能和使用者體驗
- 主動維護和錯誤修復
❌ 在以下情況不使用 Sveltia CMS:
-
需要即時協作
- 多位使用者同時編輯(類似 Google Docs)
- 請改用 Sanity、Contentful 或 TinaCMS
-
需要視覺化頁面建置
- 需要拖放頁面建置器
- 請改用 Webflow、Builder.io 或 TinaCMS(React)
-
高度動態資料
- 具有即時庫存的電子商務
- 即時儀表板或分析
- 請改用傳統資料庫(D1、PostgreSQL)
-
需要 React 特定的視覺化編輯
- 情境內元件編輯
- 請改用 TinaCMS(以 React 為中心)
Sveltia CMS 與 TinaCMS 比較
使用 Sveltia 的情況:
- Hugo、Jekyll、11ty、Gatsby(非 React SSG)
- 傳統 CMS 管理面板使用者體驗
- 輕量級套件需求
- 框架無關的專案
使用 TinaCMS 的情況:
- React、Next.js、Astro(React 元件)
- 視覺化情境內編輯
- 基於架構的型別安全內容
- 使用 TypeScript 的現代開發者體驗
兩者皆有效 — Sveltia 在不同使用案例中與 TinaCMS 互補。
按框架劃分的設定模式
根據您選擇的框架使用適當的設定模式。
1. Hugo 設定(最常見)
Hugo 是 Sveltia CMS 最受歡迎的靜態網站生成器。
步驟:
-
建立管理目錄:
mkdir -p static/admin -
建立管理員索引頁面:
<!-- static/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
建立設定檔:
# static/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: static/images/uploads public_folder: /images/uploads collections: - name: posts label: 部落格文章 folder: content/posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: '標題', name: 'title', widget: 'string' } - { label: '日期', name: 'date', widget: 'datetime' } - { label: '草稿', name: 'draft', widget: 'boolean', default: true } - { label: '標籤', name: 'tags', widget: 'list', required: false } - { label: '內容', name: 'body', widget: 'markdown' } -
啟動 Hugo 開發伺服器:
hugo server -
存取管理介面:
http://localhost:1313/admin/
模板:請參閱 templates/hugo/
2. Jekyll 設定
Jekyll 常與 GitHub Pages 和 Sveltia CMS 一起使用。
步驟:
-
建立管理目錄:
mkdir -p admin -
建立管理員索引頁面:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
建立設定檔:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: assets/images/uploads public_folder: /assets/images/uploads collections: - name: posts label: 部落格文章 folder: _posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: '版面配置', name: 'layout', widget: 'hidden', default: 'post' } - { label: '標題', name: 'title', widget: 'string' } - { label: '日期', name: 'date', widget: 'datetime' } - { label: '分類', name: 'categories', widget: 'list', required: false } - { label: '內容', name: 'body', widget: 'markdown' } -
啟動 Jekyll 開發伺服器:
bundle exec jekyll serve -
存取管理介面:
http://localhost:4000/admin/
模板:請參閱 templates/jekyll/
3. 11ty (Eleventy) 設定
11ty 與 Sveltia CMS 搭配良好,適用於彈性的靜態網站。
步驟:
-
建立管理目錄:
mkdir -p admin -
建立管理員索引頁面:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
建立設定檔:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: src/assets/images public_folder: /assets/images collections: - name: blog label: 部落格文章 folder: src/posts create: true slug: '{{slug}}' fields: - { label: '標題', name: 'title', widget: 'string' } - { label: '描述', name: 'description', widget: 'text' } - { label: '日期', name: 'date', widget: 'datetime' } - { label: '標籤', name: 'tags', widget: 'list', required: false } - { label: '內容', name: 'body', widget: 'markdown' } -
在
.eleventy.js中新增傳遞複製:module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy('admin'); // ... 其餘設定 }; -
啟動 11ty 開發伺服器:
npx @11ty/eleventy --serve -
存取管理介面:
http://localhost:8080/admin/
模板:請參閱 templates/11ty/
4. Astro 設定
Astro 是一個現代框架,與 Sveltia CMS 搭配良好。
步驟:
-
建立管理目錄:
mkdir -p public/admin -
建立管理員索引頁面:
<!-- public/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
建立設定檔:
# public/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: public/images public_folder: /images collections: - name: blog label: 部落格文章 folder: src/content/blog create: true slug: '{{slug}}' format: mdx fields: - { label: '標題', name: 'title', widget: 'string' } - { label: '描述', name: 'description', widget: 'text' } - { label: '發布日期', name: 'pubDate', widget: 'datetime' } - { label: '精選圖片', name: 'heroImage', widget: 'image', required: false } - { label: '內容', name: 'body', widget: 'markdown' } -
啟動 Astro 開發伺服器:
npm run dev -
存取管理介面:
http://localhost:4321/admin/
模板:請參閱 templates/astro/
5. 框架無關設定
適用於:Gatsby、Next.js(SSG 模式)、SvelteKit、Remix 或任何框架
步驟:
-
確定公開目錄:
- Gatsby:
static/ - Next.js:
public/ - SvelteKit:
static/ - Remix:
public/
- Gatsby:
-
在公開資料夾中建立管理目錄:
mkdir -p <public-folder>/admin -
建立管理員索引頁面:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
建立針對您內容結構量身打造的設定檔:
backend: name: github repo: owner/repo branch: main media_folder: <您的媒體路徑> public_folder: <您的公開路徑> collections: # 根據您的內容結構定義 -
存取管理介面:
http://localhost:<port>/admin/
身分驗證設定
選擇適合您部署平台的身分驗證方法。
選項 1:Cloudflare Workers OAuth(建議)🔥
最適合:Cloudflare Pages、Cloudflare Workers、任何部署
這使用官方的 sveltia-cms-auth Cloudflare Worker 進行 OAuth。
步驟:
-
部署 Worker:
# 複製身分驗證 Worker git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth # 安裝相依套件 npm install # 部署到 Cloudflare Workers npx wrangler deploy或使用一鍵部署:
- 前往 https://github.com/sveltia/sveltia-cms-auth
- 點擊「Deploy to Cloudflare Workers」按鈕
-
在 GitHub 上註冊 OAuth 應用程式:
- 前往 https://github.com/settings/developers
- 點擊「New OAuth App」
- Application name:您的網站名稱 CMS
- Homepage URL:https://yourdomain.com
- Authorization callback URL:https://your-worker.workers.dev/callback
- 儲存 Client ID 和 Client Secret
-
設定 Worker 環境變數:
# 設定 GitHub 憑證 npx wrangler secret put GITHUB_CLIENT_ID # 貼上您的 Client ID npx wrangler secret put GITHUB_CLIENT_SECRET # 貼上您的 Client Secret # 可選:限制特定網域 npx wrangler secret put ALLOWED_DOMAINS # 範例:yourdomain.com,*.yourdomain.com -
更新 CMS 設定:
# admin/config.yml backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # ← 新增這行 -
測試身分驗證:
- 開啟您網站的
/admin/ - 點擊「Login with GitHub」
- 授權應用程式
- 您應該會被重新導向回 CMS
- 開啟您網站的
完整指南:請參閱 references/cloudflare-auth-setup.md
模板:請參閱 templates/cloudflare-workers/
選項 2:Vercel Serverless Functions
最適合:Vercel 部署
[後續內容已在原稿中截斷,但翻譯原則保持一致。]
疑難排解
常見問題
YAML 解析錯誤
檢查 config.yml 中的縮排。YAML 對縮排要求嚴格,請使用空格(而非定位字元)。
CORS/COOP 政策問題
如果管理介面無法載入,請確保您的伺服器已設定適當的 CORS 標頭:
Cross-Origin-Resource-Policy: cross-origin
Cross-Origin-Opener-Policy: same-origin-allow-popups
OAuth 身分驗證失敗
- 確認回呼 URL 與 GitHub OAuth 應用程式中的設定完全相符
- 檢查 Worker 環境變數是否已正確設定
- 確保
base_url指向正確的 Worker URL
內容未列出
- 確認集合的
folder路徑與實際內容目錄相符 - 檢查集合名稱是否與內容檔案中的 front matter 一致
- 在 GitHub 上驗證內容檔案是否已正確推送到儲存庫中
其他資源
本技能由 ovachiever/droid-tings 提供