開始使用

Next.js

在 Kanorio 上建構 Next.js App Router 前端，支援快取讀取、Webhook 重新驗證、草稿模式、SEO 檔案與邊緣重新導向。

Next.js 快取標籤與 Kanorio 的快取標籤是天作之合。頁面從 Next.js 快取進行渲染，當有人在 Kanorio 發佈內容時，Webhook 會在幾秒鐘內重新驗證所有使用該變更內容的頁面。

本指南使用 App Router 與 Next.js 16，其中 middleware 稱為 proxy.ts。

1. 環境變數

# .env.local
NEXT_PUBLIC_KANORIO_SITE_URL="https://s-xxxxxxxxxxxx.kanorio.com"

# server only
KANORIO_WEBHOOK_SECRET="whsec_..."
KANORIO_PREVIEW_TOKEN="knr_pv_..."

請使用來自網站設定 › 開發者的永久系統網址。Webhook 密鑰來自您在第 4 步建立的端點。預覽權杖為選填，且僅在伺服器端使用。

2. 共用的 fetch 輔助函式

lib/kanorio.ts 會為每次讀取加上 Kanorio 的快取標籤，並在草稿模式開啟時切換至草稿。標籤必須在 fetch 前已知，因此請使用 SDK 的 cacheTag 輔助函式來建立它們（它們帶有 Webhook 處理程式使用的 kanorio: 前綴）；回應本身的 X-Kanorio-Cache-Tags 標頭會列出完整集合，包含麵包屑祖先與展開的參照，適用於可在 fetch 後進行標記的框架。

// lib/kanorio.ts
import { draftMode } from "next/headers";
import { prefixCacheTags } from "@kanorio/sdk";

const SITE_URL = process.env.NEXT_PUBLIC_KANORIO_SITE_URL!;

export async function kanorio<T>(path: string, tags: string[]): Promise<T | null> {
  const { isEnabled: isDraft } = await draftMode();
  const url = new URL(`/api/v1${path}`, SITE_URL);
  if (isDraft) url.searchParams.set("preview", "1");

  const res = await fetch(
    url,
    isDraft
      ? { headers: { "X-Kanorio-Preview": process.env.KANORIO_PREVIEW_TOKEN! }, cache: "no-store" }
      : { next: { tags: prefixCacheTags(tags) } }
  );
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`Kanorio ${res.status} for ${path}`);
  return (await res.json()) as T;
}

3. 渲染文章

// app/blog/page.tsx
import Link from "next/link";
import { cacheTag } from "@kanorio/sdk";
import { kanorio } from "@/lib/kanorio";

type Post = { id: string; slug: string; fieldData: { title: string; excerpt: string | null } };

export default async function BlogIndex() {
  const page = await kanorio<{ data: Post[]; nextCursor: string | null }>(
    "/collections/blog/items?sort=-publishedAt&limit=20&fields=title,excerpt",
    [cacheTag.collection("blog")]
  );
  return (
    <ul>
      {page?.data.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.fieldData.title}</Link>
        </li>
      ))}
    </ul>
  );
}

// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { cacheTag } from "@kanorio/sdk";
import { kanorio } from "@/lib/kanorio";

type Asset = { url: string; width: number | null; height: number | null; alt: string | null; placeholder?: string };
type PostResponse = {
  item: { id: string; fieldData: { title: string; cover_image: string | null }; contentHtml?: string };
  assets: Record<string, Asset>;
};

export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  // Single items are tagged with the collection's item tag, not the list tag, so publishing another post does not evict this one
  const data = await kanorio<PostResponse>(
    `/collections/blog/items/${encodeURIComponent(slug)}?expand=authors,categories&formats=html`,
    [cacheTag.collectionItems("blog")]
  );
  if (!data) notFound();

  const { item, assets } = data;
  const cover = item.fieldData.cover_image ? assets[item.fieldData.cover_image] : undefined;
  return (
    <article>
      <h1>{item.fieldData.title}</h1>
      {cover && <img src={cover.url} alt={cover.alt ?? ""} width={cover.width ?? undefined} height={cover.height ?? undefined} />}
      {item.contentHtml && <div dangerouslySetInnerHTML={{ __html: item.contentHtml }} />}
    </article>
  );
}

4. 發佈時重新驗證

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import { createRevalidateHandler } from "@kanorio/sdk";

export const POST = createRevalidateHandler({
  signingSecret: process.env.KANORIO_WEBHOOK_SECRET!,
  revalidateTag: (tag) => revalidateTag(tag),
});

在網站設定 › Webhooks 下註冊 https://www.example.com/api/revalidate，並訂閱 collection、page 與 localization 事件。處理程式會驗證簽章，並重新驗證 data.cacheTags 中所有帶有相同 kanorio: 前綴的標籤。單一文章上線會重新整理該文章頁面與所有語系的部落格索引；翻譯上線則僅重新整理該語系。請參閱 Webhooks。

5. 從後台進入草稿模式

在開發者設定中，將前端網址設為外部商店網址。後台的「檢視網站」按鈕隨即會以帶有短效預覽權杖的 ?kp= 開啟您的前端。一個路由處理程式會將其轉換為草稿模式工作階段：

// app/api/draft/route.ts
import { draftMode } from "next/headers";
import { createPreviewRouteHandler } from "@kanorio/sdk/preview";

export const GET = createPreviewRouteHandler({
  siteUrl: process.env.NEXT_PUBLIC_KANORIO_SITE_URL,
  enableDraftMode: async () => (await draftMode()).enable(),
});

它會使用 Kanorio 驗證權杖，將其儲存在 HttpOnly Cookie 中，防範開放式重新導向，並重新導向至該頁面。在 proxy.ts 中，將帶有 ?kp= 的請求發送至 /api/draft?kp=…&redirect=<path>。在 lib/kanorio.ts 中，您可以使用 tokenFromCookieHeader 從 Cookie 讀取權杖，而非使用環境變數。當權杖過期時，API 會回傳 401；請停用草稿模式並退回至已發佈內容。

6. SEO 檔案、重新導向與爬蟲規則

從您自己的網域提供 sitemap、robots.txt、llms.txt 與 feeds：

// next.config.ts
import { seoRewrites } from "@kanorio/sdk";

export default {
  async rewrites() {
    return seoRewrites({ siteUrl: process.env.NEXT_PUBLIC_KANORIO_SITE_URL!, framework: "next" });
  },
};

在邊緣運算層套用擁有者在後台設定的重新導向與 AI 爬蟲規則，並提供 IndexNow 金鑰檔案：

// proxy.ts
import type { NextFetchEvent, NextRequest } from "next/server";
import { createKanorioMiddleware } from "@kanorio/sdk/edge";

const kanorioEdge = createKanorioMiddleware({ siteUrl: process.env.NEXT_PUBLIC_KANORIO_SITE_URL! });

export function proxy(request: NextRequest, event: NextFetchEvent) {
  return kanorioEdge.handleRequest(request, event);
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

Middleware 每分鐘會重新整理規則，因此後台的變更無需重新部署即可生效。重新導向規則會優先比對精確路徑，接著是長度最長的 /* 萬用字元前綴，與 Kanorio 託管網站的比對方式相同。靜態匯出 (output: "export") 無法執行 proxy.ts；請改在您的主機上設定重新導向。

7. 語系

多語言網站會在根目錄提供主要語系，並在擁有者選擇的網址前綴下提供其他語系，例如 /en/about。GET /api/v1/site 會在 locales[] 中列出它們與 pathPrefix，且每次讀取都接受 locale（代碼或前綴）。未翻譯的欄位會退回至主要文字，回應會在 resolvedLocale 中說明服務內容，並在 availableLocales 中說明哪些語系有翻譯。

createKanorioMiddleware 已處理邊緣規則：第一個區段為主要語系代碼的請求（如 /zh-hant/about）會被重新導向至根路徑，/en/llms.txt、/en/llms-full.txt 與 /en/rss.xml 會由 Content Delivery API 提供，且重新導向規則會比對不含前綴的路徑。請使用與 Middleware 相同的輔助函式在路由中讀取語系：

// app/[[...path]]/page.tsx
import type { Metadata } from "next";
import { buildAlternates, requestLocaleOf } from "@kanorio/sdk";
import { kanorio } from "@/lib/kanorio";

const SITE_URL = "https://www.example.com";

type Site = { primaryLocale: string | null; locales: Array<{ locale: string; isPrimary: boolean; pathPrefix: string | null }> };
type PageResponse = {
  page: { id: string; slug: string; title: string; resolvedLocale?: string; availableLocales?: string[]; localePaths?: Record<string, string>; sections: unknown[] };
};

async function load(path: string[] | undefined) {
  const pathname = `/${(path ?? []).join("/")}`;
  const site = (await kanorio<Site>("/site", ["site"]))!;
  const { locale, pathname: path0 } = requestLocaleOf(pathname, site);
  const query = locale === site.primaryLocale ? "" : `?locale=${encodeURIComponent(locale)}`;
  const data = await kanorio<PageResponse>(`/pages${path0 === "/" ? "/home" : path0}${query}`, []);
  return { site, locale, path0, data };
}

export async function generateMetadata({ params }: { params: Promise<{ path?: string[] }> }): Promise<Metadata> {
  const { site, locale, path0, data } = await load((await params).path);
  if (!data) return {};
  const alternates = buildAlternates({
    siteUrl: SITE_URL,
    site,
    path: path0,
    requestLocale: locale,
    resolvedLocale: data.page.resolvedLocale,
    availableLocales: data.page.availableLocales,
    localePaths: data.page.localePaths,
  });
  return { title: data.page.title, alternates: { canonical: alternates.canonical, languages: alternates.languages } };
}

每個語系可擁有自己的頁面別名，因此請將回應的 localePaths 傳遞給 buildAlternates 與 languageSwitcher。頁面端點也接受其他語系的網址路徑，並回傳該要求語系下的 page.slug；當它與網址不同時，請呼叫 permanentRedirect 進行導向。

buildAlternates 遵循與託管網站相同的規則：每個語系版本皆為其自身的標準網址 (canonical)，僅列出有該頁面翻譯的語系，x-default 指向主要語系，而以退回模式（該語系尚未翻譯）提供的頁面會取得主要語系的標準網址且無 hreflang。languageSwitcher({ siteUrl, site, path }) 會回傳語言選單的連結。請使用回應本身的快取標籤（帶有 @<locale>）標記語系特定的 fetch，翻譯上線時僅會重新整理該語系。

8. 檢查設定

npx @kanorio/cli doctor --site ws_example123

doctor 會檢查 SEO 檔案、JSON-LD、IndexNow 金鑰、內容同步、頁面瀏覽報告與 Webhooks。在多語言網站上，它還會檢查每個語系的頁面是否能在其前綴下透過翻譯後的標題存取、hreflang 是否列出所有上線語系，以及 /{prefix}/llms.txt 是否已提供。

讓權杖遠離瀏覽器

公開讀取無需權杖，草稿預覽則在伺服器端使用唯讀的 knr_pv_ 權杖。切勿將 knr_pat_ 權杖匯入用戶端元件或 NEXT_PUBLIC_ 變數中。