Astro 集成指南

Astro 默认零 JavaScript 的静态与混合渲染架构，非常适合用来打造极速的品牌形象网站与博客。搭配 Kanorio 的 Content Delivery API，您可以在 .astro 组件顶部直接用几行 fetch 读取所有已发布的内容集合与文章。

1. 设置环境变量

在 Astro 项目的 .env 加入您的 Kanorio 网站永久系统网址：

PUBLIC_KANORIO_SITE_URL="https://s-k4m9x2p7q8w3.kanorio.com"

---

2. 读取作品案例或服务集合（src/pages/projects.astro）

在 .astro 文件的 Frontmatter 区块直接调用 /api/v1/collections/{key}/items，并通过顶层 assets 对照表获取图片网址：

---
const SITE_URL = import.meta.env.PUBLIC_KANORIO_SITE_URL;
const res = await fetch(`${SITE_URL}/api/v1/collections/projects/items?sort=-publishedAt&limit=20`);
const { items, assets } = await res.json();
---

<section>
  <h1>作品案例</h1>
  <div class="grid">
    {items.map((item) => {
      const cover = assets[item.fieldData.cover];
      return (
        <article>
          {cover && (
            <img
              src={cover.url}
              alt={cover.alt ?? item.fieldData.title}
              width={cover.width ?? undefined}
              height={cover.height ?? undefined}
              loading="lazy"
            />
          )}
          <h2>{item.fieldData.title}</h2>
          <p>{item.fieldData.summary}</p>
        </article>
      );
    })}
  </div>
</section>

---

3. 建立博客文章列表与内页（src/pages/blog/[slug].astro）

读取 blog 系统集合时加上 formats=html 与 expand=authors,categories，就能直接把 item.contentHtml 交给 Astro 的 set:html 渲染，并用 item.toc 生成文章目录：

---
const SITE_URL = import.meta.env.PUBLIC_KANORIO_SITE_URL;

export async function getStaticPaths() {
  const siteUrl = import.meta.env.PUBLIC_KANORIO_SITE_URL;
  const res = await fetch(`${siteUrl}/api/v1/collections/blog/items?fields=title&limit=100`);
  const { items } = await res.json();
  return items.map((post) => ({ params: { slug: post.slug } }));
}

const { slug } = Astro.params;
const res = await fetch(
  `${SITE_URL}/api/v1/collections/blog/items/${encodeURIComponent(slug!)}?expand=authors,categories,tags&formats=html`
);
if (!res.ok) return Astro.redirect("/404");
const { item, assets } = await res.json();
const coverId = (item.fieldData.cover_image ?? "").replace(/^asset:/, "");
const cover = assets[coverId];
---

<article>
  <h1>{item.fieldData.title}</h1>
  {cover && <img src={cover.url} alt={cover.alt ?? item.fieldData.title} />}

  {item.toc?.length > 0 && (
    <nav aria-label="文章目录">
      <ul>
        {item.toc.map((h) => (
          <li data-level={h.level}>
            <a href={`#${h.id}`}>{h.label}</a>
          </li>
        ))}
      </ul>
    </nav>
  )}

  <div class="prose" set:html={item.contentHtml} />
</article>

---

4. 串接联系表单与自动更新

1. 联系我们表单： 在您的联系页面挂载表单时，先从浏览器调用 GET ${PUBLIC_KANORIO_SITE_URL}/api/v1/forms/{formId}/challenge，提交时再 POST 到 /api/v1/forms/{formId}/submit（完整步骤见）。记得将您的正式域名加入后台“网站设置 › 开发者”的“允许的来源”。
2. 内容发布时自动更新：
   • SSR 模式（@astrojs/cloudflare 或 @astrojs/node）：可直接透传或比对响应的 x-kanorio-public-version 与 X-Kanorio-Cache-Tags。
   • SSG 静态构建模式：在 Vercel 或 Cloudflare Pages 建立一条 Deploy Hook 网址，贴到 Kanorio 后台“网站设置 › Webhooks”并订阅 collections.item.published、collections.item.unpublished、collections.item.deleted 与 collections.items.bulkChanged，每次发布文章或更新集合就会自动触发重新部署。

相关文档