nextjs-tinacms

Next.js 16 + React 19 + TinaCMS + Vercel

针对：Next.js App Router + TinaCMS + Tina Cloud + Vercel + Tailwind CSS 4 + shadcn/ui。

两种工作流：新建项目（从头搭建）或添加 CMS（集成到现有的 Next.js 15/16 项目中）。

技术栈

技术	版本	主要特性
Next.js	16.x	默认使用 Turbopack、"use cache"、proxy.ts、异步 params
TinaCMS	3.x	基于 Git 的 CMS、可视化点击编辑、GraphQL schema API、仅支持 ESM
React	19.x	Server Components、Actions、use()、useEffectEvent
Tailwind CSS	4.x	CSS 优先配置（@import "tailwindcss"），无需 JS 配置
shadcn/ui	CLI v4	复制粘贴组件、npx shadcn create、tw-animate-css
Vercel	--	部署目标。@vercel/analytics、@vercel/speed-insights、部署钩子
Tina Cloud	--	默认 CMS 后端。免费套餐（2 位用户），Team Plus+ 提供编辑工作流

快速开始

npx create-next-app@latest my-site --typescript --tailwind --app --src-dir
cd my-site
npx @tinacms/cli@latest init

验证：运行 tinacms dev，然后打开 http://localhost:3000/admin/index.html。

本地开发以仅本地模式运行——内容直接从文件系统读取和写入，无需连接 Tina Cloud。生产构建通过 Vercel 上的 NEXT_PUBLIC_TINA_CLIENT_ID 和 TINA_TOKEN 环境变量连接 Tina Cloud。

重要知识

1. 服务器与客户端必须分离。 useTina() 需要 "use client"。每个可编辑页面都需要一个服务器组件（数据获取器）和一个客户端组件（可视化编辑包装器）。
2. 构建顺序很重要。 始终使用 "build": "tinacms build && next build"。顺序错误会导致 Cannot find module '../tina/__generated__/client'。
3. 固定 TinaCMS 的精确版本。 不要使用 caret 版本范围。UI 资源与 CDN 不同步。通过包分组（RenovateBot 或 Dependabot）保持 tinacms 和 @tinacms/* 版本一致。
4. 应将 tina/__generated__/ 加入 gitignore。 只需提交 tina-lock.json。__generated__/ 文件夹会由 tinacms build 重新生成。
5. TinaCMS 3.x 仅支持 ESM。 配置文件必须使用 import 语法。在 package.json 中设置 "type": "module"，或使用 .ts 扩展名。
6. Next.js 16 中的异步 params。 每个 page.tsx、layout.tsx、route.ts 都必须对 params 使用 await——已完全移除同步访问方式。
7. proxy.ts 取代 middleware.ts。 文件位于项目根目录，导出 proxy 函数，且仅在 Node.js 运行时运行。Codemod：npx @next/codemod@canary middleware-to-proxy .
8. 安全性：必须使用 @tinacms/cli >= 2.1.8。 CVE-2026-28792（严重，CVSS 9.6）——旧版本存在通过 CORS 和路径遍历发起的无交互攻击。
9. 开发命令是 tinacms dev -c "next dev"。 绝不能单独运行 next dev——本地 GraphQL 服务将无法运行。

最低版本要求

搭建项目之前，查询当前稳定版本（npm view <pkg> version）。

软件包	最低版本	原因
next	>= 16.0.10	安全补丁
tinacms	>= 3.3.x	可视化选择器、仅支持 ESM、当前 schema API
@tinacms/cli	>= 2.1.8	修复 CVE-2026-28792
react / react-dom	>= 19.0.x	Server Components、Actions（useEffectEvent 需要 19.2.x）
tailwindcss	>= 4.x	CSS 优先配置（v3.4.x 也可接受）
Node.js	>= 20.9.0	Next.js 16 的要求

关键导入

导入项	来自	用途
defineConfig	tinacms	在 tina/config.ts 中配置 schema
useTina	tinacms/dist/react	在客户端组件中进行实时编辑
tinaField	tinacms/dist/react	点击编辑数据属性
TinaMarkdown	tinacms/dist/rich-text	富文本渲染
client	@/tina/__generated__/client	GraphQL 查询（自动生成）

集合

根据项目需求添加：

集合	类型	需要时机
pages	文件夹 + 区块	始终需要
global	单例	始终需要（站点设置、SEO 默认值）
navigation	单例	始终需要（可包含页脚链接）
posts	文件夹	站点有博客时
authors	文件夹	站点有博客时
footer	单例	页脚值得拥有独立集合时
notFound	单例	可选

常见任务

创建新区块

在 tina/config.ts 中，将模板对象添加到 blocks 字段的 templates 数组。每个区块都需要 ui.defaultItem。可选：添加 ui.previewSrc 以提供可视化选择器缩略图。

为页面添加可视化编辑

1. 服务端组件从 Tina 客户端获取 { data, query, variables }
2. 客户端组件使用这些属性调用 useTina()
3. 在 DOM 元素上添加 data-tina-field={tinaField(data.page, 'fieldName')}

启用缓存

在 next.config.ts 中设置 cacheComponents: true，然后使用 "use cache" 指令和 cacheLife() 预设：seconds、minutes、hours、days、weeks、max。

部署到 Vercel

1. 构建命令：tinacms build && next build
2. 设置 Vercel 环境变量：NEXT_PUBLIC_TINA_CLIENT_ID、TINA_TOKEN、NEXT_PUBLIC_TINA_BRANCH
3. 安装 @vercel/analytics + @vercel/speed-insights，并在根布局中渲染 <Analytics /> 和 <SpeedInsights />
4. 设置 Deploy Hook，以便在内容更改时重新构建
5. 使用 Vercel Team Environment Variables 在预览版和生产环境之间共享密钥

除非项目有特定的自托管理由，否则始终使用 Tina Cloud。 有关自托管这一备用选项，请参阅 references/deployment.md。

Claude Code 自动化

在 Day 0 早期于 .claude/settings.json 中设置：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "If the file path contains 'tina/__generated__/' or ends with 'tina-lock.json', BLOCK this edit. These files are auto-generated by tinacms build and must not be manually edited."
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }]
    }]
  },
  "permissions": {
    "allow": [
      "Bash(npx tinacms dev:*)",
      "Bash(npx tinacms build:*)",
      "Bash(pnpm dev:*)",
      "Bash(pnpm build:*)",
      "Bash(npx shadcn@latest add:*)"
    ]
  }
}

MCP 服务：

• claude mcp add context7 -- npx -y @upstash/context7-mcp@latest -- TinaCMS/Next.js/React/Tailwind 实时文档
• claude mcp add playwright -- npx -y @anthropic-ai/mcp-server-playwright@latest -- 在浏览器中测试可视化编辑

考虑为重复任务创建项目级技能：

• /new-block -- 搭建区块模板、组件和渲染器映射
• /tinacms-check -- 审查架构，检查缺失的 ui.itemProps、失效的 tinaField 和版本偏差

Agentic 工作流与氛围编程

• 迭代构建： 不要指望首次尝试就能完美集成 CMS。起草架构和可视化编辑封装，在本地测试连接（tinacms dev），隔离具体的数据获取或渲染错误，每次只调整一个字段或查询，然后刷新，直到点击编辑体验流畅无碍。
• 氛围编程： 在尝试添加复杂的区块模板或部署到 Vercel 之前，先在本地提交可正常运行的 Next.js 页面和 Tina 架构配置。确保这些提交包含 tina-lock.json。

参考文件

文件	阅读时机
references/schema-design.md	设计集合、区块、字段和内容钩子
references/visual-editing.md	服务端/客户端拆分、草稿模式、点击编辑调试
references/seo-meta.md	元数据、JSON-LD、OG 标签、站点地图、RSS
references/deployment.md	Tina Cloud 与自托管、媒体提供商、环境变量
references/setup-checklist.md	分阶段实施清单（MVP / 润色 / 全面）
templates/tina-config-starter.ts	包含 5 个区块模板的生产级 tina/config.ts
templates/page-server-client.tsx	包含元数据和静态参数的服务端/客户端页面模式