Communitygithub.com

Sanity 模式

用於結構化內容管理的平台 — GROQ 查詢、Schema 定義、@sanity/client、Portable Text、圖片處理、即時監聽、資料異動、TypeGen

Sanity 模式 是什麼?

此技能提供在 Sanity 內容平台上進行結構化內容管理的完整指南和模式。它涵蓋了從客戶端設定(使用 `createClient` 並明確設定 `apiVersion`)到進階 GROQ 查詢、類型安全的 Schema 定義(使用 `defineType`/`defineField`)以及使用 `@portabletext/react` 渲染富文本的所有內容。主要特點包括使用 `@sanity/image-url` 進行圖片處理、使用 `client.listen()` 進行即時更新、完整的 CRUD 異動支援,以及透過 Sanity TypeGen 從 Schema 和 GROQ 查詢自動產生 TypeScript 類型。此技能支援所有主流前端框架(React、Next.js、Vue、Svelte),並強調關鍵的最佳實踐,如使用參數化查詢防止 GROQ 注入、適當的文件草稿處理以及明確的 CDN 快取策略。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-cms-sanity

在你喜歡的 AI 中提問

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

說明文件

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:

Schema:

  • examples/schemas.md — defineType、defineField、文件類型、物件類型、參考、圖片

豐富內容:

異動與即時功能:


理念

Sanity 是一個結構化內容平台,建構在即時內容湖、GROQ(圖形關聯物件查詢)作為其查詢語言,以及 Sanity Studio 作為可自訂的編輯環境之上。

核心原則:

  1. 結構化內容 — 內容由 Schema(defineType、defineField)定義,這些 Schema 描述了形狀、驗證和編輯 UI。Schema 是程式碼,而不是設定檔。
  2. GROQ 優先查詢 — GROQ 讓你能在單一查詢中進行篩選、投影、關聯和重新塑造資料。與 REST 或 GraphQL 不同,GROQ 查詢會回傳你在投影中定義的確切形狀。
  3. 作為資料的內容 — 富文本儲存為 Portable Text(一個基於 JSON 的規範),使其能在任何前端框架中渲染,而不受供應商鎖定。
  4. API 版本控制 — 每個用戶端必須指定一個 apiVersion 日期字串。這會將你的程式碼鎖定到特定的 API 行為,防止破壞性變更影響生產環境。
  5. CDN 快取 — 公開讀取查詢使用 useCdn: true 以獲得邊緣快取回應。異動和經過驗證的讀取使用 useCdn: false 以取得最新資料。
  6. 型別產生 — 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>

Individual skills in this repo

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

相關技能