Next.js

给定制 Next.js 网站添加一套已经具备 SEO 能力的 Surpasso 博客。

Next.js 是开发网站的工具，不是一个统一托管的网站平台，因此没有“登录 Next.js 并授权”的通用按钮。网站会从服务端安全读取 Surpasso 中已经发布的文章，再使用自己的设计展示内容。

Surpasso Starter 已包含 /blog 列表、文章详情页、SEO Metadata、Sitemap、服务端缓存和受保护的缓存刷新接口。草稿保留在 Surpasso，网站只能读取正式发布的文章。

开始前需要准备

需要一个 Next.js App Router 项目，以及修改代码和部署环境的权限。可以让开发者完成，也可以把后面的提示交给 AI 编程工具。

1. 创建连接

在 Surpasso 打开 Workspace → Integrations。
选择 Next.js。
填写容易识别的名称，点击 创建密钥并继续。
立即复制 Content API Key，完整密钥只显示一次。

如果密钥泄露，请在 Surpasso 中轮换密钥，旧密钥会立即失效。

2. 添加服务端环境变量

本地开发时加入 .env.local，部署时加入网站的服务端环境：

SURPASSO_URL=https://surpasso.ai
SURPASSO_CONTENT_API_KEY=sp_content_replace_me
SURPASSO_REVALIDATE_SECRET=choose_a_separate_random_secret

不要给 Content API Key 使用 NEXT_PUBLIC_ 前缀，否则密钥可能暴露给访客。

3. 读取已发布文章

在 Server Component 或仅服务端使用的方法中读取：

import 'server-only';

const baseUrl = process.env.SURPASSO_URL!;
const apiKey = process.env.SURPASSO_CONTENT_API_KEY!;

export async function listArticles() {
  const response = await fetch(`${baseUrl}/api/content/v1/articles?limit=50`, {
    headers: { authorization: `Bearer ${apiKey}` },
    next: { revalidate: 3600, tags: ['surpasso-content'] },
  });
  if (!response.ok) throw new Error('Could not load Surpasso articles');
  return response.json();
}

export async function getArticle(slug: string) {
  const response = await fetch(
    `${baseUrl}/api/content/v1/articles/${encodeURIComponent(slug)}`,
    {
      headers: { authorization: `Bearer ${apiKey}` },
      next: { revalidate: 3600, tags: ['surpasso-content'] },
    }
  );
  if (response.status === 404) return null;
  if (!response.ok) throw new Error('Could not load the Surpasso article');
  return response.json();
}

文章详情包含标题、摘要、HTML 和 Markdown 正文、SEO 标题、SEO 描述、Canonical URL、封面图、分类、标签和更新时间。

4. 添加博客页面

参考实现位于 examples/nextjs-surpasso-starter：

app/blog/page.tsx
app/blog/[slug]/page.tsx
app/sitemap.ts
app/api/revalidate/route.ts
lib/surpasso.ts

把文件复制到 App Router 项目中的对应位置，再按现有网站调整样式。读取数据的方法必须保留在服务端。

5. 测试完整流程

启动 Next.js 网站并打开 /blog。
在 Surpasso 正式发布一篇测试文章，不要只创建草稿。
刷新 /blog 并打开文章详情页。
检查标题、正文、图片、SEO Metadata 和 Canonical URL。
打开 Sitemap，确认其中已经出现文章网址。

文章没有立即出现时，可以调用 Starter 中受保护的刷新接口，或等待缓存时间结束。

创建、更新和发布全部通过后，独立 Next.js Starter 显示生产 Content API 文章。

交给 AI 编程工具完成

复制下面的提示，但不要把真实 API Key 放进提示里：

请给这个现有的 Next.js App Router 项目添加一个由 Surpasso 提供内容的博客。

要求：
1. SURPASSO_CONTENT_API_KEY 只能保存在服务端，不要使用 NEXT_PUBLIC_。
2. 从 SURPASSO_URL/api/content/v1/articles?limit=50 读取列表。
3. 从 SURPASSO_URL/api/content/v1/articles/{slug} 读取详情。
4. 服务端请求使用 Authorization: Bearer ${SURPASSO_CONTENT_API_KEY}。
5. 添加 /blog 和 /blog/[slug] 页面，并保持网站现有设计。
6. 安全渲染返回的文章 HTML。
7. 生成 title、description、canonical、Open Graph 和 Twitter metadata。
8. 把已发布文章加入 sitemap。
9. 使用 "surpasso-content" 标签缓存，并添加受保护的刷新接口。
10. 文章不存在时调用 notFound()，API 暂时不可用时显示清晰错误。

服务端环境变量：
SURPASSO_URL=https://surpasso.ai
SURPASSO_CONTENT_API_KEY=<我会自己加入部署环境>
SURPASSO_REVALIDATE_SECRET=<我会自己添加一个单独密钥>

修改前先检查并复用项目现有的路由、样式、Metadata 和 Sitemap 习惯。

安全检查

Content API Key 只能放在服务端环境变量中。
不要从 Client Component 或浏览器脚本直接请求 Surpasso。
密钥出现在 Git、浏览器代码或截图中时立即轮换。
缓存刷新接口使用另一个单独密钥保护。
接口详细说明请查看 Content API 教程。

Next.js

On this page