Communitygithub.com

ovachiever/droid-tings

建置內容豐富的網站,並搭配 Git 備份的 TinaCMS。為部落格、文件及行銷網站提供視覺化編輯與內容管理功能,適合非技術編輯人員使用。

droid-tings 是什麼?

這個技能旨在將 TinaCMS 整合到現代化的 Web 應用程式中。TinaCMS 是一個開源、以 Git 為基礎的無頭式內容管理系統 (CMS),讓開發者與內容創作者能夠順暢協作。它支援以 Markdown、MDX 或 JSON 格式將內容儲存在 Git 儲存庫中,提供完整的版本控制與變更歷史,並可避免供應商鎖定。其主要功能包括視覺化/語境編輯(提供所見即所得式的即時預覽)、基於 Schema 驅動的內容建模(可在程式碼中定義結構類型,並自動產生型別安全的 GraphQL API),以及靈活的部署選項(可選擇 TinaCloud 託管服務或自行託管於 Cloudflare Workers、Vercel Functions 等平台)。此技能最適合整合到 Next.js、Vite + React 或 Astro 架構中,同時也支援 Hugo、Jekyll、Eleventy 等其他框架,但在非 React 框架中視覺編輯功能會受限。使用此技能的時機包括建設部落格、文件網站、行銷網站等內容密集型網站,且需要讓非技術編輯人員能夠透過 Git 工作流程進行視覺化編輯。相對地,若需要即時協作編輯、處理高動態資料(如電商產品目錄),或應用程式並非以內容為導向,則不建議使用。技能內容涵蓋了各框架的設定步驟、Schema 建模最佳實踐(包括集合與欄位類型的詳細說明),以及常見問題的疑難排解。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ovachiever/droid-tings/tree/HEAD/skills/tinacms

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

TinaCMS 技能

將 TinaCMS 整合至現代 Web 應用程式的完整技能。


什麼是 TinaCMS?

TinaCMS 是一個開源、以 Git 為基礎的無頭式內容管理系統 (CMS),讓開發者與內容創作者能夠在內容豐富的網站上順暢協作。

主要功能

  1. Git 備份儲存

    • 內容以 Markdown、MDX 或 JSON 檔案格式儲存在 Git 儲存庫中
    • 完整的版本控制與變更歷史
    • 無供應商鎖定 – 內容保存在您的儲存庫中
  2. 視覺化/語境編輯

    • 並排編輯體驗
    • 即時預覽輸入的變更
    • 適用於 Markdown 內容的所見即所得式編輯
  3. Schema 驅動的內容建模

    • 在程式碼中定義內容結構 (tina/config.ts)
    • 從 Schema 自動產生型別安全的 GraphQL API
    • 使用集合 (Collections) 和欄位 (Fields) 系統來組織內容
  4. 彈性部署

    • TinaCloud:受管服務(最簡便,提供免費方案)
    • 自行託管:Cloudflare Workers、Vercel Functions、Netlify Functions、AWS Lambda
    • 多種驗證選項(Auth.js、自訂、本機開發)
  5. 框架支援

    • 最佳:Next.js (App Router + Pages Router)
    • 良好:React、Astro(實驗性視覺編輯)、Gatsby、Hugo、Jekyll、Remix、11ty
    • 框架無關:可搭配任何框架(視覺編輯僅限於 React)

目前版本

  • tinacms:2.9.0 (2025 年 9 月)
  • @tinacms/cli:1.11.0 (2025 年 10 月)
  • React 支援:19.x (>=18.3.1 <20.0.0)

何時使用此技能

✅ 在以下情況使用 TinaCMS:

  1. 建置內容密集型網站

    • 部落格和個人網站
    • 文件網站
    • 行銷網站
    • 作品集網站
  2. 非技術編輯人員需要存取

    • 不具程式碼知識的內容團隊
    • 管理頁面的行銷團隊
    • 撰寫部落格文章的作家
  3. 希望採用 Git 工作流程

    • 希望透過 Git 進行內容版本控制
    • 需要透過 Pull Request 進行內容審查
    • 偏好將內容與程式碼一同保存在儲存庫中
  4. 需要視覺編輯

    • 編輯人員希望即時看到變更
    • 偏好所見即所得體驗
    • 並排編輯工作流程

❌ 不應使用 TinaCMS 的情況:

  1. 需要即時協作

    • 多位使用者同時編輯(像是 Google 文件)
    • 請改用 Sanity、Contentful 或 Firebase
  2. 高度動態的資料

    • 庫存頻繁變動的電商產品目錄
    • 即時儀表板
    • 請改用傳統資料庫(D1、PostgreSQL)
  3. 不需要內容管理

    • 應用程式是資料驅動而非內容驅動
    • 硬編碼內容已足夠

各框架的設定模式

根據您選擇的框架使用適當的設定模式。

1. Next.js 設定(推薦)

App Router (Next.js 13+)

步驟:

  1. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
    • 當提示輸入公開資源目錄時,請輸入 public
  2. 更新 package.json 的 scripts:

    {
      "scripts": {
        "dev": "tinacms dev -c \"next dev\"",
        "build": "tinacms build && next build",
        "start": "tinacms build && next start"
      }
    }
    
  3. 設定環境變數:

    # .env.local
    NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    
  4. 啟動開發伺服器:

    npm run dev
    
  5. 存取管理介面:

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

建立的關鍵檔案:

  • tina/config.ts - Schema 設定
  • app/admin/[[...index]]/page.tsx - 管理 UI 路由(使用 App Router 時)

範本:請參閱 templates/nextjs/tina-config-app-router.ts


Pages Router (Next.js 12 及更早版本)

設定過程相同,但管理路由為:

  • pages/admin/[[...index]].tsx 而非 app 目錄

資料擷取模式:

// pages/posts/[slug].tsx
import { client } from '../../tina/__generated__/client'
import { useTina } from 'tinacms/dist/react'

export default function BlogPost(props) {
  // 為視覺編輯進行水合
  const { data } = useTina({
    query: props.query,
    variables: props.variables,
    data: props.data
  })

  return (
    <article>
      <h1>{data.post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: data.post.body }} />
    </article>
  )
}

export async function getStaticProps({ params }) {
  const response = await client.queries.post({
    relativePath: `${params.slug}.md`
  })

  return {
    props: {
      data: response.data,
      query: response.query,
      variables: response.variables
    }
  }
}

export async function getStaticPaths() {
  const response = await client.queries.postConnection()
  const paths = response.data.postConnection.edges.map((edge) => ({
    params: { slug: edge.node._sys.filename }
  }))

  return { paths, fallback: 'blocking' }
}

範本:請參閱 templates/nextjs/tina-config-pages-router.ts


2. Vite + React 設定

步驟:

  1. 安裝依賴套件:

    npm install react@^19 react-dom@^19 tinacms
    
  2. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
    • 將公開資源目錄設定為 public
  3. 更新 vite.config.ts:

    import { defineConfig } from 'vite'
    import react from '@vitejs/plugin-react'
    
    export default defineConfig({
      plugins: [react()],
      server: {
        port: 3000  // TinaCMS 預設埠號
      }
    })
    
  4. 更新 package.json 的 scripts:

    {
      "scripts": {
        "dev": "tinacms dev -c \"vite\"",
        "build": "tinacms build && vite build",
        "preview": "vite preview"
      }
    }
    
  5. 建立管理介面:

    選項 A:手動路由 (React Router)

    // src/pages/Admin.tsx
    import TinaCMS from 'tinacms'
    
    export default function Admin() {
      return <div id="tina-admin" />
    }
    

    選項 B:直接 HTML

    <!-- public/admin/index.html -->
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>Tina CMS</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </head>
      <body>
        <div id="root"></div>
        <script type="module" src="/@fs/[path-to-tina-admin]"></script>
      </body>
    </html>
    
  6. 使用 useTina 鉤子進行視覺編輯:

    import { useTina } from 'tinacms/dist/react'
    import { client } from '../tina/__generated__/client'
    
    function BlogPost({ initialData }) {
      const { data } = useTina({
        query: initialData.query,
        variables: initialData.variables,
        data: initialData.data
      })
    
      return (
        <article>
          <h1>{data.post.title}</h1>
          <div>{/* 渲染內容 */}</div>
        </article>
      )
    }
    
  7. 設定環境變數:

    # .env
    VITE_TINA_CLIENT_ID=your_client_id
    VITE_TINA_TOKEN=your_read_only_token
    

範本:請參閱 templates/vite-react/


3. Astro 設定

步驟:

  1. 使用官方起始範本(推薦):

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

    或手動初始化:

    npx @tinacms/cli@latest init
    
  2. 更新 package.json 的 scripts:

    {
      "scripts": {
        "dev": "tinacms dev -c \"astro dev\"",
        "build": "tinacms build && astro build",
        "preview": "astro preview"
      }
    }
    
  3. 設定 Astro:

    // astro.config.mjs
    import { defineConfig } from 'astro/config'
    import react from '@astro/react'
    
    export default defineConfig({
      integrations: [react()]  // Tina 管理介面需要
    })
    
  4. 視覺編輯(實驗性):

    • 需要 React 元件
    • 使用 client:tinaDirective 進行互動式編輯
    • 截至 2025 年 10 月,完整視覺編輯仍為實驗性功能
  5. 設定環境變數:

    # .env
    PUBLIC_TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

最適用於:內容為主的靜態網站、文件、部落格

範本:請參閱 templates/astro/


4. 框架無關設定

適用於:Hugo、Jekyll、Eleventy、Gatsby、Remix 或任何框架

步驟:

  1. 初始化 TinaCMS:

    npx @tinacms/cli@latest init
    
  2. 手動設定建置腳本:

    {
      "scripts": {
        "dev": "tinacms dev -c \"<你的開發指令>\"",
        "build": "tinacms build && <你的建置指令>"
      }
    }
    
  3. 管理介面:

    • 自動建立在 http://localhost:<埠號>/admin/index.html
    • 埠號取決於您的框架
  4. 資料擷取:

    • 無視覺編輯(僅有側邊欄)
    • 透過 Git 備份的介面編輯內容
    • 變更直接儲存至檔案
  5. 設定環境變數:

    TINA_CLIENT_ID=your_client_id
    TINA_TOKEN=your_read_only_token
    

限制:

  • 無視覺編輯(React 專屬功能)
  • 需要手動整合
  • 僅提供側邊欄式編輯

Schema 建模最佳實踐

在 tina/config.ts 中定義您的內容結構。

基本設定結構

import { defineConfig } from 'tinacms'

export default defineConfig({
  // 分支設定
  branch: process.env.GITHUB_BRANCH ||
          process.env.VERCEL_GIT_COMMIT_REF ||
          'main',

  // TinaCloud 憑證(若使用受管服務)
  clientId: process.env.NEXT_PUBLIC_TINA_CLIENT_ID,
  token: process.env.TINA_TOKEN,

  // 建置設定
  build: {
    outputFolder: 'admin',
    publicFolder: 'public',
  },

  // 媒體設定
  media: {
    tina: {
      mediaRoot: '',
      publicFolder: 'public',
    },
  },

  // 內容 Schema
  schema: {
    collections: [
      // 在此定義集合
    ],
  },
})

集合 (Collections)

集合 = 內容類型 + 目錄映射

{
  name: 'post',           // 單數,內部名稱(用於 API)
  label: 'Blog Posts',    // 複數,顯示名稱(顯示於管理介面)
  path: 'content/posts',  // 儲存檔案的目錄
  format: 'mdx',          // 檔案格式:md, mdx, markdown, json, yaml, toml
  fields: [/* ... */]     // 欄位定義陣列
}

關鍵屬性:

  • name:內部識別碼(僅限字母數字與底線)
  • label:管理介面中的人類可讀名稱
  • path:相對於專案根目錄的檔案路徑
  • format:副檔名(預設為 'md')
  • fields:內容結構定義

欄位類型參考

類型使用情境範例
string短文字(單行)標題、slug、作者姓名
rich-text長格式內容部落格內文、頁面內容
number數值價格、數量、評分
datetime日期/時間值發布日期、活動時間
boolean開啟/關閉切換草稿狀態、精選標記
image圖片上傳主圖、縮圖、頭像
reference連結至另一文件作者、分類、相關文章
object巢狀欄位群組SEO 元資料、社交連結

完整參考:請參閱 references/field-types-reference.md


集合範本

部落格文章集合

{
  name: 'post',
  label: 'Blog Posts',
  path: 'content/posts',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,  // 顯示於內容清單中
      required: true
    },
    {
      type: 'string',
      name: 'excerpt',
      label: 'Excerpt',
      ui: {
        component: 'textarea'  // 多行輸入
      }
    },
    {
      type: 'image',
      name: 'coverImage',
      label: 'Cover Image'
    },
    {
      type: 'datetime',
      name: 'date',
      label: 'Published Date',
      required: true
    },
    {
      type: 'reference',
      name: 'author',
      label: 'Author',
      collections: ['author']  // 參照作者集合
    },
    {
      type: 'boolean',
      name: 'draft',
      label: 'Draft',
      description: '若勾選,文章將不會發布',
      required: true
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true  // 主要內容區域
    }
  ],
  ui: {
    router: ({ document }) => `/blog/${document._sys.filename}`
  }
}

範本:請參閱 templates/collections/blog-post.ts


文件頁面集合

{
  name: 'doc',
  label: 'Documentation',
  path: 'content/docs',
  format: 'mdx',
  fields: [
    {
      type: 'string',
      name: 'title',
      label: 'Title',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'description',
      label: 'Description',
      ui: {
        component: 'textarea'
      }
    },
    {
      type: 'number',
      name: 'order',
      label: 'Order',
      description: '側邊欄中的排序順序'
    },
    {
      type: 'rich-text',
      name: 'body',
      label: 'Body',
      isBody: true,
      templates: [
        // 可在此定義 MDX 元件
      ]
    }
  ],
  ui: {
    router: ({ document }) => {
      const breadcrumbs = document._sys.breadcrumbs.join('/')
      return `/docs/${breadcrumbs}`
    }
  }
}

範本:請參閱 templates/collections/doc-page.ts


作者集合(參考目標)

{
  name: 'author',
  label: 'Authors',
  path: 'content/authors',
  format: 'json',  // 使用 JSON 儲存結構化資料
  fields: [
    {
      type: 'string',
      name: 'name',
      label: 'Name',
      isTitle: true,
      required: true
    },
    {
      type: 'string',
      name: 'email',
      label: 'Email',
      ui: {
        validate: (value) => {
          if (!value?.includes('@')) {
            return '無效的電子郵件地址'
          }
        }
      }
    },
    {
      type: 'image',
      name: 'avatar',
      label: 'Avatar'
    },
    {
      type: 'string',
      name: 'bio',
      label: 'Bio',
      ui: {
        component: 'textarea'
      }
    }
  ]
}

範本:請參閱 templates/collections/author.ts


驗證規則 (Validation)

為您的欄位加入驗證邏輯:

{
  type: 'string',
  name: 'slug',
  label: 'Slug',
  required: true,
  ui: {
    validate: (value) => {
      if (value && !/^[a-z0-9-]+$/.test(value)) {
        return 'Slug 只能包含小寫字母、數字與連字號'
      }
    }
  }
}

部署模式

選項 1:TinaCloud(推薦)

最簡單的設定,適用於大多數專案。

  1. 註冊 TinaCloud 帳號
  2. 建立專案 並連結您的 Git 儲存庫
  3. 設定環境變數 使用提供的 NEXT_PUBLIC_TINA_CLIENT_ID 和 TINA_TOKEN
  4. 部署 您的網站至 Vercel、Netlify 或 Cloudflare Pages

優點:

  • 無需維護後端基礎設施
  • 內建媒體管理
  • 內容審查流程
  • 協作功能

選項 2:自行託管

對於需要完全控管的團隊。

支援的後端:

  • Cloudflare Workers
  • Vercel Functions
  • Netlify Functions
  • AWS Lambda
  • 任何 Node.js 伺服器

基本伺服器端點設定:

// api/tina/[route].ts
import { TinaNodeBackend, LocalBackendAuthProvider } from '@tinacms/datalayer'

const tinaBackend = TinaNodeBackend({
  authProvider: LocalBackendAuthProvider(),
  databaseClient: async (req) => {
    const database = await import('./database')
    return database.default()
  }
})

export default async function handler(req, res) {
  await tinaBackend(req, res)
}

認證選項:

  • Auth.js (NextAuth):與 Next.js 整合
  • Custom JWT:自訂認證邏輯
  • Local Dev:僅開發模式,無認證

環境變數參考

變數用途必要
NEXT_PUBLIC_TINA_CLIENT_IDTinaCloud 用戶端 ID(Next.js 公開)是(若使用 TinaCloud)
TINA_TOKENTinaCloud 唯讀 Token是(若使用 TinaCloud)
GITHUB_BRANCH要使用的 Git 分支建議設定
VERCEL_GIT_COMMIT_REFVercel 自動提供的 Vercel 分支自動
VITE_TINA_CLIENT_IDTinaCloud 用戶端 ID(Vite 公開)是(若使用 TinaCloud 與 Vite)
PUBLIC_TINA_CLIENT_IDTinaCloud 用戶端 ID(Astro 公開)是(若使用 TinaCloud 與 Astro)

常見問題排解

問題:#1:ESbuild 編譯錯誤

症狀: Build failed with 1 error

解決方案:

  1. 清除 node_modules 和鎖定檔案
  2. 重新安裝:
    rm -rf node_modules package-lock.json
    npm install
    
  3. 確保使用支援的 Node.js 版本 (>=18.x)

問題:#2:模組解析問題

症狀: Cannot find module '@tinacms/cli'

解決方案:

npm install -D @tinacms/cli@latest

確保 @tinacms/cli 在 package.json 的 devDependencies 中。


問題:#3:Docker 繫結問題

症狀: Docker 環境中的權限錯誤

解決方案:

  1. 在 Dockerfile 中設定 USER:
    USER node
    
  2. 確保 content/ 目錄存在:
    RUN mkdir -p content && chown -R node:node content
    

問題:#4:管理介面無法載入

症狀: 管理介面顯示空白頁面

解決方案:

  1. 檢查是否有正確執行的 tinacms dev 指令
  2. 驗證 public/admin/index.html 是否存在
  3. 確認環境變數是否設置正確
  4. 檢查瀏覽器主控台是否有錯誤

相關參考資料

若要深入了解,請查閱這些資源:


疑難排解指令

# 檢查 TinaCMS 版本
npx tinacms --version

# 檢查 TinaCMS 設定
npx tinacms audit

# 重新產生 TypeScript 類型
npx tinacms build

# 以詳細模式執行開發伺服器
tinacms dev -c "next dev" --verbose

後續步驟

  1. 根據您的架構選擇一個設定模式
  2. 定義您的內容 Schema
  3. 建立您的第一個集合
  4. 在 /admin 路徑存取管理介面
  5. 邀請非技術團隊成員管理內容

如需詳細資訊,請查閱 references/ 目錄中的參考文件,或造訪 https://tina.io/docs/。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能