Sveltia CMS 技能
将 Sveltia CMS 集成到静态站点项目的完整技能。
什么是 Sveltia CMS?
Sveltia CMS 是一个基于 Git 的轻量级无头内容管理系统,从头构建,是 Decap CMS(原 Netlify CMS)的现代继任者。它为存储在 Git 仓库中的内容提供了一个快速、直观的编辑界面。
主要特性
-
轻量且快速
- 包体积:<500 KB(minified/brotlied),而竞品为 1.5-2.6 MB
- 基于 Svelte 编译器构建(无虚拟 DOM 开销)
- 使用 GraphQL API 实现即时内容获取
- 基于相关性的全内容搜索
-
现代用户体验
- 直观的后台界面,充分利用视口
- 支持暗黑模式(跟随系统偏好)
- 针对移动端和平板优化
- 拖拽文件上传,支持多文件
- 实时预览,即时更新
-
Git 原生架构
- 内容存储为 Markdown、MDX、YAML、TOML 或 JSON
- 完整的版本控制和变更历史
- 无供应商锁定 - 内容与代码共存
- 支持 GitHub、GitLab、Gitea、Forgejo 后端
-
框架无关
- 以纯 JavaScript 包形式提供
- 适用于 Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit
- 无 React、Vue 或框架运行时依赖
- 兼容任何静态站点生成器
-
一流的国际化支持
- 内置多语言支持
- 一键集成 DeepL 翻译
- 编辑时切换区域设置
- 灵活的 i18n 结构(文件、文件夹、单一文件)
-
内置图片优化
- 自动转换为 WebP 格式
- 客户端调整大小和优化
- 支持 SVG 优化
- 可配置质量和尺寸
当前版本
- @sveltia/cms:0.113.5(2025 年 10 月)
- 状态:公开测试版(v1.0 预计 2026 年初)
- 成熟度:生产就绪(已解决 265+ 个前代问题)
何时使用此技能
✅ 使用 Sveltia CMS 的场景:
-
构建静态站点
- Hugo 博客和文档
- Jekyll 站点和 GitHub Pages
- 11ty(Eleventy)项目
- Gatsby 营销站点
- Astro 内容密集型站点
-
非技术编辑需要访问
- 营销团队管理页面
- 作者撰写博客文章
- 无 Git 知识的团队人员
- 客户需要轻松的内容更新
-
需要基于 Git 的工作流
- 通过 Git 进行内容版本控制
- 通过拉取请求进行内容审查
- 内容与代码共存于仓库
- 用于部署的 CI/CD 集成
-
需要轻量级解决方案
- 对性能敏感的项目
- 需要优先考虑移动端编辑
- 加载时间至关重要
- 最小包体积很重要
-
从 Decap/Netlify CMS 迁移
- 现有的
config.yml可重用 - 即插即用(更改一行代码)
- 更好的性能和用户体验
- 积极维护和错误修复
- 现有的
❌ 不使用 Sveltia CMS 的场景:
-
需要实时协作
- 多用户同时编辑(类似 Google Docs)
- 改用 Sanity、Contentful 或 TinaCMS
-
需要可视化页面构建
- 需要拖拽式页面构建器
- 改用 Webflow、Builder.io 或 TinaCMS (React)
-
高度动态数据
- 需要实时库存的电子商务
- 实时仪表盘或分析
- 改用传统数据库(D1、PostgreSQL)
-
需要 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 最流行的静态站点生成器。
步骤:
-
创建 admin 目录:
mkdir -p static/admin -
创建 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> -
创建配置文件:
# 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' } -
启动 Hugo 开发服务器:
hugo server -
访问后台:
http://localhost:1313/admin/
模板:参见 templates/hugo/
2. Jekyll 设置
Jekyll 通常与 GitHub Pages 和 Sveltia CMS 一起使用。
步骤:
-
创建 admin 目录:
mkdir -p admin -
创建 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> -
创建配置文件:
# 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' } -
启动 Jekyll 开发服务器:
bundle exec jekyll serve -
访问后台:
http://localhost:4000/admin/
模板:参见 templates/jekyll/
3. 11ty (Eleventy) 设置
11ty 与 Sveltia CMS 配合良好,适用于灵活的静态站点。
步骤:
-
创建 admin 目录:
mkdir -p admin -
创建 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> -
创建配置文件:
# 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' } -
在
.eleventy.js中添加 passthrough copy:module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy('admin'); // ... rest of config }; -
启动 11ty 开发服务器:
npx @11ty/eleventy --serve -
访问后台:
http://localhost:8080/admin/
模板:参见 templates/11ty/
4. Astro 设置
Astro 是一个现代框架,与 Sveltia CMS 配合良好。
步骤:
-
创建 admin 目录:
mkdir -p public/admin -
创建 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> -
创建配置文件:
# 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' } -
启动 Astro 开发服务器:
npm run dev -
访问后台:
http://localhost:4321/admin/
模板:参见 templates/astro/
5. 框架无关设置
适用于:Gatsby、Next.js (SSG 模式)、SvelteKit、Remix,或任何框架
步骤:
-
确定公共目录:
- Gatsby:
static/ - Next.js:
public/ - SvelteKit:
static/ - Remix:
public/
- Gatsby:
-
在公共文件夹中创建 admin 目录:
mkdir -p <public-folder>/admin -
创建 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> -
创建适合您内容结构的配置文件:
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 -
访问后台:
http://localhost:<port>/admin/
身份验证设置
选择适合您部署平台的身份验证方法。
选项 1:Cloudflare Workers OAuth(推荐)🔥
最适合:Cloudflare Pages、Cloudflare Workers、任何部署
这使用官方的 sveltia-cms-auth Cloudflare Worker 进行 OAuth。
步骤:
-
部署 Worker:
# 克隆身份验证 worker git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth # 安装依赖 npm install # 部署到 Cloudflare Workers npx wrangler deploy或使用一键部署:
- 访问 https://github.com/sveltia/sveltia-cms-auth
- 点击 "Deploy to Cloudflare Workers" 按钮
-
在 GitHub 上注册 OAuth 应用:
- 转到 https://github.com/settings/developers
- 点击 "New OAuth App"
- Application name:您的站点名称 CMS
- Homepage URL:https://yourdomain.com
- Authorization callback URL:https://your-worker.workers.dev/callback
- 保存 Client ID 和 Client Secret
-
配置 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 -
更新 CMS 配置:
# admin/config.yml backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # ← 添加此行 -
测试身份验证:
- 打开您的站点
/admin/ - 点击 "Login with GitHub"
- 授权该应用
- 您应该被重定向回 CMS
- 打开您的站点
完整指南:参见 references/cloudflare-auth-setup.md
模板:参见 templates/cloudflare-workers/
选项 2:Vercel Serverless Functions
最适合:Vercel 部署
步骤:
-
创建 API 路由:
// api/auth.ts export default async function handler(req, res) { // OAuth handling logic // See templates/vercel-serverless/api-auth.ts } -
在 Vercel 中设置环境变量:
GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret -
更新 CMS 配置:
backend: name: github repo: owner/repo branch: main base_url: https://yourdomain.com/api/auth