Communitygithub.com

Sveltia CMS 集成技能

设置 Sveltia CMS - 轻量级、基于 Git 的后台内容管理系统,是 Decap/Netlify CMS 的继任者,拥有 5 倍更小的包体积(300 KB)、GraphQL 性能,并修复了 260+ 个前代问题。支持 Hugo、Jekyll、11ty、Gatsby、Astro 等框架。

Sveltia CMS 集成技能 是什么?

此技能为将 Sveltia CMS 集成到静态站点项目提供全面指导。Sveltia CMS 是轻量级、基于 Git 的无头 CMS,作为 Decap CMS(原 Netlify CMS)的现代继任者,从头构建。它提供快速直观的编辑界面,内容存储在 Git 仓库中。技能详细介绍其核心优势,包括极小的包体积(<500 KB)、通过 Svelte 编译器实现的高性能、使用 GraphQL API 进行即时内容获取、内置国际化支持、图片优化以及 Git 原生架构。此外,技能清晰列出了其适用和不适用场景,并将其与 TinaCMS 等竞品进行了对比。核心部分提供了针对 Hugo、Jekyll、11ty、Astro 等主流框架的分步设置指南,以及通用的框架无关设置方法。技能还深入讲解了多种身份验证方案,特别是通过 Cloudflare Workers 或 Vercel Serverless Functions 进行 OAuth 认证的配置,这解决了静态站点 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(minified/brotlied),而竞品为 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 进行内容版本控制
    • 通过拉取请求进行内容审查
    • 内容与代码共存于仓库
    • 用于部署的 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 组件)
  • 可视化上下文内编辑
  • 基于 Schema 的类型安全内容
  • 现代开发者体验(TypeScript)

两者都有效 - Sveltia 补充了 TinaCMS 在不同用例中的不足。


按框架的设置模式

根据您选择的框架使用合适的设置模式。

1. Hugo 设置(最常见)

Hugo 是 Sveltia CMS 最流行的静态站点生成器。

步骤:

  1. 创建 admin 目录:

    mkdir -p static/admin
    
  2. 创建 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>
    
  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: Blog Posts
        folder: content/posts
        create: true
        slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
        fields:
          - { label: 'Title', name: 'title', widget: 'string' }
          - { label: 'Date', name: 'date', widget: 'datetime' }
          - { label: 'Draft', name: 'draft', widget: 'boolean', default: true }
          - { label: 'Tags', name: 'tags', widget: 'list', required: false }
          - { label: 'Body', name: 'body', widget: 'markdown' }
    
  4. 启动 Hugo 开发服务器:

    hugo server
    
  5. 访问后台:

    http://localhost:1313/admin/
    

模板:参见 templates/hugo/


2. Jekyll 设置

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

步骤:

  1. 创建 admin 目录:

    mkdir -p admin
    
  2. 创建 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>
    
  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: Blog Posts
        folder: _posts
        create: true
        slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
        fields:
          - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' }
          - { label: 'Title', name: 'title', widget: 'string' }
          - { label: 'Date', name: 'date', widget: 'datetime' }
          - { label: 'Categories', name: 'categories', widget: 'list', required: false }
          - { label: 'Body', name: 'body', widget: 'markdown' }
    
  4. 启动 Jekyll 开发服务器:

    bundle exec jekyll serve
    
  5. 访问后台:

    http://localhost:4000/admin/
    

模板:参见 templates/jekyll/


3. 11ty (Eleventy) 设置

11ty 与 Sveltia CMS 配合良好,适用于灵活的静态站点。

步骤:

  1. 创建 admin 目录:

    mkdir -p admin
    
  2. 创建 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>
    
  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: Blog Posts
        folder: src/posts
        create: true
        slug: '{{slug}}'
        fields:
          - { label: 'Title', name: 'title', widget: 'string' }
          - { label: 'Description', name: 'description', widget: 'text' }
          - { label: 'Date', name: 'date', widget: 'datetime' }
          - { label: 'Tags', name: 'tags', widget: 'list', required: false }
          - { label: 'Body', name: 'body', widget: 'markdown' }
    
  4. 在 .eleventy.js 中添加 passthrough copy:

    module.exports = function(eleventyConfig) {
      eleventyConfig.addPassthroughCopy('admin');
      // ... rest of config
    };
    
  5. 启动 11ty 开发服务器:

    npx @11ty/eleventy --serve
    
  6. 访问后台:

    http://localhost:8080/admin/
    

模板:参见 templates/11ty/


4. Astro 设置

Astro 是一个现代框架,与 Sveltia CMS 配合良好。

步骤:

  1. 创建 admin 目录:

    mkdir -p public/admin
    
  2. 创建 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>
    
  3. 创建配置文件:

    # public/admin/config.yml
    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: public/images
    public_folder: /images
    
    collections:
      - name: blog
        label: Blog Posts
        folder: src/content/blog
        create: true
        slug: '{{slug}}'
        format: mdx
        fields:
          - { label: 'Title', name: 'title', widget: 'string' }
          - { label: 'Description', name: 'description', widget: 'text' }
          - { label: 'Published Date', name: 'pubDate', widget: 'datetime' }
          - { label: 'Hero Image', name: 'heroImage', widget: 'image', required: false }
          - { label: 'Body', 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. 在公共文件夹中创建 admin 目录:

    mkdir -p <public-folder>/admin
    
  3. 创建 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>
    
  4. 创建适合您内容结构的配置文件:

    backend:
      name: github
      repo: owner/repo
      branch: main
    
    media_folder: <your-media-path>
    public_folder: <your-public-path>
    
    collections:
      # Define based on your content structure
    
  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 部署

步骤:

  1. 创建 API 路由:

    // api/auth.ts
    export default async function handler(req, res) {
      // OAuth handling logic
      // See templates/vercel-serverless/api-auth.ts
    }
    
  2. 在 Vercel 中设置环境变量:

    GITHUB_CLIENT_ID=your_client_id
    GITHUB_CLIENT_SECRET=your_client_secret
    
  3. 更新 CMS 配置:

    backend:
      name: github
      repo: owner/repo
      branch: main
      base_url: https://yourdomain.com/api/auth
    

Individual skills in this repo

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

相关技能