TinaCMS 技能
將 TinaCMS 整合至現代 Web 應用程式的完整技能。
什麼是 TinaCMS?
TinaCMS 是一個開源、以 Git 為基礎的無頭式內容管理系統 (CMS),讓開發者與內容創作者能夠在內容豐富的網站上順暢協作。
主要功能
-
Git 備份儲存
- 內容以 Markdown、MDX 或 JSON 檔案格式儲存在 Git 儲存庫中
- 完整的版本控制與變更歷史
- 無供應商鎖定 – 內容保存在您的儲存庫中
-
視覺化/語境編輯
- 並排編輯體驗
- 即時預覽輸入的變更
- 適用於 Markdown 內容的所見即所得式編輯
-
Schema 驅動的內容建模
- 在程式碼中定義內容結構 (
tina/config.ts) - 從 Schema 自動產生型別安全的 GraphQL API
- 使用集合 (Collections) 和欄位 (Fields) 系統來組織內容
- 在程式碼中定義內容結構 (
-
彈性部署
- TinaCloud:受管服務(最簡便,提供免費方案)
- 自行託管:Cloudflare Workers、Vercel Functions、Netlify Functions、AWS Lambda
- 多種驗證選項(Auth.js、自訂、本機開發)
-
框架支援
- 最佳: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:
-
建置內容密集型網站
- 部落格和個人網站
- 文件網站
- 行銷網站
- 作品集網站
-
非技術編輯人員需要存取
- 不具程式碼知識的內容團隊
- 管理頁面的行銷團隊
- 撰寫部落格文章的作家
-
希望採用 Git 工作流程
- 希望透過 Git 進行內容版本控制
- 需要透過 Pull Request 進行內容審查
- 偏好將內容與程式碼一同保存在儲存庫中
-
需要視覺編輯
- 編輯人員希望即時看到變更
- 偏好所見即所得體驗
- 並排編輯工作流程
❌ 不應使用 TinaCMS 的情況:
-
需要即時協作
- 多位使用者同時編輯(像是 Google 文件)
- 請改用 Sanity、Contentful 或 Firebase
-
高度動態的資料
- 庫存頻繁變動的電商產品目錄
- 即時儀表板
- 請改用傳統資料庫(D1、PostgreSQL)
-
不需要內容管理
- 應用程式是資料驅動而非內容驅動
- 硬編碼內容已足夠
各框架的設定模式
根據您選擇的框架使用適當的設定模式。
1. Next.js 設定(推薦)
App Router (Next.js 13+)
步驟:
-
初始化 TinaCMS:
npx @tinacms/cli@latest init- 當提示輸入公開資源目錄時,請輸入
public
- 當提示輸入公開資源目錄時,請輸入
-
更新 package.json 的 scripts:
{ "scripts": { "dev": "tinacms dev -c \"next dev\"", "build": "tinacms build && next build", "start": "tinacms build && next start" } } -
設定環境變數:
# .env.local NEXT_PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token -
啟動開發伺服器:
npm run dev -
存取管理介面:
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 設定
步驟:
-
安裝依賴套件:
npm install react@^19 react-dom@^19 tinacms -
初始化 TinaCMS:
npx @tinacms/cli@latest init- 將公開資源目錄設定為
public
- 將公開資源目錄設定為
-
更新 vite.config.ts:
import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { port: 3000 // TinaCMS 預設埠號 } }) -
更新 package.json 的 scripts:
{ "scripts": { "dev": "tinacms dev -c \"vite\"", "build": "tinacms build && vite build", "preview": "vite preview" } } -
建立管理介面:
選項 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> -
使用 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> ) } -
設定環境變數:
# .env VITE_TINA_CLIENT_ID=your_client_id VITE_TINA_TOKEN=your_read_only_token
範本:請參閱 templates/vite-react/
3. Astro 設定
步驟:
-
使用官方起始範本(推薦):
npx create-tina-app@latest --template tina-astro-starter或手動初始化:
npx @tinacms/cli@latest init -
更新 package.json 的 scripts:
{ "scripts": { "dev": "tinacms dev -c \"astro dev\"", "build": "tinacms build && astro build", "preview": "astro preview" } } -
設定 Astro:
// astro.config.mjs import { defineConfig } from 'astro/config' import react from '@astro/react' export default defineConfig({ integrations: [react()] // Tina 管理介面需要 }) -
視覺編輯(實驗性):
- 需要 React 元件
- 使用
client:tinaDirective進行互動式編輯 - 截至 2025 年 10 月,完整視覺編輯仍為實驗性功能
-
設定環境變數:
# .env PUBLIC_TINA_CLIENT_ID=your_client_id TINA_TOKEN=your_read_only_token
最適用於:內容為主的靜態網站、文件、部落格
範本:請參閱 templates/astro/
4. 框架無關設定
適用於:Hugo、Jekyll、Eleventy、Gatsby、Remix 或任何框架
步驟:
-
初始化 TinaCMS:
npx @tinacms/cli@latest init -
手動設定建置腳本:
{ "scripts": { "dev": "tinacms dev -c \"<你的開發指令>\"", "build": "tinacms build && <你的建置指令>" } } -
管理介面:
- 自動建立在
http://localhost:<埠號>/admin/index.html - 埠號取決於您的框架
- 自動建立在
-
資料擷取:
- 無視覺編輯(僅有側邊欄)
- 透過 Git 備份的介面編輯內容
- 變更直接儲存至檔案
-
設定環境變數:
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(推薦)
最簡單的設定,適用於大多數專案。
- 註冊 TinaCloud 帳號
- 建立專案 並連結您的 Git 儲存庫
- 設定環境變數 使用提供的
NEXT_PUBLIC_TINA_CLIENT_ID和TINA_TOKEN - 部署 您的網站至 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_ID | TinaCloud 用戶端 ID(Next.js 公開) | 是(若使用 TinaCloud) |
TINA_TOKEN | TinaCloud 唯讀 Token | 是(若使用 TinaCloud) |
GITHUB_BRANCH | 要使用的 Git 分支 | 建議設定 |
VERCEL_GIT_COMMIT_REF | Vercel 自動提供的 Vercel 分支 | 自動 |
VITE_TINA_CLIENT_ID | TinaCloud 用戶端 ID(Vite 公開) | 是(若使用 TinaCloud 與 Vite) |
PUBLIC_TINA_CLIENT_ID | TinaCloud 用戶端 ID(Astro 公開) | 是(若使用 TinaCloud 與 Astro) |
常見問題排解
問題:#1:ESbuild 編譯錯誤
症狀: Build failed with 1 error
解決方案:
- 清除
node_modules和鎖定檔案 - 重新安裝:
rm -rf node_modules package-lock.json npm install - 確保使用支援的 Node.js 版本 (>=18.x)
問題:#2:模組解析問題
症狀: Cannot find module '@tinacms/cli'
解決方案:
npm install -D @tinacms/cli@latest
確保 @tinacms/cli 在 package.json 的 devDependencies 中。
問題:#3:Docker 繫結問題
症狀: Docker 環境中的權限錯誤
解決方案:
- 在 Dockerfile 中設定
USER:USER node - 確保
content/目錄存在:RUN mkdir -p content && chown -R node:node content
問題:#4:管理介面無法載入
症狀: 管理介面顯示空白頁面
解決方案:
- 檢查是否有正確執行的
tinacms dev指令 - 驗證
public/admin/index.html是否存在 - 確認環境變數是否設置正確
- 檢查瀏覽器主控台是否有錯誤
相關參考資料
若要深入了解,請查閱這些資源:
- TinaCMS 官方文件:https://tina.io/docs/
- TinaCMS GitHub 儲存庫:https://github.com/tinacms/tinacms
- TinaCloud 管理介面:https://app.tina.io
- 架構特定指南:請參閱
references/目錄field-types-reference.mddeployment-guide.mdauthentication-setup.md
疑難排解指令
# 檢查 TinaCMS 版本
npx tinacms --version
# 檢查 TinaCMS 設定
npx tinacms audit
# 重新產生 TypeScript 類型
npx tinacms build
# 以詳細模式執行開發伺服器
tinacms dev -c "next dev" --verbose
後續步驟
- 根據您的架構選擇一個設定模式
- 定義您的內容 Schema
- 建立您的第一個集合
- 在
/admin路徑存取管理介面 - 邀請非技術團隊成員管理內容
如需詳細資訊,請查閱 references/ 目錄中的參考文件,或造訪 https://tina.io/docs/。