mcpField
T
tina-schema-sync

tina-schema-sync

github.com/genericservice开发040 次安装23 周前更新
代码仓库

关于 tina-schema-sync

在 TinaCMS Schema 变更后重新生成并提交相关产物的 Skill。它引导开发者使用 `tinacms dev` 本地生成、验证文件并准备部署，也涵盖 `tinacms build` 无法播种内容的情况。

主要功能

  1. 01使用 `tinacms dev` 重新生成产物
  2. 02验证生成类型和锁定文件
  3. 03检查凭据及本地端口
  4. 04将生成文件一并提交
  5. 05排查 Schema 同步失败

适用场景

  1. 01编辑 `tina/config.ts` 后同步产物
  2. 02生成时处理未知区块类型
  3. 03为 Vercel 部署准备 Schema 产物

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/genericservice/claude-skills --skill tina-schema-sync

安装后在 Claude Code 中输入/tina-schema-sync确认已加载。

详细介绍

TinaCMS 模式同步

在本地重新生成 TinaCMS 构建产物，并在模式变更后将其提交。此流程适用于混合部署策略：在 Vercel 上跳过 tinacms build，并预先提交构建产物。

适用场景

  • 编辑 tina/config.ts 后（添加字段、区块或集合）
  • 升级 @tinacms/cli 后
  • pnpm tina:build 因“Unable to seed”（内容引用了未知区块类型）而失败时
  • Vercel 部署成功，但新区块未显示时

前置条件

  • 在 .env.local 中配置 TinaCloud 凭据： 
    NEXT_PUBLIC_TINA_CLIENT_ID="..."
TINA_TOKEN="..."
  • 如果 .env.local 不存在，请运行 ./scripts/pull-secrets.sh，或从 .env.example 复制并根据 TinaCloud 控制面板填写相应值。

流程

步骤 1：载入凭据
source .env.local

确认凭据已设置：

echo $NEXT_PUBLIC_TINA_CLIENT_ID | head -c 10
echo $TINA_TOKEN | head -c 10
步骤 2：运行开发服务器以重新生成构建产物
NEXT_PUBLIC_TINA_CLIENT_ID="$NEXT_PUBLIC_TINA_CLIENT_ID" \
TINA_TOKEN="$TINA_TOKEN" \
npx tinacms dev --noWatch --noTelemetry

等待出现“已启动 TinaCMS 开发服务器”消息，然后停止服务器（按 Ctrl+C 或终止进程）。

为什么使用 tinacms dev 而不是 tinacms build？ 构建命令会连接 TinaCloud 进行索引。如果内容已引用 TinaCloud 模式中尚未定义的新区块类型，构建就会因“Unable to seed”而失败。开发服务器无需 TinaCloud 先重新索引，即可在本地生成构建产物。

步骤 3：确认构建产物已重新生成
git status tina/

你应该会看到以下文件发生变更：

  • tina/__generated__/client.ts
  • tina/__generated__/types.ts
  • tina/tina-lock.json

同时检查 public/admin/ 是否有变更。

步骤 4：确认新类型存在

如果你添加了新区块类型（例如 ContentTypes）：

grep "ContentTypes" tina/__generated__/types.ts
步骤 5：提交全部三组构建产物
git add tina/__generated__/ tina/tina-lock.json public/admin/
git commit -m "chore(tina): regenerate artifacts for [describe schema change]"

重要： TinaCloud 会读取 tina/tina-lock.json，以便在部署时了解模式。如果提交了生成的类型，却忘记提交锁文件，部署就会失败，或者新区块类型无法显示。

步骤 6：推送
git push

TinaCloud 会从推送的提交中读取锁文件，并正确索引模式。

Agent 工作流与氛围编程

  • 迭代同步： 如果字段依赖关系复杂，不要指望模式能一次同步成功。如果开发服务器报错或未生成构建产物，请找出具体的模式错误，只修复一个集合或字段定义，然后重新运行同步流程，直到成功为止。
  • 氛围编程： 在运行同步流程前，先为正在进行的 tina/config.ts 变更创建本地语义化提交；同步成功后，再单独提交生成的构建产物。这样如果生成失败，你就可以轻松回滚。

故障排查

“Unable to seed content/pages/home.mdx”

内容文件引用了云端模式中未定义的区块类型。这正是此技能要处理的情况。请使用 tinacms dev（步骤 2），不要使用 tinacms build。

开发服务器无法启动
  • 确认凭据已设置（步骤 1）
  • 检查端口 4001 是否被占用：lsof -i :4001
  • 检查端口 6970 是否被占用：lsof -i :6970
已生成类型，但锁文件未变更

模式变更可能尚未保存。运行开发服务器前，请确认 tina/config.ts 已写入。

检查清单

推送前，请确认：

  • tina/__generated__/client.ts 有变更
  • tina/__generated__/types.ts 包含新的类型定义
  • tina/tina-lock.json 有变更
  • public/admin/ 已更新（如适用）
  • 以上四项均已暂存并一并提交

评论

支持 Markdown