TinaCMS 技能
将 TinaCMS 集成到现代 Web 应用程序的完整技能。
什么是 TinaCMS?
TinaCMS 是一个开源、基于 Git 的无头内容管理系统 (CMS),它使开发者和内容创作者能够在内容密集型网站上无缝协作。
主要特性
-
基于 Git 的存储
- 内容以 Markdown、MDX 或 JSON 文件形式存储在 Git 仓库中
- 完整的版本控制和变更历史
- 无供应商锁定——内容存在于你的仓库中
-
可视化/上下文编辑
- 并排编辑体验
- 实时预览输入时的更改
- 针对 Markdown 内容的所见即所得式编辑
-
模式驱动的内容建模
- 在代码中定义内容结构 (
tina/config.ts) - 根据模式自动生成类型安全的 GraphQL API
- 用于组织内容的集合和字段系统
- 在代码中定义内容结构 (
-
灵活的部署
- TinaCloud:托管服务(最简单,提供免费套餐)
- 自托管:Cloudflare Workers、Vercel Functions、Netlify Functions、AWS Lambda
- 多种身份验证选项(Auth.js、自定义、本地开发)
-
框架支持
- 最佳: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:
-
构建内容密集型网站
- 博客和个人网站
- 文档网站
- 营销网站
- 作品集网站
-
非技术编辑人员需要访问权限
- 不具备编码知识的内容团队
- 管理页面的营销团队
- 撰写博客文章的作者
-
期望基于 Git 的工作流程
- 希望通过 Git 实现内容版本控制
- 需要通过拉取请求进行内容审查
- 偏好将内容与代码一同存放在仓库中
-
需要可视化编辑
- 编辑人员希望实时查看更改
- 偏好所见即所得体验
- 并排编辑工作流程
❌ 在以下情况下不要使用 TinaCMS:
-
需要实时协作
- 多个用户同时编辑(Google Docs 风格)
- 请改用 Sanity、Contentful 或 Firebase
-
高度动态的数据
- 电子商务产品目录,库存频繁变化
- 实时仪表板
- 请改用传统数据库(D1、PostgreSQL)
-
不需要内容管理
- 应用程序是数据驱动的,而不是内容驱动的
- 硬编码的内容已足够
按框架划分的设置模式
根据你的框架选择使用适当的设置模式。
1. Next.js 设置(推荐)
App Router (Next.js 13+)
步骤:
-
初始化 TinaCMS:
npx @tinacms/cli@latest init- 当提示输入公共资产目录时,输入
public
- 当提示输入公共资产目录时,输入
-
更新 package.json 脚本:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
设置环境变量:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token -
启动开发服务器:
npm run dev -
访问管理界面:
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 设置
步骤:
-
安装依赖:
npm install react@^19 react-dom@^19 tinacms -
初始化 TinaCMS:
npx @tinacms/cli@latest init- 将公共资产目录设置为
public
- 将公共资产目录设置为
-
更新 vite.config.ts:
import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: 3000 // TinaCMS 默认端口 } }) -
更新 package.json 脚本:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
创建管理界面:
选项 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> -
使用 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> ) } -
设置环境变量:
# .env VITE_TINA_CLIENT_ID=your_client_id VITE_TINA_TOKEN=your_read_only_token
模板:参见 templates/vite-react/
3. Astro 设置
步骤:
-
使用官方启动模板(推荐):
npx create-tina-app@latest --template tina-astro-starter或手动初始化:
npx @tinacms/cli@latest init -
更新 package.json 脚本:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
配置 Astro:
// astro.config.mjs import { defineConfig } from 'astro/config' import react from '@astro/react' export default defineConfig({ integrations: [react()] // 需要 React 用于 Tina 管理界面 }) -
可视化编辑(实验性):
- 需要 React 组件
- 使用
client:tinaDirective进行交互式编辑 - 截至 2025 年 10 月,完整的可视化编辑仍处于实验阶段
-
设置环境变量:
# .env PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token
最佳适用场景:以内容为中心的静态站点、文档、博客
模板:参见 templates/astro/
4. 框架无关设置
适用于:Hugo、Jekyll、Eleventy、Gatsby、Remix 或任何框架
步骤:
-
初始化 TinaCMS:
npx @tinacms/cli@latest init -
手动配置构建脚本:
{ "scripts": { "dev": "tinacms dev -c \"<你的开发命令>\"", "build": "tinacms build && <你的构建命令>" } } -
管理界面:
- 自动创建于
http://localhost:<端口>/admin/index.html - 端口取决于你的框架
- 自动创建于
-
数据获取:
- 无可视化编辑(仅侧边栏)
- 通过基于 Git 的界面编辑内容
- 更改直接保存到文件
-
设置环境变量:
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(托管)
最适合:希望最快上手,无需操心基础设施的用户。
- 连接仓库:在 tina.io 注册并连接你的 Git 仓库。
- 配置环境变量:设置
NEXT_PUBLIC_TINA_CLIENT_ID和TINA_TOKEN(来自仪表板)。 - 部署:正常部署你的站点(Vercel、Netlify、Cloudflare Pages 等)。
你的数据:
- 内容保存在你的 Git 仓库中
- TinaCloud 处理身份验证和中继
选项 2:自托管(Cloudflare Workers)
最适合:需要完全控制基础设施和零第三方依赖的用户。
前置要求:
- Cloudflare 账户
wranglerCLI 已安装
步骤:
-
克隆自托管模板:
git clone https://github.com/tinacms/self-hosted-starter.git cd self-hosted-starter npm install -
创建 D1 数据库:
npx wrangler d1 create tina-database- 更新
wrangler.toml中的数据库绑定 ID。
- 更新
-
配置身份验证:
# 生成 JWT 密钥 openssl rand -base64 32- 在 Cloudflare 仪表板或
.dev.vars中设置JWT_SECRET。
- 在 Cloudflare 仪表板或
-
本地开发:
npx wrangler d1 migrations apply tina-database --local npm run dev -
部署:
npm run deploy
你的数据:
- 数据库:Cloudflare D1
- 内容:Git(通过自托管后端)
- 媒体:Cloudflare R2(对象存储)
完整指南:参见 references/self-hosted-guide.md
使用凭据
API 令牌
| 环境变量 | 用途 | 获取位置 |
|---|---|---|
TINA_TOKEN | 只读 API 令牌 | TinaCloud 仪表板 |
NEXT_PUBLIC_TINA_CLIENT_ID | 公共客户端 ID | TinaCloud 仪表板 |
TINA_CLIENT_ID | 服务器端客户端 ID | TinaCloud 仪表板 |
GITHUB_BRANCH | 用于内容编辑的分支 | CI 环境 |
VERCEL_GIT_COMMIT_REF | Vercel 自动设置 | Vercel 部署 |
身份验证
TinaCMS 支持多种身份验证策略:
- TinaCloud 身份验证:默认选项。重定向到 accounts.tina.io 进行登录。
- Auth.js(以前称为 NextAuth.js):用于自定义身份验证流程。
- 本地开发:无需身份验证(自动创建模拟用户)。
- 自定义身份验证:使用自托管后端实现你自己的提供商。
使用场景
1. 企业博客
用例: 公司通过编辑团队维护博客。
- 作者:创建作者个人资料(姓名、照片、简介)。
- 分类:按主题对文章进行分组。
- SEO 元数据:为每篇文章添加自定义元数据。
- 工作流程:作者创建草稿 -> 编辑人员审核 -> 发布。
2. 文档网站
用例: 开源项目需要为多个版本提供文档。
- 结构化内容:使用
order字段进行侧边栏导航。 - 版本控制:不同分支对应不同版本。
- 搜索:与 Algolia 或 Meilisearch 集成。
3. 营销网站
用例: 营销团队管理营销网站。
- 页面构建器:使用
object字段进行灵活布局。 - A/B 测试:Git 分支用于内容变体。
- 多语言:使用
path和reference字段进行内容翻译。
常见问题排查
问题:ESBuild 编译错误
症状:构建期间出错,与 ESBuild 相关。
解决方案:
- 更新
@tinacms/cli到最新版本。 - 确保你的 Node.js 版本 >= 18。
- 清理
.next或dist文件夹,然后重新构建。
问题:模块解析失败
症状:Cannot find module 错误。
解决方案:
- 运行
npm install以确保所有依赖已安装。 - 检查
node_modules/.cache/tina是否存在,如果存在则删除。 - 重新运行
tinacms build。
问题:Docker 绑定问题(自托管)
症状:Docker 容器中的文件权限错误。
解决方案:
- 确保 Docker 与你的主机文件系统共享卷。
- 如果使用 Docker Compose,检查
volumes配置。 - 使用
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/ | 通用集合模板 |