Sanity 模式 是做什麼的?
快速指南: 使用 Sanity 進行結構化內容管理,搭配 GROQ 查詢、透過
defineType/defineField的型別 Schema,以及用於資料擷取的@sanity/client。務必將apiVersion設為日期字串,對公開讀取使用useCdn: true,明確處理草稿文件,使用@sanity/image-url進行圖片轉換,並使用@portabletext/react渲染富文本。使用sanity typegen generate產生 TypeScript 型別。
<critical_requirements>
重要:使用此技能前須知
所有程式碼必須遵循 CLAUDE.md 中的專案慣例(kebab-case、具名匯出、匯入排序、
import type、具名常數)
(在 createClient 上,你「必須」始終將 apiVersion 設定為日期字串,例如 '2025-02-19' — 省略它會使用可能出錯的舊版 API)
(進行公開讀取查詢時「必須」使用 useCdn: true,使用 token 或需要最新資料時則使用 useCdn: false)
(對於任何動態值,「必須」使用參數化 GROQ 查詢 ($param) — 切勿將使用者輸入內插到 GROQ 字串中)
(你「必須」明確處理草稿 — 草稿文件的 _id 帶有 drafts. 前綴,並且在 perspective: 'published' 下預設不會回傳)
(你「必須」使用 groq 的 defineQuery() 並將查詢指派給具名變數,以便 TypeGen 產生型別)
</critical_requirements>
自動偵測: Sanity, sanity, @sanity/client, createClient, GROQ, groq, defineType, defineField, defineArrayMember, @sanity/image-url, urlFor, @portabletext/react, PortableText, portable text, block content, sanity.config, sanity.cli, typegen, sanity studio, content lake
使用時機:
- 使用
createClient設定@sanity/client以進行資料擷取 - 撰寫 GROQ 查詢(篩選、投影、關聯、排序、切片)
- 使用
defineType、defineField、defineArrayMember定義內容 Schema - 使用
@portabletext/react渲染 Portable Text(區塊內容) - 使用
@sanity/image-url產生圖片 URL(響應式圖片、裁切、熱點) - 執行異動(建立、修補、刪除、交易)
- 使用
client.listen()設定即時監聽器 - 使用 Sanity TypeGen 產生 TypeScript 型別
涵蓋的主要模式:
- 使用
createClient和apiVersion設定進行用戶端設定 - GROQ 查詢語言:篩選、投影、排序、切片、關聯、參考
- Schema 定義:文件類型、物件類型、陣列、參考、圖片
- 使用自訂元件渲染 Portable Text
- 內含響應式圖片和轉換功能的圖片 URL 建構器
- 異動:建立、createOrReplace、修補、刪除、交易
- 透過
client.listen()實現的即時監聽器 - 使用
defineQuery()進行型別安全的 GROQ 查詢 TypeGen
何時「不」使用此技能:
- 僅限 GraphQL 的 API(Sanity 主要支援 GROQ;如有需要,請使用 GraphQL 技能)
- 直接資料庫存取(Sanity 是託管的內容湖,不是資料庫)
- 非 Sanity 的 CMS 平台(請使用適用於你的 CMS 的專用技能)
詳細資源:
- 關於決策框架和快速參考表,請參閱 reference.md
用戶端與 GROQ:
- examples/core.md — 用戶端設定、GROQ 查詢、錯誤處理、TypeGen
Schema:
- examples/schemas.md — defineType、defineField、文件類型、物件類型、參考、圖片
豐富內容:
- examples/rich-content.md — Portable Text 渲染、圖片 URL 建構器、響應式圖片
異動與即時功能:
- examples/mutations.md — 建立、修補、刪除、交易、即時監聽器
理念
Sanity 是一個結構化內容平台,建構在即時內容湖、GROQ(圖形關聯物件查詢)作為其查詢語言,以及 Sanity Studio 作為可自訂的編輯環境之上。
核心原則:
- 結構化內容 — 內容由 Schema(
defineType、defineField)定義,這些 Schema 描述了形狀、驗證和編輯 UI。Schema 是程式碼,而不是設定檔。 - GROQ 優先查詢 — GROQ 讓你能在單一查詢中進行篩選、投影、關聯和重新塑造資料。與 REST 或 GraphQL 不同,GROQ 查詢會回傳你在投影中定義的確切形狀。
- 作為資料的內容 — 富文本儲存為 Portable Text(一個基於 JSON 的規範),使其能在任何前端框架中渲染,而不受供應商鎖定。
- API 版本控制 — 每個用戶端必須指定一個
apiVersion日期字串。這會將你的程式碼鎖定到特定的 API 行為,防止破壞性變更影響生產環境。 - CDN 快取 — 公開讀取查詢使用
useCdn: true以獲得邊緣快取回應。異動和經過驗證的讀取使用useCdn: false以取得最新資料。 - 型別產生 — Sanity TypeGen 會從你的 Schema 和 GROQ 查詢中產生 TypeScript 型別,實現從內容模型到前端的端到端型別安全。
何時使用 Sanity:
- 內容驅動的網站和應用程式(部落格、行銷網站、文件)
- 需要在可自訂的 Studio 中進行即時協作編輯的專案
- 從單一內容來源進行多頻道內容傳遞(網頁、行動裝置、物聯網)
- 希望使用 GROQ 和 TypeGen 進行型別安全內容查詢的團隊
何時「不」使用:
- 需要 ACID 保證的交易性資料(請使用資料庫)
- 大規模的使用者生成內容(Sanity 針對編輯內容進行了最佳化)
- 需要自託管 CMS 的專案(Sanity 的內容湖是託管的,但 Studio 是開源的)
核心模式
模式 1:使用 createClient 進行用戶端設定
使用專案 ID、資料集、API 版本和 CDN 偏好設定來設定 @sanity/client。始終將 apiVersion 設定為日期字串,並明確設定 useCdn。
import { createClient } from "@sanity/client";
export const client = createClient({
projectId: process.env.SANITY_PROJECT_ID!,
dataset: process.env.SANITY_DATASET!,
apiVersion: "2025-02-19", // 鎖定到特定的 API 版本日期
useCdn: true, // 公開讀取為 true,經過驗證/最新資料為 false
});
關於雙用戶端設定(公開 + 帶 token 的預覽),請參閱 examples/core.md。
模式 2:帶有篩選和投影的 GROQ 查詢
GROQ 查詢結合了篩選、投影、排序和切片。始終對 TypeGen 使用 defineQuery(),對動態值使用 $param。
import { defineQuery } from "groq";
const POST_BY_SLUG_QUERY = defineQuery(`
*[_type == "post" && slug.current == $slug][0]{
_id, title, body, "author": author->{name, image}
}
`);
const post = await client.fetch(POST_BY_SLUG_QUERY, { slug: "my-post" });
切勿將使用者輸入內插到 GROQ 字串中 — 始終使用 $param 參數以防止 GROQ 注入。關於進階查詢(組合查詢、條件投影),請參閱 examples/core.md。
模式 3:使用 defineType 和 defineField 定義 Schema
使用來自 "sanity" 的 defineType、defineField 和 defineArrayMember 定義內容結構,以實現型別安全和 Studio UI。
import { defineType, defineField } from "sanity";
export const postType = defineType({
name: "post",
type: "document",
fields: [
defineField({
name: "title",
type: "string",
validation: (r) => r.required(),
}),
defineField({ name: "slug", type: "slug", options: { source: "title" } }),
],
});
關於完整的 Schema(含熱點的圖片、陣列、參考、預覽、物件類型),請參閱 examples/schemas.md。
模式 4:Portable Text 渲染
使用 @portabletext/react 渲染區塊內容。為非標準區塊(圖片、程式碼)和標記(連結、高亮)定義自訂的 PortableTextComponents。
import { PortableText } from "@portabletext/react";
<PortableText value={body} components={components} />;
不要使用棄用的 @sanity/block-content-to-react 套件。關於完整的元件範例,請參閱 examples/rich-content.md。
模式 5:圖片 URL 建構器
使用 @sanity/image-url 來產生最佳化、支援裁切和熱點的響應式圖片 URL。
import { createImageUrlBuilder } from "@sanity/image-url";
const builder = createImageUrlBuilder(client);
export function urlFor(source: SanityImageSource) {
return builder.image(source);
}
// 用法: urlFor(image).width(800).auto("format").url()
關於響應式 srcSet 模式和圖片轉換,請參閱 examples/rich-content.md。
模式 6:異動(建立、修補、刪除)
使用 @sanity/client 的方法進行文件異動。始終在修補和交易上呼叫 .commit()。
await client.create({ _type: "post", title: "New Post" });
await client.patch("post-123").set({ title: "Updated" }).commit();
await client.delete("post-123");
關於 createOrReplace、createIfNotExists、交易、陣列插入和可見性選項,請參閱 examples/mutations.md。
模式 7:即時監聽器
使用 client.listen() 訂閱文件變更。監聽器僅使用 GROQ 的篩選部分 — 投影和排序將被忽略。
const subscription = client.listen(`*[_type == "post"]`).subscribe({
next: (update) => {
/* update.transition: 'update' | 'appear' | 'disappear' */
},
error: (err) => console.error(err),
});
subscription.unsubscribe(); // 完成後清理
對於生產環境的前端,請評估較新的 Live Content API 作為更簡單的替代方案。關於監聽器選項和注意事項,請參閱 examples/mutations.md。
模式 8:用於型別安全 GROQ 的 TypeGen
在 sanity.cli.ts 中設定 TypeGen,設定 overloadClientMethods: true 以獲得型別化的 client.fetch 結果。使用來自 "groq" 的 defineQuery() 使查詢可被 TypeGen 發現。
// sanity.cli.ts — 設定 typegen.overloadClientMethods: true
// queries/post-queries.ts — 使用 defineQuery() 包裝查詢
// sanity.types.ts — 自動產生的結果型別
const posts = await client.fetch(allPostsQuery); // 型別化的結果
未使用 defineQuery() 的內聯查詢字串會產生無型別 (any) 的結果。關於完整的 TypeGen 設定和工作流程,請參閱 examples/core.md。
<decision_framework>
決策框架
useCdn: true vs false
資料是公開且非個人化的嗎?
├─ 是 → useCdn: true (邊緣快取,快速)
└─ 否 →
├─ 使用 token 進行經過驗證的讀取? → useCdn: false
├─ 需要即時最新資料(預覽)? → useCdn: false
└─ 正在執行異動? → useCdn: false
草稿處理
你需要草稿文件嗎?
├─ 是 → 使用 perspective: 'previewDrafts'(需要 token)
├─ 否 → 使用 perspective: 'published'(自 API v2025-02-19 起為預設值)
└─ 混合(預覽模式切換)?
└─ 建立兩個用戶端:一個公開(useCdn: true),一個預覽(token + useCdn: false)
GROQ 查詢回傳形狀
你期望多少個文件?
├─ 一個(依 ID、slug、單例) → 在結尾添加 [0](回傳物件或 null)
├─ 多個(列表、饋送) → 無切片後綴(回傳陣列)
└─ 分頁 → 添加 [start...end] 切片
圖片處理
圖片應該如何傳遞?
├─ 固定尺寸(縮圖、頭像) → urlFor(img).width(W).height(H).url()
├─ 響應式(文章圖片) → 具有多個寬度的 srcSet
├─ 格式最佳化 → .auto('format') 用於 WebP/AVIF
└─ 裁剪至長寬比 → .width(W).height(H).fit('crop')
異動方法選擇
你需要什麼操作?
├─ 建立新文件 → client.create()
├─ 建立或完全取代 → client.createOrReplace()(用於單例)
├─ 僅在不存在時建立 → client.createIfNotExists()
├─ 更新特定欄位 → client.patch(id).set({...}).commit()
├─ 移除欄位 → client.patch(id).unset([...]).commit()
├─ 多個相關變更 → client.transaction()...commit()
└─ 刪除文件 → client.delete(id)
</decision_framework>
<red_flags>
危險標記
高優先級問題:
- 用戶端缺少
apiVersion— 省略apiVersion會使用可能隨時變更的舊版 API 行為。始終鎖定到日期字串。 - GROQ 查詢中的字串內插 — 將使用者輸入內插到 GROQ 字串中會啟用 GROQ 注入。始終使用
$param參數。 - 將
useCdn: true與 token 一起使用 — CDN 快取的回應會忽略驗證 token。經過驗證的查詢必須使用useCdn: false。 - 在沒有 token 的情況下存取草稿文件 — 草稿(
drafts.*文件)需要 API token 和perspective: 'previewDrafts'。沒有 token,草稿是不可見的。
中等優先級問題:
- 當只需要幾個欄位時,使用
{...}擷取所有欄位 — 過度擷取會浪費頻寬和 CDN 快取效率。僅投影你需要的欄位。 - 修補缺少
.commit()— 沒有.commit()的client.patch(id).set({...})不會執行任何操作 — 異動從未發送。 - 未對 GROQ 查詢使用
defineQuery()— TypeGen 無法為未包裝在defineQuery()中或未指派給具名變數的查詢產生型別。 - 硬編碼的專案 ID 或資料集 — 使用環境變數;硬編碼的值會阻止環境切換並洩漏專案細節。
- 使用已棄用的
@sanity/block-content-to-react— 已被@portabletext/react取代。舊套件已不再維護。
常見錯誤:
- 在異動中忘記陣列項目的
_key— Sanity 陣列中的每個項目都必須有唯一的_key欄位。缺少_key的異動將會失敗。 - 使用
_id搭配client.create()—create()會產生一個隨機的_id。如果你指定_id且文件存在,它會報錯。對於冪等操作,請使用createOrReplace()或createIfNotExists()。 - 未處理
[0]回傳null的情況 — 一個 GROQ 查詢以[0]結尾可能會回傳null(如果沒有比對結果)。
</red_flags>