⚡

SveltiaCMS集成技能 sveltia-cms

这个技能用于将 Sveltia CMS 集成到静态网站项目中，提供完整的指南和工具，帮助快速搭建轻量级、基于 Git 的内容管理系统。Sveltia CMS 是现代 Decap/Netlify CMS 的继任者，支持多种框架如 Hugo、Jekyll、Astro，包含安装、配置、认证、错误解决和部署。关键词：Sveltia CMS，静态网站，内容管理，Git 集成，轻量级 CMS，前端开发工具，SEO 友好内容管理。

前端开发 0 次安装 0 次浏览 更新于 3/7/2026

name: sveltia-cms description: Sveltia CMS 是一个基于 Git 的内容管理系统（Decap/Netlify CMS 的继任者）。包大小缩小 5 倍（300 KB），提供 GraphQL 性能，解决 260+ 个问题。适用于静态网站（Hugo、Jekyll、11ty、Gatsby、Astro、Next.js）、博客、文档、i18n，或遇到 OAuth 错误、TOML/YAML 问题、CORS 问题、内容列表错误。 license: MIT allowed-tools: [‘读取’, ‘写入’, ‘编辑’, ‘Bash’, ‘Glob’, ‘Grep’] metadata: token_savings: “60-65%” errors_prevented: 8 package_version: “0.113.5” last_verified: “2025-10-29” frameworks: [“Hugo”, “Jekyll”, “11ty”, “Gatsby”, “Astro”, “Next.js”, “SvelteKit”, “框架无关”] deployment: [“Cloudflare Workers”, “Vercel”, “Netlify”, “GitHub Pages”, “Cloudflare Pages”]

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 进行内容版本控制
    • 通过拉取请求进行内容审查
    • 内容与代码一起存储在仓库中
    • 部署的 CI/CD 集成

  4. 需要轻量级解决方案

    • 性能敏感项目
    • 需要移动优先编辑
    • 快速加载时间关键
    • 最小包大小重要

  5. 从 Decap/Netlify CMS 迁移

    • 现有 config.yml 可重用
    • 直接替换（更改 1 行）
    • 更好的性能和用户体验
    • 活跃维护和错误修复

❌ 不使用 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 SSGs）
  • 传统 CMS 管理面板用户体验
  • 轻量级包要求
  • 框架无关项目

使用 TinaCMS 用于：

  • React、Next.js、Astro（React 组件）
  • 视觉上下文编辑
  • 模式驱动的类型安全内容
  • 现代开发者体验与 TypeScript

两者都有效 - Sveltia 补充 TinaCMS 用于不同用例。

快速开始

加载 references/framework-setup.md 以获取完整的框架特定设置（Hugo、Jekyll、11ty、Astro、Next.js、Gatsby、SvelteKit）。

基本设置步骤（框架无关）

  1. 在公共文件夹中创建 admin 目录（例如，static/admin、public/admin）
  2. 创建 admin/index.html 并添加 Sveltia CMS 脚本标签
  3. 创建 admin/config.yml 配置后端和集合
  4. 设置身份验证 → 参见 references/authentication-guide.md
  5. 本地测试 访问 /admin/

模板可用 在 templates/ 目录中为每个框架。

身份验证设置

加载 references/authentication-guide.md 以获取完整的 OAuth 设置说明。

快速概述

方法 最适合 复杂性
Cloudflare Workers 所有部署 容易 ⭐
Vercel Serverless Vercel 项目 中等
本地开发 仅开发 容易

推荐: Cloudflare Workers OAuth（官方、快速、免费）

模板: 参见 templates/cloudflare-workers/ 和 templates/vercel-serverless/

配置

加载 references/configuration-guide.md 以获取完整的 config.yml 文档、集合模式和 i18n 设置。

基本配置结构

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev

media_folder: static/images
public_folder: /images

collections:
  - name: posts
    label: 博客文章
    folder: content/posts
    create: true
    fields:
      - { label: 标题, name: title, widget: string }
      - { label: 正文, name: body, widget: markdown }

集合模板 可用在 templates/collections/ 中为博客、文档和落地页面。

i18n 支持: 多文件、文件夹或单文件结构 - 参见参考指南。

常见错误与解决方案

此技能预防 8 个常见错误。以下显示前 3 个 - 加载 references/error-catalog.md 以获取所有 8 个及完整解决方案。

1. ❌ OAuth 身份验证失败

错误: “错误：身份验证失败” / 重定向到错误域名

快速修复:

  • 验证 config.yml 中的 base_url 指向您的 OAuth 代理
  • 检查 GitHub OAuth 回调 URL 匹配 Worker URL
  • 测试 Worker: curl https://your-worker.workers.dev/health

→ 加载 references/error-catalog.md 错误 #1 以获取完整解决方案

2. ❌ CMS 中内容未列出

错误: “未找到条目” / 空内容列表

快速修复:

  • 验证 folder 路径匹配实际文件位置
  • 匹配 format 到实际文件格式（yaml vs toml）
  • 检查文件扩展名匹配配置

→ 加载 references/error-catalog.md 错误 #4 以获取完整解决方案

3. ❌ CORS / COOP 策略错误

错误: “身份验证中止” / OAuth 弹窗关闭

快速修复:

  • 设置 Cross-Origin-Opener-Policy: same-origin-allow-popups 在头部
  • 添加 OAuth 代理到 CSP connect-src

→ 加载 references/error-catalog.md 错误 #8 以获取完整解决方案

所有 8 个错误及详细解决方案: 参见 references/error-catalog.md

从 Decap CMS 迁移

Sveltia 是 直接替换 - 只需更改脚本标签！

<!-- 旧: Decap CMS -->
<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>

<!-- 新: Sveltia CMS -->
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>

您现有的 config.yml 可原样使用。加载 references/migration-from-decap.md 以获取完整迁移指南和测试清单。

部署

加载 references/deployment-guide.md 以获取平台特定部署说明（Cloudflare Pages、Vercel、Netlify、GitHub Pages）。

快速部署清单

  • [ ] 正确公共文件夹中的 admin 目录
  • [ ] OAuth 代理已部署和配置
  • [ ] base_url 在 config.yml 中设置
  • [ ] 构建命令配置
  • [ ] 部署后测试 /admin/ 路由

何时加载参考

加载 references/framework-setup.md 当：

  • 用户需要框架特定设置（Hugo、Jekyll、11ty、Astro 等）
  • 设置新 Sveltia CMS 安装
  • 故障排除框架特定 admin 目录问题

加载 references/authentication-guide.md 当：

  • 设置 GitHub OAuth 身份验证
  • 部署 Cloudflare Workers OAuth 代理
  • 故障排除身份验证错误
  • 用户询问 base_url 配置

加载 references/configuration-guide.md 当：

  • 用户需要完整 config.yml 示例
  • 设置集合、字段或小部件
  • 配置媒体上传、i18n 或工作流
  • 用户询问特定配置选项

加载 references/error-catalog.md 当：

  • 用户遇到设置中任何错误
  • 故障排除身份验证、解析或部署问题
  • 用户报告超出上面显示的前 3 个错误

加载 references/deployment-guide.md 当：

  • 部署到 Cloudflare Pages、Netlify 或 Vercel
  • 设置 OAuth 代理部署
  • 故障排除生产部署问题

加载 references/migration-from-decap.md 当：

  • 从 Decap CMS / Netlify CMS 迁移
  • 用户询问兼容性或迁移步骤

资源

模板: templates/hugo/, templates/jekyll/, templates/cloudflare-workers/ 官方文档: https://github.com/sveltia/sveltia-cms OAuth Worker: https://github.com/sveltia/sveltia-cms-auth

包信息

当前版本: @sveltia/cms@0.113.5（2025 年 10 月） 状态: 可用于生产，v1.0 预计 2026 年初

最后更新: 2025-10-24