TinaCMS 与 Astro 并行运行，具有无需在页面树中使用 React 的一流可视化编辑功能。该集成以 @tinacms/astro（一个原生 Astro 富文本渲染器加上一行 Astro 集成）和 @tinacms/bridge（一个仅在编辑器 iframe 内加载的小型 postMessage 客户端）的形式提供。

本指南将介绍本地设置、内容建模、运行 TinaCMS 和连接可视化编辑的过程。

入门

1. 在您的 Astro 站点中初始化 TinaCMS

在站点的根目录中运行：

npx @tinacms/cli@latest init

此命令将提示您进行一些设置问题。当被问及公共资产目录时，输入：

public

或者，从无 React 的入门模板开始：

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

这将设置一个博客就绪的 Astro 入门模板，其中 TinaCMS 和可视化编辑已预配置，源代码树中没有 React。

建模您的内容

在 tina/config.ts 中定义您的内容模型。完整的模式参考请参见内容建模文档。

运行 TinaCMS

与 Astro 一起启动开发服务器：

npx tinacms dev -c "astro dev"

注意：可以在 astro dev 后添加 --port 8080 以指定自定义端口。

运行后，导航到：

http://localhost:<port>/admin/index.html
或
/admin（如果使用 Tina Astro Starter，它会重定向到 /admin/index.html）

提示： 如果遇到错误，请查看常见错误页面。

您现在应该可以看到 Tina 管理界面，能够选择帖子、保存更改，并观察更新持久化到本地 markdown 文件中。

TinaCMS 管理界面

启用可视化编辑

可视化编辑（点击聚焦、编辑器输入时实时预览、并排管理 + 页面）在没有 React 的 Astro 上通过 @tinacms/astro 包工作。入门模板已预配置。对于现有站点：

pnpm add @tinacms/astro tinacms
pnpm add @astrojs/node          # 或 @astrojs/vercel / netlify / cloudflare

然后在 astro.config.mjs 中：

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

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [tina()],
});

那单个 tina() 调用自动注入请求范围的中间件（在编辑模式响应中拼接桥接线）并将原生 JS 桥接作为静态文件阶段在 /admin/bridge.js。生产 HTML 与无 Tina 的 Astro 应用字节相同。

您需要一个 SSR 适配器。 每个岛屿刷新端点（/tina-island/[name]）在请求时运行。使用 @astrojs/node、@astrojs/vercel、@astrojs/netlify 或 @astrojs/cloudflare。output: 'server' 是最简单的选择；output: 'static' 也可以，只要可编辑区域被 <TinaIsland>（包的标记组件）包裹，并且适配器可以提供按需的一个岛屿路由。

完整的连接（requestWithMetadata() 数据加载器、岛屿注册表、<TinaIsland> 包装器、tinaField() 标记、每个岛屿端点）记录在可视化编辑设置 → Astro中。

可视化编辑

项目结构

入门模板和可视化编辑设置围绕四个活动部分组织：

src/lib/：data.ts（每个集合的获取器——每个调用生成的 Tina 客户端并通过 @tinacms/astro/data 中的 requestWithMetadata() 管道结果），islands.ts（由 experimental_createIslandRoute 消费的可编辑区域注册表）。
src/pages/tina-island/[name].ts：桥接在每次按键时 POST 的动态端点。一行：experimental_createIslandRoute(islands)。
src/components/islands/*.astro：纯 Astro 渲染器（用于富文本的 <TinaMarkdown>，用于点击编辑标记的 tinaField()）。
astro.config.mjs：注册 tina() 集成；中间件自动处理桥接注入——无需维护共享的 <head> 连接组件。

有关完整架构，请参见可视化编辑设置 → Astro。

下一步

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

有关更多详细信息，请访问官方 TinaCMS 文档和 Astro 文档。加入 TinaCMS Discord 以获得社区支持。

另请参阅

Next.js 设置指南 - 使用 Tina 与 Next.js
Hugo 设置指南 - 使用 Tina 与 Hugo
自托管选项 - 在您自己的基础设施上托管 Tina

上次编辑: May 26, 2026

Next.js Pages Router

Astro + Tina 设置指南

入门