sveltia-cms

Sveltia CMS 技能

将 Sveltia CMS 集成到静态网站项目中的完整技能。

---

什么是 Sveltia CMS？

Sveltia CMS 是一款基于 Git 的轻量级无头内容管理系统，从头构建，作为 Decap CMS（原名 Netlify CMS）的现代继任者。它为存储在 Git 仓库中的内容提供快速、直观的编辑界面。

主要功能

1. 轻量且快速

   • 包体积：<500 KB（压缩后） vs 竞品的 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 月）
• 状态：公开测试版（预计 2026 年初发布 v1.0）
• 成熟度：可用于生产环境（已解决来自前身的 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 静态站点生成器）
• 传统 CMS 管理面板体验
• 对轻量级构建包的要求
• 与框架无关的项目

以下情况适合使用 TinaCMS：

• React、Next.js、Astro（React 组件）
• 可视化上下文内编辑
• 由架构定义驱动的类型安全内容
• 基于 TypeScript 的现代开发体验

两者都各有优势——Sveltia 可在不同使用场景中与 TinaCMS 互为补充。

---

快速入门

加载 references/framework-setup.md 查看完整的框架专属设置指南（Hugo、Jekyll、11ty、Astro、Next.js、Gatsby、SvelteKit）。

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

1. 在公共目录中创建管理目录（例如 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: Blog Posts
    folder: content/posts
    create: true
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

博客、文档和落地页的集合模板位于 templates/collections/。

i18n 支持：支持多文件、文件夹或单文件结构——请参阅参考指南。

---

常见错误与解决方案

此技能可避免 8 种常见错误。下方列出最常见的 3 种——加载 references/error-catalog.md 查看全部 8 种错误及完整解决方案。

1. ❌ OAuth 身份验证失败

错误：“Error: Failed to authenticate”／重定向到错误的域名

快速修复：

• 确认 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 中未列出内容

错误：“No entries found”／内容列表为空

快速修复：

• 确认 folder 路径与实际文件位置一致
• 确保 format 与实际文件格式匹配（yaml 或 toml）
• 检查文件扩展名是否与配置一致

→ 加载 references/error-catalog.md 中的错误 #4，查看完整解决方案

---

3. ❌ CORS／COOP 策略错误

错误：“Authentication Aborted”／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 是可直接替换的方案——只需更改脚本标签！

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


<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）。

快速部署检查清单

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

---

何时加载参考资料

在以下情况下加载 references/framework-setup.md：

• 用户需要针对特定框架的设置说明（Hugo、Jekyll、11ty、Astro 等）
• 设置新的 Sveltia CMS 安装
• 排查特定框架的管理目录问题

在以下情况下加载 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/[email protected]（2025 年 10 月） 状态：已可用于生产环境，预计于 2026 年初发布 v1.0

---

最后更新：2025-10-24