Astro + TinaCMS 设置指南

TinaCMS 可以与 Astro 并行运行，具有无需在页面树中使用 React 的一流可视化编辑功能。它作为 @tinacms/astro 提供，一个原生 Astro 富文本渲染器加上一行集成。

入门

有两种方式可以在 Astro 中设置 TinaCMS。

• 选项 1：从入门模板搭建（适合新项目）。
• 选项 2：将 TinaCMS 添加到现有的 Astro 站点，使用 tinacms init。

示例使用 pnpm。在 npm 或 yarn 上，替换命令：pnpm dev 变为 npm run dev 或 yarn dev；pnpm add x 变为 npm install x 或 yarn add x。

选项 1：从入门模板搭建

npx create-tina-app@latest --template tina-astro-starter

在提示时输入项目名称。然后进入该文件夹并启动开发服务器：

cd your-project-name      # 你刚创建的文件夹
pnpm dev

保持开发服务器运行。打开 http://localhost:4321/admin/index.html，选择一篇文章并编辑。可视化编辑已经连接，无需其他操作。（4321 是 Astro 的默认端口；使用终端打印的端口。）

选项 2：将 TinaCMS 添加到现有的 Astro 站点

从你站点的根目录：

cd your-astro-site       # 你的现有站点
npx @tinacms/cli@latest init

回答提示：

init 将 TinaCMS 添加到一个现有站点。在空文件夹中运行它会停止并指向选项 1。

init 安装 @tinacms/astro + 一个 SSR 适配器，包装你的 dev / build 脚本，并添加新文件：一个可编辑的演示位于 /tinacms-demo，你的 tina/ 配置和一个示例集合。它不会覆盖你的内容，并且会保留自定义的 astro.config（空或默认配置会得到 Tina 的连接）。

启动开发服务器：

pnpm dev

保持它运行。在浏览器中打开：

• http://localhost:4321/tinacms-demo 显示演示英雄。（终端中不同的端口？使用那个。）
• http://localhost:4321/admin/index.html#/~/tinacms-demo 打开编辑器。粘贴整个 URL（包括 #/~/）。点击标题或按钮：它应该高亮并在侧边栏打开一个表单进行实时编辑。

点击后是否打开了可编辑字段？

• ✅ 是（字段高亮并打开了一个表单）。init 已为你连接了配置。演示可以正常工作，也可以按原样构建和部署。接下来：使你的现有页面可编辑（目前只有 /tinacms-demo 是可编辑的）。
• ❌ 否（页面显示但点击无效，或稍后 pnpm build 失败并显示 [NoAdapterInstalled]）。你的 astro.config 已经有内容，所以 init 没有修改它。打开 astro.config.mjs：如果 integrations 中没有 tina()，这就是原因。 在下面的启用可视化编辑中连接它，然后重启。

建模你的内容

在 tina/config.ts 中定义你的集合。每个字段映射到编辑器 UI 和你的内容文件。init 提供了一个集合作为起点。完整参考：内容建模。

运行 TinaCMS

从你的项目根目录，启动开发服务器：

cd your-project          # 你的项目文件夹
pnpm dev

pnpm dev 同时运行 TinaCMS 和 Astro（它调用 tinacms dev -c "astro dev"）。管理员位于：

http://localhost:4321/admin/index.html

自定义端口： 运行 pnpm exec tinacms dev -c "astro dev --port 8080"，然后在管理员 URL 中使用该端口。 错误？ 请参阅常见错误。

你应该能看到 TinaCMS 管理员，能够选择一篇文章，保存，并观察更改持久化到你的本地内容文件。

启用可视化编辑

仅适用于现有 Astro 站点。 如果你是从入门模板搭建的（选项 1，tina-astro-starter），请跳过此步骤：可视化编辑已经连接。你只需要在**init 没有修改你的现有 astro.config**（上面的 ❌ 情况）或你手动连接现有站点时。

从你现有站点的根目录，安装包和一个 SSR 适配器：

cd your-astro-site       # 你的现有站点
pnpm add @tinacms/astro tinacms
pnpm add -D @tinacms/cli
pnpm add @astrojs/node          # 或 @astrojs/vercel / netlify / cloudflare

@astrojs/node 是本地编辑的安全默认选项。部署时根据你的主机（Vercel、Netlify、Cloudflare）进行匹配。

将 Tina 集成和一个 SSR 适配器添加到 astro.config.mjs。如果你已经有一个 integrations 数组或一个适配器，保留它们，只需追加 tina()。

不确定如何合并？ 复制 init 在你的终端中打印的版本，或者将你的文件与下面的代码片段进行比较，并保留你现有的集成和适配器。

import { defineConfig } from 'astro/config';
import tina from '@tinacms/astro/integration';
import { tinaAdminDevRedirect } from '@tinacms/astro/vite';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),       // 或你的现有适配器（Vercel、Netlify，...）
  integrations: [tina()],                      // 将 tina() 追加到你现有的数组中
  vite: {
    plugins: [tinaAdminDevRedirect()], // 让 /admin 在开发中工作
    // 可选：仅在 SSR 构建中需要，不适用于完全静态站点。
    ssr: { noExternal: ['@tinacms/astro', '@tinacms/bridge'] },
  },
});

然后停止并重启开发服务器（Astro 不会重新加载配置更改）：

# Ctrl-C，然后：
pnpm dev

为什么 output: 'server' 和一个适配器？ 编辑器从按需路由重新获取每个区域。output: 'server' 是最简单的；如果每个可编辑区域都包装在 <TinaIsland> 中，output: 'static' 也可以工作。请参阅静态站点编辑。

使你的现有 Astro 页面可编辑

在 init 之后，/tinacms-demo 是唯一为 Tina 编辑连接的页面。它是你网站其他部分的工作模板：将相同的模式复制到你现有的页面和组件中。（一个岛只是页面的一个可编辑部分。）每个可编辑页面连接这五个部分，所有这些都为演示搭建：

1. 你的架构中的一个字段（tina/config.ts）：你想编辑的内容。
2. 一个数据加载器：在 requestWithMetadata() 中包装查询。
3. 一个岛注册表条目用于该区域。
4. 每个岛的端点：src/pages/tina-island/[name].ts（处理每个区域；保留其 export const prerender = false）。
5. <TinaIsland> 和 tinaField()：包装区域并标记可点击的元素。（从 @tinacms/astro/TinaMarkdown.astro 导入 TinaMarkdown，子路径，否则 Astro 不会编译它。）

完整的代码演练：可视化编辑设置 → Astro。它有从演示到真实页面时要遵循的确切文件名和模式。

项目结构

init（和入门模板）围绕这些文件组织可视化编辑：

• tina/config.ts：你的集合（架构）；生成类型化客户端。
• src/lib/tina/data.ts：每个集合的获取器，每个通过 requestWithMetadata() 管道。
• src/lib/tina/islands.ts：可编辑区域的注册表。
• src/pages/tina-island/[name].ts：桥接重新获取的按需端点，通过 experimental_createIslandRoute(islands)。
• src/components/tina/*.astro：使用 <TinaMarkdown> 和 tinaField() 的 Astro 渲染器。
• astro.config.mjs：注册 tina()；中间件自动注入桥接。

请参阅可视化编辑设置 → Astro以获取完整架构。

下一步

• 可视化编辑设置 → Astro：集成、每个岛的重新获取和自定义 MDX 嵌入
• 从基于 React 的可视化编辑迁移：在旧 client:tina 路径上的现有站点
• 内容建模 · 数据获取 · 部署你的站点

有问题吗？加入 TinaCMS Discord。

另请参阅

• Next.js 设置指南：在 Next.js 中使用 TinaCMS
• Hugo 设置指南：在 Hugo 中使用 TinaCMS
• 自托管选项：在你自己的基础设施上托管 TinaCMS