# Next.js 16 + React 19 + TinaCMS 技能两个主要工作流程： 1. **新项目**：Scaffold Next.js 16 + TinaCMS，带块页面构建器、可视化编辑、完整 SEO、Tailwind CSS 4、shadcn/ui 2. **添加 CMS** ：将 TinaCMS 集成到现有的 Next.js 15/16 项目中 ## 为什么这个堆栈 * **Next.js 16** - Turbopack 默认，“使用缓存”指令，“proxy.ts”替换中间件，需要异步参数，React 19.2 * **TinaCMS 3.x** — Git 支持的无头 CMS、可视化点击编辑、来自代码优先模式的 GraphQL API、位于 `/admin` 的管理 UI * **React 19.2** — 服务器组件稳定、操作、`use()` 钩子、视图转换、React 编译器（选择加入） * **Tailwind CSS 4** — CSS优先配置，`@import "tailwindcss"`，不需要`tailwind.config.js` * **shadcn/ui** — 复制粘贴组件，与 Tailwind 一起使用，而不是版本控制包 ## 关键知识 1. **服务器-客户端分离是强制性的。** `useTina()` 需要 `"use client"`。每个可编辑页面都需要一个服务器组件（数据获取器）和一个客户端组件（可视化编辑包装器）。 TinaCMS v2+ 中不需要全局 `TinaProvider`。 2. **构建顺序很重要。** 始终`"build": "tinacms build && next build"`。首先运行 `next build` → `找不到模块 '../tina/__ generated__/client'`。 3. **固定确切的 TinaCMS 版本。** 无插入符范围。 UI 资产部分由 CDN 提供，并由本地 CLI 提供。通过 RenovateBot 分组保持所有“tinacms”和“@tinacms/*”同步。 4. **`tina/__ generated__/` 必须提交。** 生产构建需要文件“_graphql.json”、“_lookup.json”、“_schema.json”和“tina-lock.json”。 5. **Next.js 16 中的异步参数** 每个 `page.tsx`、`layout.tsx`、`route.ts` 都必须 `await params` — 同步访问已完全删除。 6. **`proxy.ts` 替换了 Next.js 16 中的 `middleware.ts`。** 身份验证、重定向和请求操作移至在 Node.js 运行时运行的 `app/proxy.ts`。 7. **需要 Node.js ≥ 20.9.0。** Next.js 16 删除了 Node 18。 8. **字段名称：仅限字母数字+下划线。** 架构字段名称中的连字符/空格会导致构建错误。 9. **TinaCMS ≥ 2.7.3 需要 pnpm。** npm/yarn 可能存在模块解析问题。 10. **开发命令是 `tinacms dev -c "next dev"`。** 切勿单独使用 `next dev` — 本地 GraphQL 服务器将不会运行。 11. **自托管 TinaCMS 无法在 Edge Runtime 中运行**（Cloudflare Workers、Vercel Edge Functions）。标记为无法修复。 12. **`useTina()` 返回 props.data 在生产中保持不变** — 零开销。仅在编辑模式下订阅实时更新。 ## 版本楼层在搭建脚手架之前，请查找当前的稳定版本（`npm view version`）。最低楼层：套餐 |最低 |为什么 ---|---|--- `下一个` | ≥ 16.0.10 |安全补丁 `tinacms` | ≥ 3.3.x |视觉选择器，当前模式 API `@tinacms/cli` | ≥ 2.1.x |当前构建工具链 `react` / `react-dom` | ≥ 19.2.x |视图转换、useEffectEvent `tailwindcss` | ≥ 4.x | CSS-first 配置（v3.4.x 也可以接受） Node.js | ≥ 20.9.0 | Next.js 16 要求打字稿 | ≥ 5.1.0 | Next.js 需要 16 种类型 ## 工作流程：新项目逐个遵循 `references/day0-2-checklist.md` 中的 **247 任务清单**。以下各节总结了架构 - 清单包含详尽的实现细节。 ### 第 1 步：脚手架和安装 npx create-next-app@latest my-site --typescript --tailwind --app --src-dir --turbopack cd 我的网站 npx @tinacms/cli@latest init 验证：`tinacms dev`→确认`/admin`在`http://localhost:3000/admin/index.html`加载。 ### 步骤 2：配置包管理固定确切的 TinaCMS 版本。添加 `renovate.json` — 请参阅 `references/day0-2-checklist.md § Stack Versions` 以了解配置。 ### 步骤 3：`tina/config.ts` 中的架构设计请阅读“references/nextjs16-react19-tinacms-reference.md § 架构设计模式”以获取完整示例。使用“templates/tina-config-starter.ts”作为起点。 **所需收藏：** 收藏|类型 |目的 ---|---|--- `页面` |文件夹+块|具有可视化页面生成器的动态页面 `帖子` |文件夹|具有结构化字段的博客/文章 `作者` |文件夹|帖子引用 `全球` |单一文档 |站点范围设置、SEO 默认值、社交链接 `导航` |单一文档 |可编辑的导航结构 `页脚` |单一文档 |页脚内容和链接组 `未找到` |单一文档 |可定制的404页面内容 **单例模式：** ui: { 全局: true, allowedActions: { 创建: false, 删除: false } } **方块图案：** { 类型：'对象'，列表：true，名称：'块'，标签：'页面部分'， ui: { 视觉选择器: true }, 模板：[heroBlock、featuresBlock、contentBlock、ctaBlock、faqBlock]、 } 每个块模板都需要：`ui.previewSrc`、`ui.defaultItem`、部分样式组（布局/背景/高度/文本颜色作为映射到 Tailwind 类的枚举）。 **现场质量——在每个领域强制执行：** * 标题字段为“isTitle: true”，必填字段为“required: true” * `ui.validate` 用于字符限制、格式验证 * 用于编辑指导的“ui.description” * **每个**列表字段上的`ui.itemProps`带有有意义的标签 * `ui.component: 'textarea'` 用于多行字符串，`'group'` 用于可折叠组 **可重用字段组** — 提取为共享变量：`seoFields`、`ctaFields`、`linkFields`、`responsiveImageFields`、`sectionStyleFields`。 **内容挂钩：** 用户界面：{ beforeSubmit: async ({ 值 }) => ({ ...价值观， slug:values.title.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''), 修改日期: new Date().toISOString(), }), } ### 步骤 4：服务器-客户端页面模式有关完整模式，请参阅“templates/page-server-client.tsx”。 // app/[...slug]/page.tsx — 服务器组件从 '@/tina/__ generated__/client' 导入客户端从 './client-page' 导入 PageClient 导出默认异步函数 Page({ params }: { params: Promise<{ slug: string[] }> }) { const { slug } = 等待参数 constrelativePath = `${slug.join('/')}.md` const { 数据、查询、变量 } = 等待 client.queries.page({relativePath }) 返回 } 导出异步函数generateStaticParams() { const 页面 = 等待 client.queries.pageConnection() 返回pages.data.pageConnection.edges?.map((edge) => ({ slug: 边缘?.node?._sys.breadcrumbs, }））？？ [] } // app/[...slug]/client-page.tsx — 客户端组件 “使用客户端” 从 'tinacms/dist/react' 导入 { useTina, tinaField } 从 '@/components/blocks' 导入 { Blocks } 导出默认函数 PageClient(props: { 数据: any; 查询: string; 变量: any }) { const { 数据 } = useTina(props) 返回（

<块块={data.page.blocks} /> ） } ### 步骤 5：可视化编辑和草稿模式 **草稿模式 API 路由** (`app/api/preview/route.ts`)：从'next/headers'导入{draftMode} 从“下一步/导航”导入{重定向} 导出异步函数 GET(请求: 请求) { const { searchParams } = 新 URL(request.url) const slug = searchParams.get('slug') || '/' ;(等待draftMode()).enable() 重定向（slug） } **可视化编辑调试清单** - 如果单击编辑不起作用： 1.草稿模式启用了吗？ (`/api/预览`) 2. 组件是“使用客户端”？ 3. 使用正确的“{ data, query, variables }”属性调用“useTina()”？ 4. DOM 元素（不是包装组件）上的 `data-tina-field={tinaField(data.page, 'fieldName')}`？ 5. Tina 开发服务器正在运行吗？ (`tinacms 开发`) 6. 生成的类型和当前的类型？ (`蒂娜/__生成__/`) **每个内容集合上的`ui.router`用于上下文编辑预览： ui: { 路由器: ({ document }) => `/blog/${document._sys.filename}` } ### 第 6 步：完成 SEO 实施阅读 `references/day0-2-checklist.md` — 第 1 天任务 1.16–1.98，了解详尽的 80 多个 SEO 字段规范，涵盖全局设置单例、每页 SEO 对象、文章字段、JSON-LD 模式、OG 标签、Twitter 卡、发现文件。 **关键模式：** **SEO描述瀑布：** 1. `metaDescription` （显式）→ 2. `摘录` → 3. 自动截断内容 → 4. `siteDescription` （全局） **每个页面中的`generateMetadata()`：** 导出异步函数generateMetadata({ params }: Props): Promise { const { slug } = 等待参数 const { data } = wait client.queries.page({relativePath: `${slug}.md` }) const seo = data.page.seo const global = wait client.queries.global({relativePath: 'settings.json' }) 返回{ 标题：seo？.metaTitle ||数据.页面.标题, 描述：resolveDescription（seo，data.page，global.data.global），打开图：{ 图片：resolveOgImage（seo，global.data.global），类型：'网站'，站点名称：global.data.global.站点名称， }, 机器人：{索引：！seo？.noIndex，跟随：！seo？.noFollow }，替代品：{规范：seo？.canonical || `${global.data.global.siteUrl}/${slug}` }, } } **JSON-LD** — 在每个页面上：“Organization”、“WebSite”（主页）、“WebPage”、“Article”/“BlogPosting”（帖子）、“BreadcrumbList”、“FAQPage”（FAQ 块）。 **发现文件：** * `app/sitemap.ts` — 来自所有集合的动态，尊重 `noIndex`/`draft` * `app/robots.ts` — 不允许 `/admin`、`/api/preview` * `app/feed.xml/route.ts` — 博客的 RSS ### 第 7 步：缓存策略异步函数 getPage(slug: string) { '使用缓存' cacheLife({ 过时: 300, 重新验证: 60, 过期: 3600 }) const { data } = wait client.queries.page({relativePath: `${slug}.md` }) 返回数据 } 草稿模式绕过所有缓存（在 Next.js PR #77141 后确认）。 Next.js 15+ 将 `fetch()` 默认更改为 `no-store` — 显式选择缓存。 ### 步骤 8：媒体管理供应商|最适合 |设置 ---|---|--- 基于存储库 (`tina: { mediaRoot, publicFolder }`) |小型网站、博客 |配置中有2行 Cloudinary (`next-tinacms-cloudinary`) |媒体重 |包 + API 路由 + 3 个环境变量 S3/R2 (`next-tinacms-s3`) |企业 |包 + IAM + 存储桶配置所有提供程序都与“next/image”集成 - 在“next.config.js”中添加“images.remotePatterns”。 ### 步骤 9：构建和部署 { “脚本”：{ "dev": "tinacms dev -c \"下一个开发\"", "build": "tinacms 构建 && 下一个构建", "start": "下次开始" } } **Tina Cloud 的 Vercel 环境变量：** NEXT_PUBLIC_TINA_CLIENT_ID=<来自 app.tina.io> TINA_TOKEN=<只读令牌> NEXT_PUBLIC_TINA_BRANCH=主要 **自托管的 Vercel 环境变量：** TINA_PUBLIC_IS_LOCAL=假 GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx NEXTAUTH_SECRET=<随机秘密> KV_REST_API_URL=https://xxx.kv.vercel-storage.com KV_REST_API_TOKEN=xxx ## 工作流程：自托管 TinaCMS 三个可插入组件：**数据库适配器**（Vercel KV / MongoDB /自定义）、**git 提供程序** (GitHub)、**身份验证提供程序** (AuthJS/Clerk)。阅读“references/nextjs16-react19-tinacms-reference.md § 自托管 TinaCMS”以获取“database.ts”配置。 **选择自托管**的原因是：完全控制、成本敏感性、开源纯度。 **选择 Tina Cloud** 的原因是：快速设置、非技术团队、内置编辑工作流程（29-599 美元/月）。 ## 常见问题问题 |原因 |修复 ---|---|--- `找不到模块'../tina/__ generated__/client'` |错误的构建顺序 | `tinacms 构建 && 下一个构建` `架构未成功构建` | `tina/config.ts` 中的前端导入 |保持进口最少 `字段名称包含无效字符` |连字符/空格 |仅字母数字+下划线 `GetCollection 失败：未提供模板名称` | frontmatter 中缺少 `_template` |使用 `templates` 数组时添加可视化编辑不起作用 |多种原因 |运行调试清单（步骤 5） `预期的 workUnitAsyncStorage` | Turbopack 预渲染错误 | `--webpack` 后备列表项目显示“项目 0”|缺少 `ui.itemProps` |添加有意义的标签功能参考下拉缓慢/503 |大收藏|带分页的自定义字段 SCSS 模块损坏 | TinaCMS esbuild 问题 | CSS 模块或 Tailwind 软件包版本不匹配 |蒂娜包裹不同步|固定精确，RenovateBot 分组 Git 推送后内容过时 |数据库索引未更新|从仪表板重新索引 iOS 共享表损坏（iMessage、AirDrop）| `manifest.json` 和 `display: "standalone"` |使用 `"display": "browser"` 或省略清单； `` 处理着色 ## 反模式不要|而是做 ---|--- 页面正文的单一富文本 |带有模板的块列表在架构中公开 CSS 值 |映射到 Tailwind 类的枚举通用包装组件 |接受 Tina 类型的专用组件服务器组件中的`useTina`客户端组件包装器 Tina 软件包的 Dependabot |带分组的 RenovateBot 内联媒体 (base64) |外部媒体提供商无块回退|渲染器中的默认情况硬编码 SEO |具有瀑布模式的 SEO 对象列表中缺少“ui.itemProps” |有意义的标签功能同步“params”访问 |到处都有“await params” 在非 PWA 网站上显示“显示：“独立””| `"display": "browser"` 或省略；使用 `` 进行着色 ## 参考文件文件 |目的 ---|--- `references/day0-2-checklist.md` | **247 项任务清单** — 按照逐项任务完成设置 `references/nextjs16-react19-tinacms-reference.md` |深入的技术参考：架构模式、字段类型、块、SEO、React 19、缓存、自托管、自定义组件、部署 `templates/tina-config-starter.ts` |生产“tina/config.ts”，具有可重复使用的 SEO 字段、5 个块模板、7 个集合 `templates/page-server-client.tsx` |具有元数据、静态参数、块渲染器的完整服务器-客户端页面模式

Nextjs Tinacms

包含技能