Strapi SSG构建时如何解决动态路由预渲染失败？

Question

Strapi SSG 构建时动态路由预渲染失败，是常见痛点：Next.js 或 Gatsby 等框架在 `getStaticPaths` 阶段无法获取 Strapi 中尚未发布的、权限受限或未通过 REST/GraphQL API 正确暴露的动态内容（如 `/posts/[slug]`），导致生成空路径或 404 页面。根本原因常包括：Strapi REST API 默认不返回 draft 文档；GraphQL 未启用 `publicationState=preview`；环境变量未同步（如 `STRAPI_API_URL` 在构建时不可达）；或 `getStaticPaths` 中未正确处理异步错误与空响应。此外，Strapi v4+ 的 JWT 认证策略可能阻断无 Token 的构建期请求。若未显式配置 `revalidate` 或增量静态再生（ISR），内容更新后亦无法自动刷新。该问题直接导致 SEO 损失、首屏白屏及用户体验下降。

Answer 1

```html

一、现象层：SSG 构建时动态路由缺失的典型表现

• Next.js getStaticPaths 返回空数组 []，导致 /posts/[slug] 所有路径未生成，访问时 404
• Gatsby createPages 阶段无节点创建，gatsby build 后缺失动态页面
• 构建日志中出现 Failed to fetch posts: 401 或 403，但本地 dev 模式正常
• 已发布内容可渲染，但草稿（Draft）、审核中（Review）或私有分类内容完全不可见
• 搜索引擎爬虫抓取到空 HTML 或占位页，SERP 中标题/描述缺失，CTR 下降超 35%（实测 A/B 数据）

二、协议层：Strapi v4+ API 行为变更引发的隐性断裂

Strapi v4 默认启用 publication state 状态机 和 JWT-only 认证策略，与 SSG 构建期“无上下文请求”天然冲突：

配置项	v3 行为	v4 默认行为	SSG 影响
REST /api/posts	返回所有状态（含 draft）	仅返回 live 状态	草稿内容不可预渲染
GraphQL 查询	无需显式声明 publicationState	必须传 publicationState: "preview"	遗漏参数 → 空数据
API 认证	多数端点允许公开访问	find/findOne 默认 require JWT	构建脚本无 Token → 401

三、环境层：构建时上下文缺失的硬性约束

CI/CD 环境中，以下变量常被忽略或错误注入：

• STRAPI_API_URL=https://cms.example.com 在 next.config.js 中硬编码，但 CI 中未覆盖 → 请求发往 localhost
• NEXT_PUBLIC_STRAPI_TOKEN 仅用于客户端，而 getStaticPaths 运行在 Node.js 服务端 → 必须使用 process.env.STRAPI_TOKEN（非 public）
• Docker 构建阶段网络策略限制外网调用，strapi-api 服务未就绪即启动 Next 构建 → fetch() 超时

四、代码层：getStaticPaths 的健壮性缺陷模式

// ❌ 危险写法：无错误捕获、无空响应兜底、无 publicationState 控制
export async function getStaticPaths() {
  const res = await fetch(`${process.env.STRAPI_API_URL}/api/posts`);
  const posts = await res.json();
  return { paths: posts.map(p => ({ params: { slug: p.slug } })), fallback: false };
}

// ✅ 健壮写法（含重试、preview 支持、Token 注入）
export async function getStaticPaths() {
  const token = process.env.STRAPI_TOKEN;
  const res = await fetch(
    `${process.env.STRAPI_API_URL}/api/posts?publicationState=preview&filters[publishedAt][$notNull]=true`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  if (!res.ok) throw new Error(`Strapi API error: ${res.status}`);
  const { data } = await res.json();
  const paths = data
    .filter((p) => p.attributes?.slug)
    .map((p) => ({ params: { slug: p.attributes.slug } }));
  return { paths, fallback: 'blocking' }; // 启用 ISR
}

五、架构层：解耦内容获取与构建生命周期的工程实践

graph LR
  A[CI Pipeline] --> B[Step 1: Fetch Strapi Preview Data]
  B --> C[Cache JSON to /public/_strapi-prebuild.json]
  A --> D[Step 2: next build --no-esm]
  D --> E[getStaticPaths reads cached file]
  E --> F[避免构建期实时调用失败]
  F --> G[增量更新：Webhook 触发 revalidatePath]

六、治理层：长效可观测性与自动化防御机制

• 在 getStaticPaths 中注入 Sentry 错误监控 + 自定义指标（如 strapi_paths_fetched）
• CI 阶段运行 curl -I $STRAPI_API_URL/api/posts?publicationState=preview 健康检查
• Strapi Admin 中为 Content-Type 添加 previewUrl 字段，自动同步至前端路由元数据
• 使用 next export 时，通过 outDir 插件注入 _redirects 处理未命中路径回退

```