Communitygithub.com

ovachiever/droid-tings

設定 Sveltia CMS — 輕量級、基於 Git 的內容管理系統,是 Decap/Netlify CMS 的後繼者,具備 5 倍更小的套件(300 KB)、GraphQL 效能,並修復了 260 多個前代問題。框架無關,適用於 Hugo、Jekyll、11ty、Gatsby、Astro。

droid-tings 是什麼?

這項技能提供完整的指引,協助您將 Sveltia CMS 整合到靜態網站專案中。Sveltia CMS 是一款基於 Svelte 的輕量級無頭 CMS,作為 Decap CMS(原 Netlify CMS)的現代後繼者,能提供更快速的編輯體驗與更小的套件體積(低於 500 KB)。技能內容涵蓋多種框架的設定模式,包括 Hugo、Jekyll、11ty、Astro 等,並說明如何透過 Cloudflare Workers 或 Vercel Serverless Functions 設定 OAuth 身分驗證。此外,詳細介紹了 Sveltia CMS 的關鍵功能,例如 GraphQL API 支援、即時預覽、內建國際化、影像最佳化,以及與 TinaCMS 的比較,協助開發者選擇最合適的解決方案。這項技能適用於靜態網站開發、非技術編輯人員的內容管理,以及從 Decap/Netlify CMS 遷移的專案。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/sveltia-cms

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Sveltia CMS 技能

完整技能,用於將 Sveltia CMS 整合到靜態網站專案中。


什麼是 Sveltia CMS?

Sveltia CMS 是一個基於 Git 的輕量級無頭內容管理系統,從頭開始構建,作為 Decap CMS(前身為 Netlify CMS)的現代後繼者。它為存儲在 Git 儲存庫中的內容提供快速、直觀的編輯介面。

主要功能

  1. 輕量且快速

    • 套件大小:<500 KB(壓縮後),而競爭對手為 1.5-2.6 MB
    • 使用 Svelte 編譯器構建(無虛擬 DOM 開銷)
    • 使用 GraphQL API 即時獲取內容
    • 基於相關性的搜索,涵蓋所有內容
  2. 現代使用者體驗

    • 直觀的管理介面,充分利用視窗空間
    • 深色模式支援(跟隨系統偏好)
    • 針對行動裝置和平板電腦最佳化
    • 拖放檔案上傳,支援多個檔案
    • 即時預覽,即時更新
  3. Git 原生架構

    • 內容以 Markdown、MDX、YAML、TOML 或 JSON 存儲
    • 完整的版本控制和變更歷史
    • 無供應商鎖定 — 內容與程式碼共存
    • 支援 GitHub、GitLab、Gitea、Forgejo 後端
  4. 框架無關

    • 作為純 JavaScript 套件提供
    • 適用於 Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit
    • 無需 React、Vue 或框架執行時期依賴
    • 與任何靜態網站生成器相容
  5. 一流國際化

    • 內建多語言支援
    • 一鍵 DeepL 翻譯整合
    • 編輯時可切換地區設定
    • 彈性的 i18n 結構(檔案、資料夾、單一檔案)
  6. 內建影像最佳化

    • 自動 WebP 轉換
    • 用戶端調整大小和最佳化
    • SVG 最佳化支援
    • 可設定的品質和尺寸

目前版本

  • @sveltia/cms: 0.113.5(2025 年 10 月)
  • 狀態: 公開測試版(v1.0 預計 2026 年初)
  • 成熟度: 可用於生產環境(已解決 265 個以上的前代問題)

何時使用此技能

✅ 在以下情況使用 Sveltia CMS:

  1. 建立靜態網站

    • Hugo 部落格和文件
    • Jekyll 網站和 GitHub Pages
    • 11ty(Eleventy)專案
    • Gatsby 行銷網站
    • Astro 內容豐富的網站
  2. 非技術編輯人員需要存取

    • 行銷團隊管理頁面
    • 作者撰寫部落格文章
    • 不具 Git 知識的內容團隊
    • 客戶需要輕鬆更新內容
  3. 需要基於 Git 的工作流程

    • 透過 Git 進行內容版本控制
    • 透過 Pull Request 進行內容審查
    • 內容與程式碼共存於儲存庫中
    • CI/CD 整合以進行部署
  4. 需要輕量級解決方案

    • 效能敏感的專案
    • 需要行動優先編輯
    • 快速載入時間至關重要
    • 最小化套件大小很重要
  5. 從 Decap/Netlify CMS 遷移

    • 可重複使用現有的 config.yml
    • 直接取代(變更一行即可)
    • 更好的效能和使用者體驗
    • 主動維護和錯誤修復

❌ 在以下情況不使用 Sveltia CMS:

  1. 需要即時協作

    • 多位使用者同時編輯(類似 Google Docs)
    • 請改用 Sanity、Contentful 或 TinaCMS
  2. 需要視覺化頁面建置

    • 需要拖放頁面建置器
    • 請改用 Webflow、Builder.io 或 TinaCMS(React)
  3. 高度動態資料

    • 具有即時庫存的電子商務
    • 即時儀表板或分析
    • 請改用傳統資料庫(D1、PostgreSQL)
  4. 需要 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 最受歡迎的靜態網站生成器。

步驟:

  1. 建立管理目錄:

    mkdir -p static/admin
    
  2. 建立管理員索引頁面:

    <!-- 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>
    
  3. 建立設定檔:

    # 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' }
    
  4. 啟動 Hugo 開發伺服器:

    hugo server
    
  5. 存取管理介面:

    http://localhost:1313/admin/
    

模板:請參閱 templates/hugo/


2. Jekyll 設定

Jekyll 常與 GitHub Pages 和 Sveltia CMS 一起使用。

步驟:

  1. 建立管理目錄:

    mkdir -p admin
    
  2. 建立管理員索引頁面:

    <!-- 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>
    
  3. 建立設定檔:

    # 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' }
    
  4. 啟動 Jekyll 開發伺服器:

    bundle exec jekyll serve
    
  5. 存取管理介面:

    http://localhost:4000/admin/
    

模板:請參閱 templates/jekyll/


3. 11ty (Eleventy) 設定

11ty 與 Sveltia CMS 搭配良好,適用於彈性的靜態網站。

步驟:

  1. 建立管理目錄:

    mkdir -p admin
    
  2. 建立管理員索引頁面:

    <!-- 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>
    
  3. 建立設定檔:

    # 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' }
    
  4. 在 .eleventy.js 中新增傳遞複製:

    module.exports = function(eleventyConfig) {
      eleventyConfig.addPassthroughCopy('admin');
      // ... 其餘設定
    };
    
  5. 啟動 11ty 開發伺服器:

    npx @11ty/eleventy --serve
    
  6. 存取管理介面:

    http://localhost:8080/admin/
    

模板:請參閱 templates/11ty/


4. Astro 設定

Astro 是一個現代框架,與 Sveltia CMS 搭配良好。

步驟:

  1. 建立管理目錄:

    mkdir -p public/admin
    
  2. 建立管理員索引頁面:

    <!-- 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>
    
  3. 建立設定檔:

    # 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' }
    
  4. 啟動 Astro 開發伺服器:

    npm run dev
    
  5. 存取管理介面:

    http://localhost:4321/admin/
    

模板:請參閱 templates/astro/


5. 框架無關設定

適用於:Gatsby、Next.js(SSG 模式)、SvelteKit、Remix 或任何框架

步驟:

  1. 確定公開目錄:

    • Gatsby:static/
    • Next.js:public/
    • SvelteKit:static/
    • Remix:public/
  2. 在公開資料夾中建立管理目錄:

    mkdir -p <public-folder>/admin
    
  3. 建立管理員索引頁面:

    <!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>
    
  4. 建立針對您內容結構量身打造的設定檔:

    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: <您的媒體路徑>
    public_folder: <您的公開路徑>
    
    collections:
      # 根據您的內容結構定義
    
  5. 存取管理介面:

    http://localhost:<port>/admin/
    

身分驗證設定

選擇適合您部署平台的身分驗證方法。

選項 1:Cloudflare Workers OAuth(建議)🔥

最適合:Cloudflare Pages、Cloudflare Workers、任何部署

這使用官方的 sveltia-cms-auth Cloudflare Worker 進行 OAuth。

步驟:

  1. 部署 Worker:

    # 複製身分驗證 Worker
    git clone https://github.com/sveltia/sveltia-cms-auth
    cd sveltia-cms-auth
    
    # 安裝相依套件
    npm install
    
    # 部署到 Cloudflare Workers
    npx wrangler deploy
    

    或使用一鍵部署:

  2. 在 GitHub 上註冊 OAuth 應用程式:

  3. 設定 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
    
  4. 更新 CMS 設定:

    # admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://your-worker.workers.dev  # ← 新增這行
    
  5. 測試身分驗證:

    • 開啟您網站的 /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 提供

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能