Loving Tina? us on GitHub0.0k
v.Latest
Documentation

分离内容仓库

在此页面上

介绍

Tina支持从一个独立的Git仓库获取内容。通过这种方式，你可以继续在你的“网站仓库”中定义Tina配置，但文档将被外部保存到一个“内容仓库”中。

为什么？

你可能出于多种原因想要这样做，例如：

  • 将你的网站代码与内容文件解耦，这样你的提交历史就不会混合内容更新和代码更新。
  • 避免必须给予TinaCloud对你网站代码的写入权限（只需给予对内容仓库的访问权限）。

在本指南中，我们将提到“网站仓库”和“内容仓库”。“网站仓库”是你实际运行网站的地方，而“内容仓库”是你存储Markdown内容的地方。

要求

  • 你必须在本地机器上同时检出“内容仓库”和“网站仓库”。
  • 你必须在Tina配置中提供内容仓库的位置（下面会详细介绍）。

创建网站仓库

我们将首先创建“网站仓库”。为此，我们创建了一个基本模板，你可以克隆下来并跟随操作。该模板包含一个NextJS站点，以及已经配置好本地配置路径的tina配置。

git clone https://github.com/tinacms/separate-website-repo.git

如果你不想从模板开始，请按照快速入门指南创建TinaCMS项目。在此步骤结束时，你应该具备以下重要内容：

  1. 一个已设置TinaCMS的项目。
  2. 该项目已推送到GitHub。
此阶段的项目不必在TinaCloud中设置和部署。这将在本指南的后续步骤中完成。

创建内容仓库

接下来我们将设置“内容仓库”。让我们从创建一个简单的.mdx文件开始。

以下命令创建一个文件夹（demo-content-repo），在该文件夹中初始化Git，并在content/pages目录中添加一个初始的MDX文件。我们将在Tina配置中为page集合使用该目录。

tree .
# .
# └── separate-website-repo
#
# 2 directories, 0 files


mkdir -p demo-content-repo/content/pages
cd demo-content-repo
git init
mkdir tina
touch ./content/pages/home.mdx 
echo "Hello" >> ./content/pages/home.mdx
cd ..


tree .
# .
# ├── demo-content-repo
# │   └── tina
# │   └── content
# │       └── pages
# │           └── home.mdx
# └── separate-website-repo
# 
# 5 directories, 1 file

在继续之前，确保“内容仓库”已推送到GitHub。

本地开发

在“网站仓库”中，安装项目的依赖并启动开发服务器以生成tina-lock.json和其他所需文件。

首先，进入网站仓库

cd separate-website-repo

然后安装项目依赖

yarn install
yarn dev

编辑内容

在开发服务器运行的情况下，打开你选择的浏览器并访问http://localhost:3000/admin/index.html。

在这里，你可以在tina/config.js中为你的内容模型添加更多字段。要了解更多信息，请访问内容建模文档。

在TinaCloud中部署内容仓库

在本地和GitHub中创建内容仓库后，是时候在TinaCloud中创建它了。此过程在以下指南中详细介绍。

完成后，请注意以下两个令牌。你将在下一步中需要它们。

  1. 在项目“概览”标签中找到的客户端ID。
  2. 在项目“令牌”标签中找到的内容令牌。
你可以将内容令牌限制在某些分支上。要了解更多信息，请访问如何创建内容令牌的文档。

在TinaCloud中部署网站仓库

在本地和GitHub中创建网站仓库后，是时候在TinaCloud中创建它了。此过程与“内容仓库”相同。

  1. 在“网站仓库”中创建一个.env文件
  2. 使用上一步中从内容仓库的TinaCloud实例中检索到的令牌填写它
cp .env.example .env

当你运行tinacms build时，它将使用这些凭据连接到TinaCloud，而不是本地服务器。如果你在使用模板，我们已将此过程集成到yarn build命令中。

最后要做的是记下在项目“概览”标签中找到的客户端ID令牌。你将在下一步中需要它。

连接内容仓库

现在“网站仓库”已在TinaCloud中创建：

  1. 获取上一步中从网站仓库的TinaCloud实例中检索到的客户端ID
  2. 在“内容仓库”中创建一个新的tina/meta.json文件。这是连接两者的关键。
cd demo-content-repo
touch tina/meta.json

然后将以下内容添加到其中：

{
  "upstreamBranch": "main",
  "upstreamClientId": "{{ website repo client ID }}"
}

以前的TinaCMS版本要求你在两个仓库中维护一个最新的/tina文件夹。现在已简化为一个tina/meta.json文件。如果你正在从旧版本迁移，请确保将TinaCloud中的仓库从“内容仓库”更新为“网站仓库”。

路径配置注意事项

在你的tina/config.(ts/js)中定义集合路径时，避免设置path: ''。因为Tina期望一个相对于文件夹的路径。使用空字符串''可能会导致在创建新文档时出现错误，因为Tina在保存时会添加一个/，这可能导致无效的GitHub路径和创建错误。

静态网站生成器兼容性

如果你使用的是NextJS以外的静态网站生成器（SSG），例如Astro。确保你的内容管道忽略“内容仓库”中的tina/目录。Tina的配置文件不是内容文件，这可能导致解析错误。

以下是如何排除tina/目录的示例：

export default defineCollection({
  schema: mySchema,
  exclude: ['tina/**/*'],
});

从内容仓库触发网站构建（可选）

使用独立的内容仓库时，你可能希望内容更新（例如来自TinaCMS UI）自动触发你的网站构建。TinaCloud支持通过webhooks开箱即用地实现这一点。

使用TinaCloud Webhooks（推荐）

TinaCloud可以配置为在内容更改提交时向webhook端点发送POST请求。这是触发网站重建的推荐方式。

👉 查看webhook功能以获取更多详细信息

使用GitHub Actions触发构建

作为使用webhooks的替代方案，你可以使用GitHub Actions触发网站构建。
如果你的平台不支持构建webhooks，或者你希望对构建过程有更多控制，这将非常有用。

示例工作流

在你的内容仓库中创建一个工作流文件（例如.github/workflows/trigger-website-build.yml）：

name: Trigger Website Build


on:
  workflow_dispatch:
  push:
    branches:
      - '**'


jobs:
  trigger-deploy:
    runs-on: ubuntu-latest
    if: github.repository_owner == 'your-org'


    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.MY_APP_ID }}
          private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
          owner: your-org
          repositories: your-website-repo


      - name: Trigger website deploy
        run: |
          gh workflow run build-and-deploy.yml \
            --repo your-org/your-website-repo \
            --ref main \
            --field run_id="$GITHUB_RUN_ID" \
            --field branch_name="${GITHUB_REF#refs/heads/}"
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
先决条件

此设置需要：

  • 一个具有访问两个仓库权限的GitHub应用
  • 在GitHub仓库设置中保存的令牌和应用密钥
上次编辑: March 20, 2026