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 互为补充，可用于不同场景。

---

按框架选择设置模式

根据所选框架使用相应的设置模式。

1. Hugo 设置（最常见）

Hugo 是最常与 Sveltia CMS 搭配使用的静态站点生成器。

步骤：

1. 创建管理目录：

   mkdir -p static/admin
   

2. 创建管理首页：

   
   <!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. 创建管理目录：

   mkdir -p admin
   

2. 创建管理首页：

   
   <!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. 创建管理目录：

   mkdir -p admin
   

2. 创建管理首页：

   
   <!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 中添加直通复制设置：

   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. 创建管理目录：

   mkdir -p public/admin
   

2. 创建管理首页：

   
   <!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. 在公开文件夹中创建管理目录：

   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: <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：

   # Clone the auth worker
   git clone https://github.com/sveltia/sveltia-cms-auth
   cd sveltia-cms-auth
   
   # Install dependencies
   npm install
   
   # Deploy to Cloudflare Workers
   npx wrangler deploy
   

   或者使用一键部署：

   • 访问 https://github.com/sveltia/sveltia-cms-auth
   • 点击“Deploy to Cloudflare Workers”按钮

2. 在 GitHub 上注册 OAuth 应用：

   • 前往 https://github.com/settings/developers
   • 点击“New OAuth App”
   • 应用名称：你的网站名称 CMS
   • 主页 URL：https://yourdomain.com
   • 授权回调 URL：https://your-worker.workers.dev/callback
   • 保存客户端 ID 和客户端密钥

3. 配置 Worker 环境变量：

   # Set GitHub credentials
   npx wrangler secret put GITHUB_CLIENT_ID
   # Paste your Client ID
   
   npx wrangler secret put GITHUB_CLIENT_SECRET
   # Paste your Client Secret
   
   # Optional: Restrict to specific domains
   npx wrangler secret put ALLOWED_DOMAINS
   # Example: yourdomain.com,*.yourdomain.com
   

4. 更新 CMS 配置：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
     base_url: https://your-worker.workers.dev  # ← Add this line
   

5. 测试身份验证：

   • 打开网站的 /admin/
   • 点击“Login with GitHub”
   • 授权此应用
   • 页面应会重定向回 CMS

完整指南：参见 references/cloudflare-auth-setup.md

模板：参见 templates/cloudflare-workers/

---

选项 2：Vercel 无服务器函数

最适合：部署到 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
   

模板：参见 templates/vercel-serverless/

---

选项 3：Netlify Functions（不推荐）

注意：Sveltia CMS 出于性能原因，特意省略了 Git Gateway 支持。

如果部署到 Netlify，请使用以下任一方案：

• Cloudflare Workers OAuth（推荐，速度更快）
• Netlify Functions 和自定义 OAuth（与 Vercel 模式类似）

---

选项 4：本地开发（直接使用 GitHub/GitLab）

仅用于本地开发——无需身份验证代理。

要求：

• GitHub/GitLab 个人访问令牌
• 支持 File System Access API 的浏览器（Chrome、Edge）

设置：

1. 生成个人访问令牌：

   • GitHub：https://github.com/settings/tokens
   • 权限范围：repo（完全控制私有仓库）

2. 配置本地后端：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
     branch: main
   
   local_backend: true  # Enable local mode
   

3. 使用 Sveltia 的本地仓库功能：

   • 在登录界面点击“Work with Local Repository”
   • 选择本地 Git 仓库文件夹
   • 更改会直接保存到本地文件
   • 通过 Git 手动提交并推送

注意：此方式仅供开发使用——生产环境需要 OAuth 代理。

---

配置最佳实践

基本配置结构

# admin/config.yml

# Backend (Git provider)
backend:
  name: github  # or gitlab, gitea, forgejo
  repo: owner/repo
  branch: main
  base_url: https://your-auth-worker.workers.dev  # OAuth proxy

# Media storage
media_folder: static/images/uploads  # Where files are saved
public_folder: /images/uploads        # URL path in content

# Optional: Multiple media libraries
media_libraries:
  default:
    config:
      max_file_size: 5242880  # 5 MB in bytes
      slugify_filename: true
      transformations:
        raster_image:
          format: webp
          quality: 85
          width: 2048
          height: 2048
        svg:
          optimize: true

# Optional: Custom branding
logo_url: https://yourdomain.com/logo.svg

# Collections (content types)
collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      # Field definitions

---

集合模式

集合定义内容类型及其存储位置。

博客文章集合

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
    format: yaml  # or md, toml, json
    fields:
      - label: Title
        name: title
        widget: string

      - label: Date
        name: date
        widget: datetime
        date_format: 'YYYY-MM-DD'
        time_format: false  # Date only

      - label: Draft
        name: draft
        widget: boolean
        default: true

      - label: Featured Image
        name: image
        widget: image
        required: false

      - label: Excerpt
        name: excerpt
        widget: text
        required: false

      - label: Tags
        name: tags
        widget: list
        required: false

      - label: Body
        name: body
        widget: markdown

模板：参见 templates/collections/blog-posts.yml

---

文档页面集合

collections:
  - name: docs
    label: Documentation
    folder: content/docs
    create: true
    slug: '{{slug}}'
    format: mdx
    fields:
      - label: Title
        name: title
        widget: string

      - label: Description
        name: description
        widget: text

      - label: Order
        name: order
        widget: number
        value_type: int
        hint: Sort order in sidebar

      - label: Category
        name: category
        widget: select
        options:
          - Getting Started
          - API Reference
          - Tutorials
          - Advanced

      - label: Body
        name: body
        widget: markdown

模板：参见 templates/collections/docs-pages.yml

---

落地页集合（结构化内容）

collections:
  - name: pages
    label: Landing Pages
    folder: content/pages
    create: true
    slug: '{{slug}}'
    format: json
    fields:
      - label: Title
        name: title
        widget: string

      - label: SEO
        name: seo
        widget: object
        fields:
          - { label: Meta Title, name: metaTitle, widget: string }
          - { label: Meta Description, name: metaDescription, widget: text }
          - { label: OG Image, name: ogImage, widget: image }

      - label: Hero Section
        name: hero
        widget: object
        fields:
          - { label: Headline, name: headline, widget: string }
          - { label: Subheadline, name: subheadline, widget: text }
          - { label: Hero Image, name: image, widget: image }
          - label: CTA Button
            name: cta
            widget: object
            fields:
              - { label: Text, name: text, widget: string }
              - { label: URL, name: url, widget: string }

      - label: Features
        name: features
        widget: list
        fields:
          - { label: Title, name: title, widget: string }
          - { label: Description, name: description, widget: text }
          - { label: Icon, name: icon, widget: image }

模板：参见 templates/collections/landing-pages.yml

---

国际化（i18n）设置

Sveltia CMS 原生支持多种 i18n 结构选项。

多文件结构（推荐）

适用于：Hugo、使用独立语言区域文件的 Jekyll

i18n:
  structure: multiple_files
  locales: [en, fr, de, ja]
  default_locale: en

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    i18n: true  # Enable i18n for this collection
    fields:
      - label: Title
        name: title
        widget: string
        i18n: true  # Translatable field

      - label: Date
        name: date
        widget: datetime
        i18n: duplicate  # Same value across locales

      - label: Body
        name: body
        widget: markdown
        i18n: true

结果：创建如下文件：

• content/posts/hello-world.en.md
• content/posts/hello-world.fr.md
• content/posts/hello-world.de.md

---

多文件夹结构

适用于：Next.js、使用语言区域目录的 Astro

i18n:
  structure: multiple_folders
  locales: [en, fr, de]
  default_locale: en

collections:
  - name: blog
    label: Blog Posts
    folder: content/{{locale}}/blog  # {{locale}} placeholder
    create: true
    i18n: true
    fields:
      # Same as above

结果：创建如下文件：

• content/en/blog/hello-world.md
• content/fr/blog/hello-world.md
• content/de/blog/hello-world.md

---

单文件结构

适用于：在单个文件中管理翻译的 i18n 库

i18n:
  structure: single_file
  locales: [en, fr, de]
  default_locale: en

collections:
  - name: translations
    label: Translations
    files:
      - name: ui
        label: UI Strings
        file: data/translations.json
        i18n: true
        fields:
          - label: Navigation
            name: nav
            widget: object
            i18n: true
            fields:
              - { label: Home, name: home, widget: string, i18n: true }
              - { label: About, name: about, widget: string, i18n: true }

参考：完整指南请参见 references/i18n-patterns.md。

---

DeepL 翻译集成

Sveltia CMS 内置了一键翻译功能，使用 DeepL 提供翻译。

设置：

1. 获取 DeepL API 密钥：

   • 在 https://www.deepl.com/pro-api 注册
   • 免费套餐：每月 500,000 个字符

2. 添加到配置中：

   # admin/config.yml
   backend:
     name: github
     repo: owner/repo
   
   i18n:
     structure: multiple_files
     locales: [en, fr, de, es, ja]
     default_locale: en
   
   # DeepL integration
   deepl:
     api_key: your-deepl-api-key
     # Or use environment variable: DEEPL_API_KEY
   

3. 在编辑器中使用：

   • 切换到非默认语言区域
   • 点击“Translate from [Default Locale]”按钮
   • DeepL 会即时翻译所有可翻译字段

注意：翻译质量取决于 DeepL 的 AI，请务必检查译文。

---

常见错误与解决方案

此技能可避免设置 Sveltia CMS 时遇到的 8 种常见错误。

1. ❌ OAuth 身份验证失败

错误消息：

• “Error: Failed to authenticate”
• 重定向到 https://api.netlify.com/auth，而不是 GitHub 登录页面

症状：

• 登录按钮没有反应
• 重定向到错误的域名
• 身份验证弹出窗口立即关闭

原因：

• 后端配置中缺少 base_url
• OAuth 代理 URL 不正确
• CORS 策略阻止身份验证
• GitHub OAuth 回调 URL 错误

解决方案：

步骤 1：确认 config.yml 中有 base_url：

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev  # ← Must be present

步骤 2：检查 GitHub OAuth App 回调：

• 应为：https://your-worker.workers.dev/callback
• 不应为：https://yourdomain.com/callback

步骤 3：确认 Worker 环境变量：

npx wrangler secret list
# Should show: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET

步骤 4：直接测试 Worker：

curl https://your-worker.workers.dev/health
# Should return: {"status": "ok"}

预防措施：

• 不使用 GitHub 直接身份验证时，务必包含 base_url
• 在无痕窗口中测试 OAuth 流程
• 检查浏览器控制台中的 CORS 错误

2. ❌ TOML 前置信息错误

错误消息：

• “解析错误：无效的 TOML”
• 文件缺少 +++ 分隔符
• 正文内容出现在前置信息中

症状：

• CMS 创建的新文件无法被 Hugo 解析
• 编辑后现有 TOML 文件出错
• 内容出现在正文分隔符上方

原因：

• Sveltia 在 Beta 版中生成 TOML 的功能有问题
• TOML 分隔符处理不完整
• 同一集合中混用了 TOML 和 YAML

解决方案：

使用 YAML 而不是 TOML（推荐）：

collections:
  - name: posts
    folder: content/posts
    format: yaml  # or md (Markdown with YAML frontmatter)
    # NOT: format: toml

如果必须使用 TOML：

1. 在 CMS 保存后手动修复分隔符
2. 使用 pre-commit 钩子验证 TOML
3. 等待 Beta 版修复（关注 GitHub issues）

从 TOML 迁移到 YAML：

# Convert all posts from TOML to YAML
for file in content/posts/*.md; do
  # Use Hugo's built-in converter
  hugo convert toYAML "$file"
done

预防措施：

• 新项目优先使用 YAML 格式
• 如果 Hugo 要求使用 TOML，请在生产环境部署前彻底测试 CMS
• 关注 Sveltia 的 GitHub 发布动态，了解 TOML 修复情况

---

3. ❌ YAML 解析错误

错误消息：

• “YAML 解析错误：无效的 YAML”
• “错误：重复的键 'field_name'”
• “位置 X 处出现意外字符”

症状：

• CMS 无法加载现有文章
• 无法保存对内容的更改
• CMS 显示空字段

原因：

• Sveltia 对 YAML 格式的要求比 Hugo/Jekyll 更严格
• 一个文件中包含多个 YAML 文档（---\n---\n---）
• 缩进错误或包含特殊字符
• 从其他地方复制粘贴时带入了智能引号

解决方案：

步骤 1：验证 YAML：

# Install yamllint
pip install yamllint

# Check all content files
find content -name "*.md" -exec yamllint {} \;

步骤 2：常见修复方法：

问题：一个文件中包含多个文档

---
title: Post 1
---
---  # ← Remove this extra separator
title: Post 2
---

问题：缩进错误

# ❌ Bad - inconsistent indentation
fields:
  - name: title
     label: Title  # Extra space
  - name: date
    label: Date

# ✅ Good - consistent 2-space indentation
fields:
  - name: title
    label: Title
  - name: date
    label: Date

问题：智能引号

# ❌ Bad - smart quotes from copy-paste
title: "Hello World"  # Curly quotes

# ✅ Good - straight quotes
title: "Hello World"  # Straight quotes

步骤 3：使用 yamlfmt 自动修复：

# Install
go install github.com/google/yamlfmt/cmd/yamlfmt@latest

# Fix all files
find content -name "*.md" -exec yamlfmt {} \;

预防措施：

• 使用支持 YAML 的编辑器（VS Code 搭配 YAML 扩展）
• 启用 YAML 架构验证
• 在 pre-commit 钩子中运行 yamllint

---

4. ❌ 内容未在 CMS 中列出

错误消息：

• “未找到条目”
• 内容列表为空
• “加载条目失败”

症状：

• 管理页面已加载，但没有显示内容
• 集合显示为空
• 文件存在于仓库中，但 CMS 无法识别

原因：

• 格式不匹配（配置要求 TOML，但文件是 YAML）
• 文件夹路径错误
• 文件扩展名与格式不匹配
• Git 后端未连接

解决方案：

步骤 1：确认文件夹路径与实际文件位置一致：

# Config says:
collections:
  - name: posts
    folder: content/posts  # Expects files here

# Check actual location:
ls -la content/posts  # Files must exist here

步骤 2：使格式与实际文件相匹配：

# If files are: content/posts/hello.md with YAML frontmatter
collections:
  - name: posts
    folder: content/posts
    format: yaml  # or md (same as yaml for .md files)

# If files are: content/posts/hello.toml
collections:
  - name: posts
    folder: content/posts
    format: toml
    extension: toml

步骤 3：检查文件扩展名：

# Config expects .md files
ls content/posts/*.md  # Should show files

# If files have different extension:
# Either rename files OR set extension in config

步骤 4：确认 Git 后端连接：

backend:
  name: github
  repo: owner/repo  # Must be correct owner/repo
  branch: main      # Must be correct branch

预防措施：

• folder 路径使用相对于仓库根目录的路径
• 使 format 与实际文件格式相匹配
• 创建集合前先用一个文件进行测试

---

5. ❌ “SVELTIA is not defined”错误

错误消息：

• 控制台错误：Uncaught ReferenceError: SVELTIA is not defined
• 管理页面空白
• 管理页面一直处于加载状态

症状：

• 管理页面已加载，但显示白屏
• 浏览器控制台显示 JavaScript 错误
• CMS 始终无法初始化

原因：

• script 标签不正确
• CDN 故障或被拦截
• script URL 错误
• 缺少 type="module" 属性

解决方案：

步骤 1：使用正确的 script 标签：

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


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


<script src="https://unpkg.com/sveltia-cms/dist/sveltia-cms.js" type="module"></script>

步骤 2：确认 CDN 可以访问：

# Test CDN URL
curl -I https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js
# Should return: 200 OK

步骤 3：固定版本（可选，但推荐）：

<script src="https://unpkg.com/@sveltia/[email protected]/dist/sveltia-cms.js" type="module"></script>

步骤 4：检查是否被 CSP 拦截：

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' https://unpkg.com;
  style-src 'self' 'unsafe-inline' https://unpkg.com;
  connect-src 'self' https://api.github.com https://your-worker.workers.dev;
">

预防措施：

• 从 Sveltia 文档中复制官方 script 标签
• 在生产环境中固定到特定版本
• 在不同浏览器中测试管理页面

6. ❌ /admin 返回 404

错误消息：

• 访问 /admin/ 时显示“404 Not Found”
• 管理页面不存在

症状：

• 网站可以加载，但访问 /admin/ 时返回 404
• 在本地可用，但在生产环境中不可用
• 文件存在，但未提供

原因：

• 管理目录不在 public/static 文件夹中
• 管理文件未部署
• 构建配置不正确
• 框架未复制管理文件

解决方案：

步骤 1：确认管理目录的位置：

Hugo：static/admin/ Jekyll：admin/ 11ty：admin/（使用 passthrough copy） Astro：public/admin/ Next.js：public/admin/ Gatsby：static/admin/

步骤 2：检查文件是否存在：

ls -la static/admin/  # Hugo example
# Should show: index.html, config.yml

步骤 3：针对框架进行修复：

Hugo：static/ 中的文件会自动复制

Jekyll：添加到 _config.yml：

include:
  - admin

11ty：添加到 .eleventy.js：

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy('admin');
};

Astro：public/ 中的文件会自动复制

步骤 4：验证部署：

# After build, check output directory
ls -la public/admin/  # or _site/admin/ or dist/admin/

预防措施：

• 部署前测试管理页面是否可以访问
• 将管理目录加入版本控制
• 在项目 README 中记录管理路径

---

7. ❌ 图片无法上传（HEIC 格式）

错误消息：

• “Unsupported file format”
• “Failed to upload image”
• 图片显示了，但未保存

症状：

• 无法上传 iPhone 照片
• HEIC 文件被拒绝
• 只有 JPEG/PNG 可以使用

原因：

• 浏览器不支持 HEIC 格式
• 图片过大（超过 max_file_size）
• 媒体文件夹路径不正确

解决方案：

步骤 1：将 HEIC 转换为 JPEG：

在 Mac 上：

# Convert single file
sips -s format jpeg image.heic --out image.jpg

# Batch convert
for f in *.heic; do sips -s format jpeg "$f" --out "${f%.heic}.jpg"; done

在 iPhone 上：

• 设置 > 相机 > 格式 > 兼容性最佳
• 这样保存的照片会是 JPEG，而不是 HEIC

或使用在线转换器：https://heic.to/

步骤 2：启用图片优化以自动转换：

# admin/config.yml
media_libraries:
  default:
    config:
      max_file_size: 10485760  # 10 MB
      transformations:
        raster_image:
          format: webp  # Auto-converts to WebP
          quality: 85
          width: 2048
          height: 2048

步骤 3：如有需要，增大最大文件大小：

media_libraries:
  default:
    config:
      max_file_size: 10485760  # 10 MB in bytes
      # Default is often 5 MB

预防措施：

• 向内容编辑人员说明图片要求
• 在配置中启用自动优化
• 设置合理的 max_file_size（5-10 MB）

---

8. ❌ CORS / COOP 策略错误

错误消息：

• “Authentication Aborted”
• “Cross-Origin-Opener-Policy blocked”
• 身份验证弹出窗口立即关闭

症状：

• OAuth 弹出窗口打开后立即关闭
• 无法完成 GitHub 登录
• 控制台显示 COOP 错误

原因：

• Cross-Origin-Opener-Policy 标头过于严格
• CORS 标头阻止身份验证
• CSP 阻止脚本执行

解决方案：

步骤 1：调整 COOP 标头：

Cloudflare Pages（_headers 文件）：

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups
  # NOT: same-origin (this breaks OAuth)

Netlify（_headers 文件）：

/*
  Cross-Origin-Opener-Policy: same-origin-allow-popups

Vercel（vercel.json）：

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin-allow-popups"
        }
      ]
    }
  ]
}

步骤 2：将 OAuth 代理添加到 CSP：

<meta http-equiv="Content-Security-Policy" content="
  connect-src 'self' https://api.github.com https://your-worker.workers.dev;
">

步骤 3：对于 Cloudflare Pages，允许 API 访问：

# admin/config.yml (if using Cloudflare Pages webhooks)
# Add to CSP: https://api.cloudflare.com

预防措施：

• 默认将 COOP 标头设为 same-origin-allow-popups
• 在不同浏览器中测试身份验证
• 在项目 README 中记录所需的标头

---

从 Decap CMS 迁移

Sveltia CMS 是 Decap CMS（前身为 Netlify CMS）的直接替代品。

迁移步骤

步骤 1：更新 script 标签：

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

步骤 2：保留现有的 config.yml：

# Your existing Decap config.yml works as-is!
backend:
  name: github
  repo: owner/repo

collections:
  # ... no changes needed

步骤 3：在本地测试：

# Start your site's dev server
hugo server  # or jekyll serve, or npm run dev

# Visit /admin/ and test:
# - Login
# - Content listing
# - Editing
# - Saving
# - Media uploads

步骤 4：部署：

git add static/admin/index.html  # or your admin path
git commit -m "Migrate to Sveltia CMS"
git push

就这么简单！ 您的内容、集合和工作流均保持不变。

---

有何不同？

配置兼容性：100% 兼容

界面变化：

• 界面更快（无虚拟 DOM）
• 移动端体验更佳
• 支持深色模式
• 搜索功能改进

性能提升：

• 包体积缩小 5 倍（300 KB，相较于 1.5 MB）
• 内容即时加载（GraphQL）
• 不再受 API 速率限制影响

新功能：

• 集成 DeepL 翻译
• 内置图片优化
• 生成 UUID slug
• 更好地支持 i18n

不支持：

• Git Gateway 后端（出于性能方面的考虑）
• Azure 后端（可能会在以后添加）
• Bitbucket 后端（可能会在以后添加）

解决方法：改用 Cloudflare Workers 或 Vercel OAuth 代理。

---

测试清单

在全面迁移之前，请测试以下工作流：

• 使用 OAuth 登录
• 查看内容列表
• 创建新条目
• 编辑现有条目
• 上传图片
• 发布/取消发布
• 搜索内容
• 在不同集合之间切换
• 移动端编辑（如适用）
• i18n 切换（如适用）

---

完整指南：请参阅 references/migration-from-decap.md

---

部署模式

Cloudflare Pages

最适合：使用 Cloudflare 生态系统的静态网站

步骤：

1. 将 Git 仓库连接到 Cloudflare Pages：

   • 控制面板 > Pages > Create Project
   • 连接 GitHub/GitLab
   • 选择仓库

2. 配置构建设置：

   Build command: hugo  # or jekyll build, or npm run build
   Build output directory: public  # or _site, or dist
   Root directory: /
   

3. 部署 OAuth Worker（请参阅 Cloudflare Workers OAuth 部分）

4. 使用 Worker URL 更新 config.yml：

   backend:
     base_url: https://your-worker.workers.dev
   

5. 部署：

   • 推送到 main 分支
   • Cloudflare Pages 会自动构建
   • 访问管理页面：https://yourdomain.pages.dev/admin/

---

Vercel

最适合：Next.js、Astro，或任何支持通过 Vercel 部署的框架

步骤：

1. 连接 Git 仓库：

   • 控制面板 > Add New Project
   • 导入仓库

2. 配置构建：

   Framework Preset: <Auto-detected>
   Build Command: <Default>
   Output Directory: <Default>
   

3. 部署 OAuth 无服务器函数（请参阅 Vercel 设置部分）

4. 设置环境变量：

   GITHUB_CLIENT_ID=your_client_id
   GITHUB_CLIENT_SECRET=your_client_secret
   

5. 部署：

   • 推送到 main 分支
   • Vercel 会自动构建

---

Netlify

最适合：JAMstack 网站、从旧版 Netlify CMS 迁移

步骤：

1. 连接 Git 仓库：

   • 控制面板 > Add New Site
   • 导入仓库

2. 配置构建：

   Build command: <your-build-command>
   Publish directory: public  # or _site, or dist
   

3. 使用 Cloudflare Workers 实现 OAuth（推荐优于 Netlify Functions）

4. 部署：

   • 推送到 main 分支
   • Netlify 会自动构建

---

GitHub Pages

最适合：Jekyll 网站、简单的静态网站

步骤：

1. 配置 Jekyll（如使用）：

   # _config.yml
   include:
     - admin
   

2. 创建 GitHub Actions 工作流：

   # .github/workflows/deploy.yml
   name: Deploy
   on:
     push:
       branches: [main]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Build
           run: jekyll build  # or your build command
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./_site
   

3. 部署 OAuth Worker 以进行身份验证

4. 访问管理页面：

   https://username.github.io/repo/admin/
   

---

其他资源

模板

所有模板均位于 templates/：

• hugo/ - 完整的 Hugo 博客设置
• jekyll/ - Jekyll 网站配置
• 11ty/ - Eleventy 博客设置
• astro/ - Astro 内容集合
• cloudflare-workers/ - OAuth 代理实现
• vercel-serverless/ - Vercel 身份验证函数
• collections/ - 预构建的集合模式
  • blog-posts.yml
  • docs-pages.yml
  • landing-pages.yml
• admin/ - 管理页面基础模板

参考资料

references/ 中的完整指南：

• common-errors.md - 扩展错误排查指南
• migration-from-decap.md - 完整迁移指南
• cloudflare-auth-setup.md - OAuth 分步设置指南
• config-reference.md - 完整的 config.yml 文档
• i18n-patterns.md - 国际化策略
• framework-guides.md - 各框架的具体说明

脚本

SCRIPTS 中的自动化工具：

• init-sveltia.sh - 新项目自动化设置
• deploy-cf-auth.sh - 部署 Cloudflare Workers OAuth
• check-versions.sh - 验证兼容性

官方文档

• 网站：https://sveltia.com（即将推出）
• GitHub：https://github.com/sveltia/sveltia-cms
• OAuth Worker：https://github.com/sveltia/sveltia-cms-auth
• npm 包：https://www.npmjs.com/package/@sveltia/cms
• 讨论区：https://github.com/sveltia/sveltia-cms/discussions

---

令牌效率

预计节省：60-65%（约节省 9,000 个令牌）

不使用 Skill（约 14,000 个令牌）：

• 初步研究与探索：2,500 个令牌
• 框架设置中的反复尝试：2,000 个令牌
• OAuth 配置尝试：2,500 个令牌
• 错误排查：3,500 个令牌
• i18n 设置：1,500 个令牌
• 部署配置：2,000 个令牌

使用 Skill（约 5,000 个令牌）：

• 发现 Skill：100 个令牌
• 加载 Skill（SKILL.md）：3,500 个令牌
• 选择模板：400 个令牌
• 少量项目特定调整：1,000 个令牌

---

已避免的错误

此技能可避免 8 种常见错误（避免率为 100%）：

1. ✅ OAuth 身份验证失败
2. ✅ TOML front matter 生成错误
3. ✅ YAML 解析错误（严格验证）
4. ✅ 内容未列入 CMS
5. ✅ “SVELTIA is not defined”错误
6. ✅ /admin 页面出现 404
7. ✅ 图片上传失败（HEIC 格式）
8. ✅ CORS / COOP 策略错误

---

快速入门示例

示例 1：使用 Cloudflare OAuth 的 Hugo 博客

# 1. Create Hugo site
hugo new site my-blog
cd my-blog

# 2. Create admin directory
mkdir -p static/admin

# 3. Copy templates
cp [path-to-skill]/templates/hugo/index.html static/admin/
cp [path-to-skill]/templates/hugo/config.yml static/admin/

# 4. Deploy OAuth Worker
git clone https://github.com/sveltia/sveltia-cms-auth
cd sveltia-cms-auth
npx wrangler deploy

# 5. Configure and test
hugo server
open http://localhost:1313/admin/

---

示例 2：GitHub Pages 上的 Jekyll

# 1. Create Jekyll site
jekyll new my-site
cd my-site

# 2. Create admin
mkdir admin
cp [path-to-skill]/templates/jekyll/index.html admin/
cp [path-to-skill]/templates/jekyll/config.yml admin/

# 3. Add to _config.yml
echo "include:\n  - admin" >> _config.yml

# 4. Deploy
git add .
git commit -m "Add Sveltia CMS"
git push

---

示例 3：从 Decap CMS 迁移

# 1. Update script tag in admin/index.html
sed -i 's|decap-cms|@sveltia/cms|g' static/admin/index.html
sed -i 's|decap-cms.js|sveltia-cms.js" type="module|g' static/admin/index.html

# 2. Test locally
hugo server
open http://localhost:1313/admin/

# 3. Deploy
git add static/admin/index.html
git commit -m "Migrate to Sveltia CMS"
git push

---

生产环境示例

• Hugo 文档：0deepresearch.com（Hugo + GitHub Pages + Sveltia）
• Jekyll 博客：keefeere.me（Jekyll + Sveltia + DeepL i18n）
• 11ty 作品集：各种社区项目

---

支持

遇到问题？ 请先查看 references/common-errors.md

仍然无法解决？

• GitHub Issues：https://github.com/sveltia/sveltia-cms/issues
• 讨论区：https://github.com/sveltia/sveltia-cms/discussions
• Stack Overflow：使用标签 sveltia-cms

---

最后更新：2025-10-24 技能版本：1.0.0 Sveltia CMS 版本：0.113.3（Beta） 状态：已可用于生产环境，预计于 2026 年初发布 v1.0 GA