Communitygithub.com

ovachiever/droid-tings - TinaCMS

构建内容密集型网站,并使用基于 Git 的 TinaCMS。为博客、文档和营销网站提供可视化编辑和内容管理功能,面向非技术编辑人员。

droid-tings - TinaCMS 是什么?

此技能提供将 TinaCMS 集成到现代 Web 应用程序中的完整指南,TinaCMS 是一个开源、基于 Git 的无头内容管理系统 (CMS)。它允许开发者和内容创作者在内容密集的网站上无缝协作,核心功能包括基于 Git 的存储(内容以 Markdown、MDX 或 JSON 文件形式存储在仓库中)、可视化/上下文编辑以及通过代码模式驱动的类型安全 GraphQL API。该技能覆盖了 Next.js(App Router 和 Pages Router)、Vite + React、Astro 的详细设置步骤,以及适用于 Hugo、Jekyll 或 Eleventy 等框架的通用方法。它还提供了模式建模的最佳实践,例如博客文章、文档和作者集合的模板,并涵盖了使用 TinaCloud 或通过 Cloudflare Workers 等平台自行托管的部署选项。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/tinacms

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

TinaCMS 技能

将 TinaCMS 集成到现代 Web 应用程序的完整技能。


什么是 TinaCMS?

TinaCMS 是一个开源、基于 Git 的无头内容管理系统 (CMS),它使开发者和内容创作者能够在内容密集型网站上无缝协作。

主要特性

  1. 基于 Git 的存储

    • 内容以 Markdown、MDX 或 JSON 文件形式存储在 Git 仓库中
    • 完整的版本控制和变更历史
    • 无供应商锁定——内容存在于你的仓库中
  2. 可视化/上下文编辑

    • 并排编辑体验
    • 实时预览输入时的更改
    • 针对 Markdown 内容的所见即所得式编辑
  3. 模式驱动的内容建模

    • 在代码中定义内容结构 (tina/config.ts)
    • 根据模式自动生成类型安全的 GraphQL API
    • 用于组织内容的集合和字段系统
  4. 灵活的部署

    • TinaCloud:托管服务(最简单,提供免费套餐)
    • 自托管:Cloudflare Workers、Vercel Functions、Netlify Functions、AWS Lambda
    • 多种身份验证选项(Auth.js、自定义、本地开发)
  5. 框架支持

    • 最佳:Next.js(App Router + Pages Router)
    • 良好:React、Astro(实验性可视化编辑)、Gatsby、Hugo、Jekyll、Remix、11ty
    • 框架无关:可与任何框架配合使用(可视化编辑仅限于 React)

当前版本

  • tinacms:2.9.0(2025 年 9 月)
  • @tinacms/cli:1.11.0(2025 年 10 月)
  • React 支持:19.x (>=18.3.1 <20.0.0)

何时使用此技能

✅ 在以下情况下使用 TinaCMS:

  1. 构建内容密集型网站

    • 博客和个人网站
    • 文档网站
    • 营销网站
    • 作品集网站
  2. 非技术编辑人员需要访问权限

    • 不具备编码知识的内容团队
    • 管理页面的营销团队
    • 撰写博客文章的作者
  3. 期望基于 Git 的工作流程

    • 希望通过 Git 实现内容版本控制
    • 需要通过拉取请求进行内容审查
    • 偏好将内容与代码一同存放在仓库中
  4. 需要可视化编辑

    • 编辑人员希望实时查看更改
    • 偏好所见即所得体验
    • 并排编辑工作流程

❌ 在以下情况下不要使用 TinaCMS:

  1. 需要实时协作

    • 多个用户同时编辑(Google Docs 风格)
    • 请改用 Sanity、Contentful 或 Firebase
  2. 高度动态的数据

    • 电子商务产品目录,库存频繁变化
    • 实时仪表板
    • 请改用传统数据库(D1、PostgreSQL)
  3. 不需要内容管理

    • 应用程序是数据驱动的,而不是内容驱动的
    • 硬编码的内容已足够

按框架划分的设置模式

根据你的框架选择使用适当的设置模式。

1. Next.js 设置(推荐)

App Router (Next.js 13+)

步骤:

  1. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
    • 当提示输入公共资产目录时,输入 public
  2. 更新 package.json 脚本:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. 设置环境变量:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    
  4. 启动开发服务器:

    npm run dev
    
  5. 访问管理界面:

    http://localhost:3000/admin/index.html
    

创建的关键文件:

  • tina/config.ts - 模式配置
  • app/admin/[[...index]]/page.tsx - 管理 UI 路由(如果使用 App Router)

模板:参见 templates/nextjs/tina-config-app-router.ts


Pages Router (Next.js 12 及以下)

设置相同,只是管理路由为:

  • pages/admin/[[...index]].tsx 而不是 app 目录

数据获取模式:

// pages/posts/[slug].tsx
import { client } from '../../tina/__generated__/client'
import { useTina } from 'tinacms/dist/react'

export default function BlogPost(props) {
  // 为可视化编辑进行水合
  const { data } = useTina({
    query: props.query,
    variables: props.variables,
    data: props.data
  })

  return (
    <article>
      <h1>{data.post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: data.post.body }} />
    </article>
  )
}

export async function getStaticProps({ params }) {
  const response = await client.queries.post({
    relativePath: `${params.slug}.md`
  })

  return {
    props: {
      data: response.data,
      query: response.query,
      variables: response.variables
    }
  }
}

export async function getStaticPaths() {
  const response = await client.queries.postConnection()
  const paths = response.data.postConnection.edges.map((edge) => ({
    params: { slug: edge.node._sys.filename }
  }))

  return { paths, fallback: 'blocking' }
}

模板:参见 templates/nextjs/tina-config-pages-router.ts


2. Vite + React 设置

步骤:

  1. 安装依赖:

    npm install react@^19 react-dom@^19 tinacms
    
  2. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
    • 将公共资产目录设置为 public
  3. 更新 vite.config.ts:

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // TinaCMS 默认端口
      }
    })
    
  4. 更新 package.json 脚本:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. 创建管理界面:

    选项 A:手动路由 (React Router)

    // src/pages/Admin.tsx
    import TinaCMS from 'tinacms'
    
    export default function Admin() {
      return <div id="tina-admin" />
    }
    

    选项 B:直接 HTML

    <!-- public/admin/index.html -->
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>Tina CMS</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </head>
      <body>
        <div id="root"></div>
        <script type="module" src="/@fs/[path-to-tina-admin]"></script>
      </body>
    </html>
    
  6. 使用 useTina hook 进行可视化编辑:

    import { useTina } from 'tinacms/dist/react'
    import { client } from '../tina/__generated__/client'
    
    function BlogPost({ initialData }) {
      const { data } = useTina({
        query: initialData.query,
        variables: initialData.variables,
        data: initialData.data
      })
    
      return (
        <article>
          <h1>{data.post.title}</h1>
          <div>{/* 渲染正文 */}</div>
        </article>
      )
    }
    
  7. 设置环境变量:

    # .env
    VITE_TINA_CLIENT_ID=your_client_id
    VITE_TINA_TOKEN=your_read_only_token
    

模板:参见 templates/vite-react/


3. Astro 设置

步骤:

  1. 使用官方启动模板(推荐):

    npx create-tina-app@latest --template tina-astro-starter
    

    或手动初始化:

    npx @tinacms/cli@latest init
    
  2. 更新 package.json 脚本:

    {
      "scripts": {
        "dev": "tinacms dev -c \"astro dev\"",
        "build": "tinacms build && astro build",
        "preview": "astro preview"
      }
    }
    
  3. 配置 Astro:

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // 需要 React 用于 Tina 管理界面
    })
    
  4. 可视化编辑(实验性):

    • 需要 React 组件
    • 使用 client:tinaDirective 进行交互式编辑
    • 截至 2025 年 10 月,完整的可视化编辑仍处于实验阶段
  5. 设置环境变量:

    # .env
    PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

最佳适用场景:以内容为中心的静态站点、文档、博客

模板:参见 templates/astro/


4. 框架无关设置

适用于:Hugo、Jekyll、Eleventy、Gatsby、Remix 或任何框架

步骤:

  1. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
  2. 手动配置构建脚本:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<你的开发命令>\"",
        "build": "tinacms build && <你的构建命令>"
      }
    }
    
  3. 管理界面:

    • 自动创建于 http://localhost:<端口>/admin/index.html
    • 端口取决于你的框架
  4. 数据获取:

    • 无可视化编辑(仅侧边栏)
    • 通过基于 Git 的界面编辑内容
    • 更改直接保存到文件
  5. 设置环境变量:

    TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

限制:

  • 无可视化编辑(React 专属功能)
  • 需要手动集成
  • 仅基于侧边栏的编辑

模式建模最佳实践

在 tina/config.ts 中定义你的内容结构。

基本配置结构

import { defineConfig } from 'tinacms'

export default defineConfig({
  // 分支配置
  branch: process.env.GITHUB_BRANCH ||
          process.env.VERCEL_GIT_COMMIT_REF ||
          'main',

  // TinaCloud 凭证(如果使用托管服务)
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,

  // 构建配置
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },

  // 媒体配置
  media: {
    tina: {
      mediaRoot: '',
      publicFolder: 'public',
    },
  },

  // 内容模式
  schema: {
    collections: [
      // 在此处定义集合
    ],
  },
})

集合

集合 = 内容类型 + 目录映射

{
  name: 'post',           // 单数形式的内部名称(用于 API)
  label: 'Blog Posts',    // 复数形式的显示名称(在管理界面显示)
  path: 'content/posts',  // 存储文件的目录
  format: 'mdx',          // 文件格式:md, mdx, markdown, json, yaml, toml
  fields: [/* ... */]     // 字段定义数组
}

关键属性:

  • name:内部标识符(仅限字母数字和下划线)
  • label:管理界面中人类可读的名称
  • path:相对于项目根目录的文件路径
  • format:文件扩展名(默认为 'md')
  • fields:内容结构定义

字段类型参考

类型用例示例
string短文本(单行)标题、slug、作者姓名
rich-text长格式内容博客正文、页面内容
number数值价格、数量、评分
datetime日期/时间值发布日期、活动时间
boolean真/假切换草稿状态、特色标记
image图片上传主图、缩略图、头像
reference链接到另一个文档作者、分类、相关文章
object嵌套字段组SEO 元数据、社交链接

完整参考:参见 references/field-types-reference.md


集合模板

博客文章集合

{
  name: 'post',
  label: 'Blog Posts',
  path: 'content/posts',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,  // 在内容列表中显示
      required: true
    },
    {
      type: 'string',
      name: 'excerpt',
      label: 'Excerpt',
      ui: {
        component: 'textarea'  // 多行输入
      }
    },
    {
      type: 'image',
      name: 'coverImage',
      label: 'Cover Image'
    },
    {
      type: 'datetime',
      name: 'date',
      label: 'Published Date',
      required: true
    },
    {
      type: 'reference',
      name: 'author',
      label: 'Author',
      collections: ['author']  // 引用作者集合
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Draft',
      description: '如果选中,文章将不会发布',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true  // 主要内容区域
    }
  ],
  ui: {
    router: ({ document }) => `/blog/${document._sys.filename}`
  }
}

模板:参见 templates/collections/blog-post.ts


文档页面集合

{
  name: 'doc',
  label: 'Documentation',
  path: 'content/docs',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'description',
      label: 'Description',
      ui: {
        component: 'textarea'
      }
    },
    {
      type: 'number',
      name: 'order',
      label: 'Order',
      description: '侧边栏中的排序顺序'
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true,
      templates: [
        // 可以在此处定义 MDX 组件
      ]
    }
  ],
  ui: {
    router: ({ document }) => {
      const breadcrumbs = document._sys.breadcrumbs.join('/')
      return `/docs/${breadcrumbs}`
    }
  }
}

模板:参见 templates/collections/doc-page.ts


作者集合(引用目标)

{
  name: 'author',
  label: 'Authors',
  path: 'content/authors',
  format: 'json',  // 对结构化数据使用 JSON
  fields: [
    {
      type: 'string',
      name: 'name',
      label: 'Name',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'email',
      label: 'Email',
      ui: {
        validate: (value) => {
          if (!value?.includes('@')) {
            return 'Invalid email address'
          }
        }
      }
    },
    // 更多字段...
  ]
}

模板:参见 templates/collections/author.ts


部署与托管

选项 1:TinaCloud(托管)

最适合:希望最快上手,无需操心基础设施的用户。

  1. 连接仓库:在 tina.io 注册并连接你的 Git 仓库。
  2. 配置环境变量:设置 NEXT_PUBLIC_TINA_CLIENT_ID 和 TINA_TOKEN(来自仪表板)。
  3. 部署:正常部署你的站点(Vercel、Netlify、Cloudflare Pages 等)。

你的数据:

  • 内容保存在你的 Git 仓库中
  • TinaCloud 处理身份验证和中继

选项 2:自托管(Cloudflare Workers)

最适合:需要完全控制基础设施和零第三方依赖的用户。

前置要求:

  • Cloudflare 账户
  • wrangler CLI 已安装

步骤:

  1. 克隆自托管模板:

    git clone https://github.com/tinacms/self-hosted-starter.git
    cd self-hosted-starter
    npm install
    
  2. 创建 D1 数据库:

    npx wrangler d1 create tina-database
    
    • 更新 wrangler.toml 中的数据库绑定 ID。
  3. 配置身份验证:

    # 生成 JWT 密钥
    openssl rand -base64 32
    
    • 在 Cloudflare 仪表板或 .dev.vars 中设置 JWT_SECRET。
  4. 本地开发:

    npx wrangler d1 migrations apply tina-database --local
    npm run dev
    
  5. 部署:

    npm run deploy
    

你的数据:

  • 数据库:Cloudflare D1
  • 内容:Git(通过自托管后端)
  • 媒体:Cloudflare R2(对象存储)

完整指南:参见 references/self-hosted-guide.md


使用凭据

API 令牌

环境变量用途获取位置
TINA_TOKEN只读 API 令牌TinaCloud 仪表板
NEXT_PUBLIC_TINA_CLIENT_ID公共客户端 IDTinaCloud 仪表板
TINA_CLIENT_ID服务器端客户端 IDTinaCloud 仪表板
GITHUB_BRANCH用于内容编辑的分支CI 环境
VERCEL_GIT_COMMIT_REFVercel 自动设置Vercel 部署

身份验证

TinaCMS 支持多种身份验证策略:

  1. TinaCloud 身份验证:默认选项。重定向到 accounts.tina.io 进行登录。
  2. Auth.js(以前称为 NextAuth.js):用于自定义身份验证流程。
  3. 本地开发:无需身份验证(自动创建模拟用户)。
  4. 自定义身份验证:使用自托管后端实现你自己的提供商。

使用场景

1. 企业博客

用例: 公司通过编辑团队维护博客。

  • 作者:创建作者个人资料(姓名、照片、简介)。
  • 分类:按主题对文章进行分组。
  • SEO 元数据:为每篇文章添加自定义元数据。
  • 工作流程:作者创建草稿 -> 编辑人员审核 -> 发布。

2. 文档网站

用例: 开源项目需要为多个版本提供文档。

  • 结构化内容:使用 order 字段进行侧边栏导航。
  • 版本控制:不同分支对应不同版本。
  • 搜索:与 Algolia 或 Meilisearch 集成。

3. 营销网站

用例: 营销团队管理营销网站。

  • 页面构建器:使用 object 字段进行灵活布局。
  • A/B 测试:Git 分支用于内容变体。
  • 多语言:使用 path 和 reference 字段进行内容翻译。

常见问题排查

问题:ESBuild 编译错误

症状:构建期间出错,与 ESBuild 相关。

解决方案:

  1. 更新 @tinacms/cli 到最新版本。
  2. 确保你的 Node.js 版本 >= 18。
  3. 清理 .next 或 dist 文件夹,然后重新构建。

问题:模块解析失败

症状:Cannot find module 错误。

解决方案:

  1. 运行 npm install 以确保所有依赖已安装。
  2. 检查 node_modules/.cache/tina 是否存在,如果存在则删除。
  3. 重新运行 tinacms build。

问题:Docker 绑定问题(自托管)

症状:Docker 容器中的文件权限错误。

解决方案:

  1. 确保 Docker 与你的主机文件系统共享卷。
  2. 如果使用 Docker Compose,检查 volumes 配置。
  3. 使用 chmod 修复文件所有权。

参考文件

本技能文件夹中包含以下参考文件:

文件描述
references/field-types-reference.md所有字段类型的完整参考
references/self-hosted-guide.md自托管部署的详细指南
references/cli-reference.md@tinacms/cli 命令参考
references/collections-complete.md高级集合模板
templates/nextjs/Next.js 的启动模板
templates/vite-react/Vite + React 的启动模板
templates/astro/Astro 的启动模板
templates/collections/通用集合模板

Individual skills in this repo

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

相关技能