tinacms

TinaCMS 是一个基于 Git 的无头 CMS，提供可视化编辑功能，面向内容密集型网站（博客、文档、营销站点）。内容以文件形式存储在 Git 仓库中，编辑界面通过可视化方式修改内容。

主要能力

Git 后端：内容以 Markdown/MDX 等文件形式保存在仓库中。
可视化编辑：通过 useTina Hook 在页面上直接编辑内容。
框架支持：Next.js、Vite+React 等（资料中明确提及）。
Schema 配置：通过 tina/config.ts 定义集合（collections）与字段（fields）。
字段类型：string、rich-text、number、datetime、boolean、image、reference、object。
部署方式：TinaCloud 托管服务（推荐）或自托管 Node.js 后端。

使用方式

推荐使用 pnpm（TinaCMS >2.7.3 要求）。初始化命令：

npx @tinacms/cli@latest init
pnpm install

package.json 脚本示例：

{
  "dev": "tinacms dev -c \"next dev\"",
  "build": "tinacms build && next build"
}

环境变量：

NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
TINA_TOKEN=your_read_only_token

启动开发服务器后，管理界面位于 http://localhost:3000/admin/index.html。

建议锁定精确版本（如 "tinacms": "3.3.1" 而非 "^3.3.1"），因为 TinaCMS UI 资源由 CDN 提供，可能先于本地 CLI 更新而导致不兼容。

Next.js 集成中，useTina Hook 用于启用可视化编辑：

import { useTina } from 'tinacms/dist/react'
import { client } from '../../tina/__generated__/client'

export default function BlogPost(props) {
  const { data } = useTina({
    query: props.query,
    variables: props.variables,
    data: props.data
  })

  return <article><h1>{data.post.title}</h1></article>
}

App Router 管理路由位于 app/admin/[[...index]]/page.tsx；Pages Router 位于 pages/admin/[[...index]].tsx。

Schema 配置示例（tina/config.ts）：

import { defineConfig } from 'tinacms'

export default defineConfig({
  branch: process.env.GITHUB_BRANCH || 'main',
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },
  schema: {
    collections: [/* ... */],
  },
})

集合示例（博客文章）：

{
  "name": "post",
  "label": "Blog Posts",
  "path": "content/posts",
  "format": "mdx",
  "fields": [
    { "type": "string", "name": "title", "label": "Title", "isTitle": true, "required": true },
    { "type": "rich-text", "name": "body", "label": "Body", "isBody": true }
  ]
}

常见错误与解决方案（资料中列出）

ESbuild 编译错误：避免在 tina/config.ts 中导入带自定义 loader 的代码、前端专用代码或整个组件库，只导入所需模块。
模块解析错误 "Could not resolve 'tinacms'"：清除缓存并重装依赖，使用 lockfile，确保安装 react 和 react-dom。
字段命名约束：字段名只能包含字母、数字、下划线，不允许连字符、空格或特殊字符。
Docker 绑定问题：TinaCMS 默认绑定 127.0.0.1，Docker 中需绑定 0.0.0.0，如 tinacms dev -c "next dev --hostname 0.0.0.0"。
缺少 _template 键错误：使用 templates 数组时需在 frontmatter 中提供 _template 字段，或改用 fields。
路径不匹配：collection 的 path 需与实际文件目录一致，避免尾部斜杠。
构建脚本顺序问题：必须先运行 tinacms build 再运行框架构建，以先生成 TypeScript 类型。
加载 TinaCMS 资源失败：生产环境必须使用 tinacms build 而非 tinacms dev；子路径部署存在已知资源加载问题。
Reference 字段 503 错误：引用集合条目过多时无分页支持，可拆分集合、改用带校验的 string 字段或自定义字段组件。
媒体管理器上传超时（幽灵上传）：UI 显示错误但实际可能已上传成功，建议等待后重新打开检查，避免重复上传。

部署选项

TinaCloud（托管，推荐）：在 https://app.tina.io 注册，获取 Client ID 和 Read Only Token，设置环境变量后部署到 Vercel/Netlify/Cloudflare Pages。资料称有免费层（每月 10k 请求）。

自托管 Node.js：需安装 @tinacms/datalayer 和 tinacms-authjs。注意自托管不支持 Edge Runtime（Cloudflare Workers、Vercel Edge Functions），因 @tinacms/datalayer 和 @tinacms/graphql 依赖 Node.js。官方自托管示例被团队认为"相当过时"，建议以最新文档为准。

适用场景

内容密集型网站：博客、文档站、营销站点。
需要可视化编辑体验的 Git 工作流项目。
使用 Next.js、Vite+React 等框架的项目。

限制

自托管不支持 Edge Runtime。
子路径部署存在资源加载问题。
Reference 字段无分页支持，条目过多会超时。
媒体管理器上传/删除存在 UI 超时但实际成功的已知问题。
字段名有字符限制。
自托管官方示例可能过时。

资料中未提供具体收费价格、性能基准或完整平台支持列表。